Pageres

Capture website screenshots

Browser automationScreenshot
sindresorhus/pagerespageres

README

pageres

Coverage Status XO code style

Capture screenshots of websites in various resolutions. A good way to make sure your websites are responsive. It's speedy and generates 100 screenshots from 10 different websites in just over a minute. It can also be used to render SVG images.

See pageres-cli for the command-line tool.

Install


  1. ```sh
  2. npm install pageres
  3. ```

Note to Linux users: If you get a "No usable sandbox!" error, you need to enable system sandboxing.

Usage


  1. ```js
  2. import Pageres from 'pageres';

  4. await new Pageres({delay: 2})
  5. .source('https://github.com/sindresorhus/pageres', ['480x320', '1024x768'], {crop: true})
  6. .source('https://sindresorhus.com', ['1280x1024', '1920x1080'])
  7. .source('data:text/html,<h1>Awesome!</h1>', ['1024x768'])
  8. .destination('screenshots')
  9. .run();

  11. console.log('Finished generating screenshots!');
  12. ```

API


Pageres(options?)


options


Type: object

delay

Type: number (Seconds)\
Default: 0

Delay capturing the screenshot.

Useful when the site does things after load that you want to capture.

timeout

Type: number (Seconds)\
Default: 60

Number of seconds after which the request is aborted.

crop

Type: boolean\
Default: false

Crop to the set height.

css

Type: string

Apply custom CSS to the webpage. Specify some CSS or the path to a CSS file.

script

Type: string

Apply custom JavaScript to the webpage. Specify some JavaScript or the path to a file.

cookies

Type: `Array`

A string with the same format as a browser cookie or an object.

Tip: Go to the website you want a cookie for and copy-paste it from DevTools.

filename

Type: string\
Default: `'<%= url %>-<%= size %><%= crop %>'`

Define a customized filename using Lo-Dash templates.\
For example: `<%= date %> - <%= url %>-<%= size %><%= crop %>`.

Available variables:

- url: The URL in slugified form, eg.http://yeoman.io/blog/ becomes yeoman.io!blog
- size: Specified size, eg. 1024x1000
- width: Width of the specified size, eg. 1024
- height: Height of the specified size, eg. 1000
- crop: Outputs -cropped when the crop option is true
- date: The current date (YYYY-MM-DD), eg. 2015-05-18
- time: The current time (HH-mm-ss), eg. 21-15-11

incrementalName

Type: boolean\
Default: false

When a file exists, append an incremental number.

selector

Type: string

Capture a specific DOM element matching a CSS selector.

hide

Type: string[]

Hide an array of DOM elements matching CSS selectors.

username

Type: string

Username for authenticating with HTTP auth.

password

Type: string

Password for authenticating with HTTP auth.

scale

Type: number\
Default: 1

Scale webpage n times.

format

Type: string\
Default: png\
Values: 'png' | 'jpg'

Image format.

userAgent

Type: string

Custom user agent.

headers

Type: object

Custom HTTP request headers.

transparent

Type: boolean\
Default: false

Set background color to transparent instead of white if no background is set.

darkMode

Type: boolean\
Default: false

Emulate preference of dark color scheme.

launchOptions

Type: object\
Default: {}

Options passed to [puppeteer.launch()](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).

beforeScreenshot

Type: Function

The specified function is called right before the screenshot is captured, as well as before any bounding rectangle is calculated as part of options.element. It receives the Puppeteer [Page instance](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-page) as the first argument and the [browser instance](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-browser) as the second argument. This gives you a lot of power to do custom stuff. The function can be async.

Note: Make sure to not call page.close() or browser.close().

  1. ```js
  2. import Pageres from 'pageres';

  4. await new Pageres({
  5. delay: 2,
  6. beforeScreenshot: async (page, browser) => {
  7.   await checkSomething();
  8.   await page.click('#activate-button');
  9.   await page.waitForSelector('.finished');
  10. }
  11. })
  12. .source('https://github.com/sindresorhus/pageres', ['480x320', '1024x768', 'iphone 5s'], {crop: true})
  13. .destination('screenshots')
  14. .run();

  16. console.log('Finished generating screenshots!');
  17. ```

pageres.source(url, sizes, options?)


Add a page to screenshot.

url


Required\
Type: string

URL or local path to the website you want to screenshot. You can also use a data URI.

sizes


Required\
Type: string[]

Use a `x` notation or a keyword.

A keyword is a version of a device from this list.

You can also pass in the w3counter keyword to use the ten most popular resolutions from w3counter.

options


Type: object

Options set here will take precedence over the ones set in the constructor.

pageres.destination(directory)


Set the destination directory.

directory


Type: string

pageres.run()


Run pageres. Returns `Promise`.

Task runners


Check out grunt-pageres if you're using Grunt.

For Gulp and Broccoli, just use the API directly. No need for a wrapper plugin.

Built with Pageres


- Break Shot - Desktop app for capturing screenshots of responsive websites.

Related


- capture-website - A different take on screenshotting websites