puppeteer/README.md

Puppeteer

Puppeteer is a Node library which provides a high-level API to control Chromium over the DevTools Protocol. Puppeteer is inspired by PhantomJS. Check our FAQ to learn more.

Installation

Get the source:

git clone https://github.com/GoogleChrome/puppeteer
cd puppeteer

Install the dependencies:

yarn

or use npm:

npm install

Note: Puppeteer bundles Chromium (~70Mb) which it is guaranteed to work with. However, you're free to point Puppeteer to any Chromium executable (example)

Getting Started

The following script navigates to https://example.com and saves a screenshot to example.jpg:

const Browser = require('Puppeteer').Browser;
const browser = new Browser();

browser.newPage().then(async page => {
  await page.navigate('https://example.com');
  await page.screenshot({path: 'example.jpg'});
  browser.close();
});

A few notes:

1. By default, Puppeteer runs a bundled Chromium browser. However, you can point Puppeteer to a different executable (example)
2. Puppeteer creates its own Chromium user profile which it cleans up on every run.
3. Puppeteer sets an initial page size to 400px x 300px, which defines the screenshot size. The page size can be changed with Page.setSize() method

API

API documentation is a work in progress.

Contributing

Check out our contributing guide

FAQ

Q: What is Puppeteer?

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

Q: Does Puppeteer work with headless Chromium?

Yes. Puppeteer bundles a version of Chromium and runs it in headless mode by default.

Q: How is Puppeteer different than PhantomJS?

While PhantomJS provides a JavaScript API to control a full-fledged browser (WebKit), Puppeteer is a light-weight Node module to control headless Chrome.

Other important differences:

• Uses an evergreen browser - Puppeteer uses headless Chromium, which means it can access all the latest web platform features offered by the Blink rendering engine.
• Improved debuggability - thanks to Node debugging in Chrome DevTools.

Q: Which Chromium version does Puppeteer use?

[TODO]

Q: How do I migrate from PhantomJS to Puppeteer?

There's no automatic way to migrate PhantomJS scripts to Node scripts with Puppeteer. For more information and some guidance, check out our migration guide.

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.

However, if you're using Node 8 or higher, async/await make life easier:

browser.newPage().then(async page => {
  await page.setViewportSize({width: 1000, height: 1000});
  await page.printToPDF('blank.pdf');
  browser.close();
});

Q: What is the "Phantom Shim"?

"Phantom Shim" is a layer built atop the Puppeteer API that simulates Phantom's environment. It was developed to run Phantom's tests and estimate the comprehensiveness Puppeteer's API.

At the moment, the shim employs unhealthy approaches (e.g. in-process code execution is emulated via nested event loops) to mimic Phantom's environment.

Migration Guide

[TODO]