puppeteer/README.md

119 lines
4.7 KiB
Markdown
Raw Normal View History

# Puppeteer [![Build Status](https://travis-ci.com/GoogleChrome/puppeteer.svg?token=8jabovWqb8afz5RDcYqx&branch=master)](https://travis-ci.com/GoogleChrome/puppeteer)
2017-06-20 02:17:11 +00:00
Puppeteer is a Node library which provides a high-level API to control Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). Puppeteer is inspired by [PhantomJS](http://phantomjs.org/). Check our [FAQ](#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
2017-05-11 07:06:41 +00:00
2017-06-20 02:17:11 +00:00
Get the source:
2017-05-11 07:06:41 +00:00
```
git clone https://github.com/GoogleChrome/puppeteer
cd puppeteer
2017-06-20 02:17:11 +00:00
```
Install the dependencies:
```
yarn
```
or use `npm`:
```
npm install
2017-05-11 07:06:41 +00:00
```
2017-06-20 02:17:11 +00:00
> Note: Puppeteer bundles Chromium (~70Mb) which it is guaranteed to work with. However, you're free to point Puppeteer to any Chromium executable ([example](https://github.com/GoogleChrome/puppeteer/blob/master/examples/custom-chromium-revision.js))
## Getting Started
2017-05-11 07:06:41 +00:00
2017-06-21 03:14:10 +00:00
The following script navigates to https://example.com and saves a screenshot to *example.png*:
2017-05-11 07:06:41 +00:00
```javascript
2017-06-20 02:17:11 +00:00
const Browser = require('Puppeteer').Browser;
const browser = new Browser();
browser.newPage().then(async page => {
2017-06-20 02:17:11 +00:00
await page.navigate('https://example.com');
2017-06-21 03:14:10 +00:00
await page.screenshot({path: 'example.png'});
2017-06-20 02:17:11 +00:00
browser.close();
});
2017-05-11 07:06:41 +00:00
```
2017-06-20 02:17:11 +00:00
A few notes:
1. By default, Puppeteer runs a bundled Chromium browser. However, you can point Puppeteer to a different executable ([example](https://github.com/GoogleChrome/puppeteer/blob/master/examples/custom-chromium-revision.js))
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
2017-06-20 02:17:11 +00:00
## API
[API documentation](docs/api.md) is a work in progress.
2017-05-11 07:06:41 +00:00
## Contributing
2017-05-11 07:06:41 +00:00
Check out our [contributing guide](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md)
2017-05-11 07:06:41 +00:00
# FAQ
2017-05-11 07:06:41 +00:00
#### Q: What is Puppeteer?
2017-05-11 07:06:41 +00:00
2017-06-20 02:17:11 +00:00
Puppeteer is a light-weight Node module to control headless Chrome using the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
#### Q: Does Puppeteer work with headless Chromium?
2017-06-20 02:17:11 +00:00
Yes. Puppeteer bundles a version of Chromium and runs it in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome) by default.
#### Q: How is Puppeteer different than PhantomJS?
2017-06-20 02:17:11 +00:00
While PhantomJS provides a JavaScript API to control a full-fledged browser (WebKit), Puppeteer is a light-weight Node module to control headless Chrome.
2017-06-20 02:17:11 +00:00
Other important differences:
2017-06-20 02:17:11 +00:00
- 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?
2017-06-20 02:17:11 +00:00
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](#migration-guide).
#### Q: Why do most of the API methods return promises?
2017-06-20 02:17:11 +00:00
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.
2017-06-20 02:17:11 +00:00
However, if you're using Node 8 or higher, `async/await` make life easier:
```javascript
browser.newPage().then(async page => {
2017-06-20 02:17:11 +00:00
await page.setViewportSize({width: 1000, height: 1000});
await page.printToPDF('blank.pdf');
browser.close();
});
2017-05-11 07:06:41 +00:00
```
2017-06-20 02:17:11 +00:00
#### Q: What is the "Phantom Shim"?
2017-06-20 02:17:11 +00:00
"Phantom Shim" is a layer built atop the Puppeteer API that simulates Phantom's environment.
2017-06-20 17:33:21 +00:00
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](https://github.com/abbr/deasync)) 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
2017-06-20 02:17:11 +00:00
[TODO]