Puppeteer

API | FAQ | Contributing

Puppeteer is a Node library which provides a high-level API to control headless Chrome over the DevTools Protocol. It can also be configured to use full (non-headless) Chrome.

What can I do?

Most things that you can do manually in the browser can be done using Puppeteer! Here are a few examples to get you started:

• Generate screenshots and PDFs of pages.
• Crawl a SPA and generate pre-rendered content (i.e. "SSR").
• Scrape content from websites.
• Automate form submission, UI testing, keyboard input, etc.
• Create an up-to-date, automated testing environment. Run your tests directly in the latest version of Chrome using the latest JavaScript and browser features.
• Capture a timeline trace of your site to help diagnose performance issues.

Getting Started

Installation

Puppeteer requires Node version 7.10 or greater

To use Puppeteer in your project, run:

yarn add puppeteer
# or "npm i puppeteer"

Note

: When you install Puppeteer, it downloads a recent version of Chromium (~71Mb Mac, ~90Mb Linux, ~110Mb Win) that is guaranteed to work with the API. However, you can tell Puppeteer to use any Chromium executable installed on the machine.

Usage

Puppeteer will be familiar to using other browser testing frameworks. You create an instance of Browser, open pages, and then manipulate them with Puppeteer's API.

Example - navigating to https://example.com and saving a screenshot as example.png:

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

browser.close();
})();

or, without async/await:

const puppeteer = require('puppeteer');

puppeteer.launch()
  .then(browser => browser.newPage())
  .then(page => {
    page.goto('https://example.com').then(response => {
       page.screenshot({path: 'example.png'}).then(buffer => {
         browser.close();
       });
    });
  });

Puppeteer sets an initial page size to 800px x 600px, which defines the screenshot size. The page size can be customized with Page.setViewport().

Example - create a PDF.

const puppeteer = require('puppeteer');

(async() => {

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com', {waitUntil: 'networkidle'});
await page.pdf({path: 'hn.pdf', format: 'A4'});

browser.close();
})();

See Page.pdf() for more information about creating pdfs.

Default runtime settings

1. Uses Headless mode

Puppeteer launches Chromium in headless mode. To launch a full version of Chromium, set the 'headless' option when creating a browser:

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

2. Runs a bundled version of Chromium

By default, Puppeteer downloads and uses a specific version of Chromium so its API is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome, pass in the executable's path when creating a Browser instance:

const browser = new Browser({executablePath: '/path/to/Chrome'});

See Browser for more information.

3. Creates a fresh user profile

Puppeteer creates its own Chromium user profile which it cleans up on every run.

API Documentation

Explore the API documentation and examples to learn more.

Contributing to Puppeteer

Check out contributing guide to get an overview of puppeteer development.

FAQ

Q: What is Puppeteer?

Puppeteer is a light-weight Node module to control headless Chrome using the latest version of the DevTools Protocol.

Q: Which Chromium version does Puppeteer use?

Look for chromium_revision in package.json.

Puppeteer bundles Chromium to insure that the latest features it uses are guaranteed to be available. As the DevTools protocol and browser improve over time, Puppeteer will be updated to depend on newer versions of Chromium.

Q: Does Puppeteer work with headless Chromium?

Yes. Puppeteer runs Chromium in headless mode by default.

Q: Why do most of the API methods return promises?

Since Puppeteer's code is run by Node, it exists out-of-process to the controlled Chromium instance. This requires most of the API calls to be asynchronous to allow the necessary roundtrips to the browser.

Q: What is the difference between Puppeteer, Selenium / WebDriver, and PhantomJS?

Selenium / WebDriver is a well-established cross-browser API that is useful for testing cross-browser support.

Puppeteer works only with Chrome. However, many teams only run unit tests with a single browser (e.g. Phantom). In non-testing use cases, Puppeteer provides a powerful but simple API because it's only targeting one browser that enables you to rapidly develop automation scripts.

PhantomJS uses an older version of WebKit as it's browser rendering engine. Puppeteer uses the latest versions of Chromium, which use the Blink rendering engine.

Q: How is this different than Chromeless?

Chromeless and Puppeteer are similar projects. Both are Node libraries that provide a high-level JS APIs to control headless Chrome.

Chromeless is intended to work well with AWS Lambda to deploy parallel testing in a serverless setup. Under the hood, it uses chrome-remote-interface to interface with the DevTools Protocol. In the future, it could use Puppeteer's API.

Puppeteer is smaller in size (ignoring the bundled version of Chrome) and does not use dependencies to interface with Chrome. It's API is inspired by other popular automated testing libraries like PhantomJS and NightmareJS.

Q: Who maintains Puppeteer?

The Chrome DevTools team maintains the library, but we'd love your help and expertise on the project! See Contributing.

Q: Why is the Chrome team building Puppeteer?

The goals are the project are simple:

• Provide a slim (1.7 Mb), canonical library that highlights the capabilities of the DevTools Protocol.
• Provide a reference implementation for similar testing libraries. Eventually, these other frameworks could adopt Puppeteer as their foundational layer.
• Grow the adoption of headless/automated browser testing.
• Help dogfood new DevTools Protocol features...and catch bugs!
• Learn more about the pain points of automated browser testing and help fill those gaps.