Node.js API for Chrome
Go to file
Andrey Lushnikov 91cbe561ba Roll chromium to r488994
This patch rolls chromium past the r488926 which prevents chromium from
going to sleep on Mac OS X.

Fixes #100.
2017-07-24 18:28:34 -07:00
docs Rename 'maxTime' option of Page.navigate into 'timeout' 2017-07-22 16:32:57 -07:00
examples Rename Page's 'consolemessage' event into 'console' 2017-07-17 20:38:11 -07:00
lib Fix clicking offscreen horizontally (#105) 2017-07-24 16:14:32 -07:00
phantom_shim Mouse (#101) 2017-07-21 20:29:31 -07:00
test Roll chromium to r488994 2017-07-24 18:28:34 -07:00
third_party Inject file with sourceURL (#102) 2017-07-23 09:56:35 -07:00
utils Refactor Frame.waitForSelector method 2017-07-24 10:07:43 -07:00
.editorconfig Add lint script and editorconfig file 2017-06-21 14:11:52 -07:00
.eslintignore [doclint] Move doclint under utils/ 2017-07-13 00:28:52 -07:00
.eslintrc.js Convert var's to let's 2017-06-22 14:58:39 -07:00
.gitignore Intorduce Page.keyboard (#74) 2017-07-17 18:49:52 -07:00
.travis.yml Update libssn3 via .travis.yml 2017-06-21 14:11:52 -07:00
CONTRIBUTING.md Support HEADLESS env variable for unit tests 2017-07-19 19:36:22 -07:00
DeviceDescriptors.js Get rid of page.emulate() / page.emulatedDevices() methods 2017-07-20 23:53:06 -07:00
index.js Reformat code using 2 spaces 2017-06-21 14:11:52 -07:00
install.js [Downloader] Remove previous chromium revisions after roll 2017-07-12 14:48:42 -07:00
LICENSE Initial commit 2017-05-09 15:16:13 -07:00
package-lock.json Introduce DEBUG module 2017-07-17 15:15:07 -07:00
package.json Roll chromium to r488994 2017-07-24 18:28:34 -07:00
README.md Getting started run instructions 2017-07-18 11:13:29 -07:00
yarn.lock Implement documentation linter (#47) 2017-07-07 19:36:45 +03:00

Puppeteer Build Status

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.

Use Cases

  • Up-to-date testing environment that supports the latest Javascript features.
  • Crawl your site to generate pre-rendered content for your SPA.
  • Scrape content from websites.

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

To navigate to https://example.com and save a screenshot as example.png, save the following script as example.js and run it using node example.js:

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.png'});
  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.setViewportSize() 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.setViewport({width: 1000, height: 1000});
  await page.pdf({path: '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.

Puppeteer's process model is different than Phantom's. Puppeteer runs out-of-process to the browser, whereas Phantom runs in-process. To simulate in-process behavior, phantom_shim hacks Node's runtime with nested event loops) to simulate in-process operation. This might result in unpredictable side-effects and makes the shim unreliable for certain use cases situations.

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

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

Puppeteer is useful for single-browser testing. For example, 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.

Migration Guide

[TODO]