Skip to main content

How to Take Screenshots with Puppeteer using Headless Chrome Browser

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 downloads and drives Chrome for Testing by default, and it can drive Firefox as well (pptr.dev, November 2026). When this post was first written in 2017 it supported Chrome only.

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: current Puppeteer releases (version 25 in November 2026) need Node 22.12 or newer (pptr.dev system requirements, November 2026). This post originally said Node v6.4.0, which was the 2017 minimum.

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.

visual regression testing tool

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();
})();

To wait until the page has stopped loading late resources before the screenshot, pass the options as the second argument of page.goto. networkidle0 waits until there are no network connections for 500 ms; networkidle2 allows up to two (pptr.dev, November 2026). The older networkidle value and networkIdleTimeout option no longer exist, and slowMo is a launch option, not a goto option.

await page.goto('https://example.com', {
  timeout: 120000,
  waitUntil: ['load', 'networkidle0'],
});

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, exported as KnownDevices (the old puppeteer/DeviceDescriptors module was replaced). Pass one of them to page.emulate() to render the page with that device’s viewport and user agent:

const { KnownDevices } = require('puppeteer');

await page.emulate(KnownDevices['iPhone 15 Pro']);
await page.screenshot({ path: 'example-iphone.png' });

Puppeteer’s API is similar to Selenium WebDriver, but it drives Chrome and Firefox only, while WebDriver works 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.text()));

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

LoadFocus is a cloud testing platform for:

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.

Chris

Head of Content at LoadFocus

Chris leads content and oversees development across the services this blog covers. The guides and tool comparisons here come out of the same decisions that shape what ships.

Weekly tips right in your inbox.

Don’t miss out on the latest testing tips and tricks, tools and news related to software testing.

Already +20,000 members in the list.

The Load Testing Platform with AI That Explains Your Results

Load test websites and APIs from 25 cloud regions, monitor page speed and uptime, and get AI analysis that explains your results in plain English.

Cloud load testing, website speed and API monitoring in one place.

Hi there! Can I share a cool thing I'm working on with you?

A software testing newsletter that sparks joy.

Our goal is to create helpful content for software developers and testers.

If you're not into it, you can unsubscribe instantly.