62cacbe5f5
This patch implements documentation linter, which leaves under `test/doclint` folder. The documentation linter works like this: 1. Parse javascript source code with esprima and construct a "documentation" out of source code 2. Generate HTML out of `api.md` and traverse the HTML with puppeteer. 3. Make sure javascript aligns nicely with HTML The documentation linter adds the following commands: - `yarn doc` - to test that documentation covers all the relevant apis - `yarn generate-toc` - to update the table-of-contents for the `api.md` |
||
|---|---|---|
| docs | ||
| examples | ||
| lib | ||
| phantom_shim | ||
| test | ||
| third_party | ||
| utils | ||
| .editorconfig | ||
| .eslintignore | ||
| .eslintrc.js | ||
| .gitignore | ||
| .travis.yml | ||
| CONTRIBUTING.md | ||
| index.js | ||
| install.js | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| yarn.lock | ||
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.png:
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:
- By default, Puppeteer runs a bundled Chromium browser. However, you can point Puppeteer to a different executable (example)
- Puppeteer creates its own Chromium user profile which it cleans up on every run.
- 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.
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.
Migration Guide
[TODO]