104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# Puppeteer [](https://travis-ci.com/GoogleChrome/puppeteer)
|
|
|
|
<img src="https://user-images.githubusercontent.com/238208/28749789-e67693de-7487-11e7-85f9-2d9ad9025aae.png" height="150" align="right">
|
|
|
|
###### [API](docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md)
|
|
|
|
Puppeteer is a node library which provides a high-level API to control [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) Chrome over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). It can also be configured to use full (non-headless) Chrome.
|
|
|
|
###### 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.
|
|
|
|
###### Features
|
|
* Full Page Screenshots
|
|
* Low-Level Input Emulation
|
|
* Build-In Device Emulation
|
|
|
|
## Installation
|
|
|
|
To add Puppeteer to your project, run:
|
|
```
|
|
yarn add puppeteer
|
|
```
|
|
|
|
> **NOTE** Puppeteer bundles a version of Chromium (~90Mb) which it is guaranteed to work with. However, you're free to point Puppeteer to any Chromium executable ([documentation](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#new-browseroptions))
|
|
|
|
|
|
## 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`:
|
|
|
|
```js
|
|
const {Browser} = require('puppeteer');
|
|
const browser = new Browser();
|
|
|
|
browser.newPage().then(async page => {
|
|
await page.goto('https://example.com');
|
|
await page.screenshot({path: 'example.png'});
|
|
browser.close();
|
|
});
|
|
```
|
|
|
|
A few notes:
|
|
|
|
1. By default, Puppeteer bundles chromium browser with which it works best. 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 800px x 600px, which defines the screenshot size. The page size can be changed with `Page.setViewportSize()` method
|
|
4. By default, browser is launched in a headless mode. This could be changed via ['headless' browser option](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#new-browseroptions)
|
|
|
|
## API Documentation
|
|
|
|
Explore the [API documentation](docs/api.md) and [examples](https://github.com/GoogleChrome/puppeteer/tree/master/examples/) to learn more.
|
|
|
|
## Contributing to Puppeteer
|
|
|
|
Check out [contributing guide](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md) 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 [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
|
|
|
|
#### Q: Which Chromium version does Puppeteer use?
|
|
|
|
Puppeteer bundles chromium it works best with. As chromium improves over time, new versions of puppeteer will be released which depend on a newer chromium versions.
|
|
|
|
Current chromium version is declared in [package.json](https://github.com/GoogleChrome/puppeteer/blob/master/package.json) as `chromium_revision` field.
|
|
|
|
#### Q: Does Puppeteer work with headless Chromium?
|
|
|
|
Yes. Puppeteer runs chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome) 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.
|
|
|
|
It is recommended to use `async/await` to consume asynchronous api:
|
|
```js
|
|
const {Browser} = require('puppeteer');
|
|
const browser = new Browser();
|
|
|
|
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"?
|
|
|
|
To make sure Puppeteer's API is comprehensive, we built [PhantomShim](https://github.com/GoogleChrome/puppeteer/tree/master/phantom_shim) - a lightweight phantomJS script runner built atop of Puppeteer API. We run phantomJS tests against PhantomShim with an ultimate goal to pass them all.
|
|
|
|
To emulate PhantomJS which runs automation scripts in-process to the automated page, PhantomShim spawns [nested event loops](https://github.com/abbr/deasync). On practice, this might result in unpredictable side-effects and makes the shim unreliable, but this works pretty good for testing goals.
|
|
|
|
> **NOTE** It is strictly **not recommended** to use PhantomShim out in the wild.
|
|
|
|
#### 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.
|