How to Take Screenshots with Puppeteer using Headless Chrome Browser

Key takeaways

• Puppeteer captures viewport, full-page or single-element screenshots.
• Set the viewport explicitly, or headless defaults produce a different image to what you expect.
• Wait for fonts and images before capturing, otherwise the shot is of a half-rendered page.

What is Puppeteer? Puppeteer is Node library that you can use in order to control Headless Chrome with the DevTools Protocol.

The Chrome DevTools Protocol allows for tools to instrument, inspect, debug and profile for Chromium and Chrome browsers.

Puppeteer – Headless Chrome Node API works only with Chrome and uses the latest versions of Chromium.

Chromium is an open-source browser project that forms the basis for the Chrome web browser. One of the biggest differences between the two browsers is that, while Chrome is based on Chromium, Google adds some of proprietary features to Chrome, features like automatic updates and support for additional video formats. Other features like usage-tracking or “user metrics” feature can be found only in Chrome browser.

Note: Puppeteer requires at least Node v6.4.0, but the examples below use async/await which is only supported in Node v7.6.0 or greater.

Node.js has a simple module loading system. In Node.js, files and modules are in one-to-one correspondence (each file is treated as a separate module).

You can use Visual Regression Testing to take website screenshots and compare the generated images and identify differences pixel by pixel, a comparison image will be shown next to the result’s screenshot that highlights the differences in red.

Install Puppeteer

Here is how to install puppeteer from NPM Modules Registry (npm is the package manager for JavaScript):

npm i puppeteer

Below are code snippets on how to use Puppeteer – Headless Chrome Node API in order to take screenshots of your website.

Example – navigating to https://example.com and saving a screenshot as a PNG file named example.png:

Generate screenshots with Puppetteer

const puppeteer = require('puppeteer'); (async () = { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('https://example.com'); await page.screenshot({path: 'example.png'}); await browser.close(); })();

await page.goto('https://example.com'), {
timeout: 120000,
slowMo: 2000,
waitUntil: ['load', 'networkidle'],
networkIdleTimeout: 5000,
});

By default, Puppeteer take screenshots of the viewport (the area which is visible by default when you open a website).

In order to take a screenshot of the full web page, you need to add the fullPage parameter to the screenshot method:

await page.screenshot({ path: 'example.png', fullPage: true });

Here is an example on how to take a screenshot of a webpage with Puppeteer using a customer web page size.
You just need to pass the width and height of the viewport in order for the browser to resize the web page to the desired size.

export async function takeScreenshot(page, filename, width, height) {
await page.setViewport({ width, height });

await page.screenshot({ path: `${filename}-${width}-${height}.png`, fullPage: true });
}

Here is how to call the above custom screenshot method:

await takeScreenshot(page, 'example.png', 320, 480);

Puppeteer, also provides a list of Mobile Devices as a list of objects called DeviceDescriptors.
In order to emulate a web page in a mobile emulator, with specific characteristics, you can import the
pre-defined list of mobile emulators from puppeteer/DeviceDescriptors

const devices from 'puppeteer/DeviceDescriptors'; 

Puppeteer’s API is very similar to Selenium WebDriver, but works only with Google Chrome, while WebDriver work with most popular browsers.

More details on how to locate elements to use in order to interact with Puppeteer or Selenium WebDriver.

Debugging and Troubleshooting Puppeteer

1. Non Headless Mode – for debugging purposes, sometimes it’s useful to see what the browser is displaying. Instead of launching in headless mode, launch a full version of Chrome using headless: false when you launch the browser using Puppeteer:

const browser = await puppeteer.launch({headless: false});

2. Slow down screenshot generation – the slowMo option slows down Puppeteer operations by the specified amount of milliseconds. It’s another way to understand better what’s happening with the code you’ve written and debug easier.

const browser = await puppeteer.launch({
headless: false,
slowMo: 250 // slow down by 250ms
});

3. Capture browser’s console output

page.on('console', msg => console.log('PAGE LOG:', ...msg.args));

await page.evaluate(() => console.log(`url is ${location.href}`));

4. Enable verbose logging – All public API calls and internal protocol traffic will be logged via the debug module under the puppeteer namespace.

# Basic verbose logging

env DEBUG="puppeteer:*" node script.js

You can use Visual Regression Testing to take website screenshots and compare the generated images and identify differences pixel by pixel, a comparison image will be shown next to the result’s screenshot that highlights the differences in red.

LoadFocus is a cloud testing platform for:

• Load Testing
• Website Speed Testing
• Mobile Testing
• Automated Website Testing
• Visual Regression Testing

Frequently Asked Questions

What can Puppeteer capture?

The viewport by default, the whole page with fullPage, or a single element by calling screenshot on the element handle. The element form is the useful one for visual checks on a specific component.

Why does the screenshot look different from my browser?

Because headless Chrome uses its own default viewport rather than your window. Set the viewport explicitly with setViewport so the image is reproducible, otherwise the shot changes with the environment.

How do I avoid capturing a half rendered page?

Wait for the things that arrive late: web fonts, images and any content fetched after load. Capturing on the load event alone tends to produce screenshots with unstyled text or missing images.

Related reading

• What Is Puppeteer?, A Tutorial on How to Use Puppeteer
• UI Regression Testing With Puppeteer and Headless Chrome
• How to Click on Element with Puppeteer and Chrome

headless browsers take screenshots with puppeteer use headless browser to generate screenshot