github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Tweaks to readme. API doc link

Browse Source
This commit is contained in:
Eric Bidelman 2017-06-19 19:17:11 -07:00 committed by Pavel Feldman
parent 9ad4938fcb
commit 92eefea511
1 changed files with 50 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@ -1,36 +1,55 @@
# Puppeteer # Puppeteer
Puppeteer is a node.js library which provides a high-level API to control chromium over the Devtools Protocol. Puppeteer is inspired by [PhantomJS](http://phantomjs.org/). Check our [FAQ](http://todo) to learn more. 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.
## Installation ## Installation
Get the source:
``` ```
git clone https://github.com/GoogleChrome/puppeteer git clone https://github.com/GoogleChrome/puppeteer
cd puppeteer cd puppeteer
```
Install the dependencies:
```
yarn
```
or use `npm`:
```
npm install 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](https://github.com/GoogleChrome/puppeteer/blob/master/examples/custom-chromium-revision.js))
> 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 ## Getting Started
The following node.js script navigates page to the https://example.com and saves screenshot to *example.jpg*: The following script navigates to https://example.com and saves a screenshot to *example.jpg*:
```javascript ```javascript
var Browser = require('Puppeteer').Browser; const Browser = require('Puppeteer').Browser;
var browser = new Browser(); const browser = new Browser();
browser.newPage().then(async page => { browser.newPage().then(async page => {
await page.navigate('https://example.com'); await page.navigate('https://example.com');
await page.screenshot({path: 'example.jpg'}); await page.screenshot({path: 'example.jpg'});
browser.close(); browser.close();
}); });
``` ```
A few gotchas:
1. By default, puppeeteer runs 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)) A few notes:
2. Puppeteer creates its own chromium user profile which it cleans up on every run.
3. Puppeteer sets initial page size to 400px x 300px, which defines the screenshot size. The page size could be changed with `Page.setSize()` method 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.setSize()` method
## API
[API documentation](docs/api.md) is a work in progress.
## Contributing ## Contributing
@ -40,19 +59,20 @@ Check out our [contributing guide](https://github.com/GoogleChrome/puppeteer/blo
#### Q: What is Puppeteer? #### Q: What is Puppeteer?
Puppeteer is a lightweight node.js module which provides high-level API atop of DevTools protocol to control chromium browsers. 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? #### Q: Does Puppeteer work with headless Chromium?
Yes. Puppeteer bundles chromium and runs it in a headless mode by default. 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's Puppeteer different to PhantomJS? #### Q: How is Puppeteer different than PhantomJS?
PhantomJS is a scriptable full-fledged browser. Puppeteer is a light-weight NPM module which could be used from any node.js script. This difference provides Puppeteer scripts with the following advantages: While PhantomJS provides a JavaScript API to control a full-fledged browser (WebKit), Puppeteer is a light-weight Node module to control headless Chrome.
- Ever-green chromium browser Other important differences:
- Node.js runtime environment and npm ecosystem
- Debuggability (thanks to node.js debugging and non-headless chromium mode) - 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? #### Q: Which Chromium version does Puppeteer use?
@ -60,27 +80,29 @@ PhantomJS is a scriptable full-fledged browser. Puppeteer is a light-weight NPM
#### Q: How do I migrate from PhantomJS to Puppeteer? #### Q: How do I migrate from PhantomJS to Puppeteer?
There's no automatic way to migrate PhantomJS scripts to node.js scripts with Puppeteer. For more information and some guidance, check out our [migration guide](http://todo). 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? #### Q: Why do most of the API methods return promises?
Since Puppeteer's code is run by node.js, it exists out-of-process to the controlled chromium instance. This requires most of the API methods to be asynchronous to allow for the roundtrip to the browser. 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, with the new `async/await` syntax this should not deal much troubles: However, if you're using Node 8 or higher, `async/await` make life easier:
```javascript ```javascript
browser.newPage().then(async page => { browser.newPage().then(async page => {
await page.setViewportSize({width: 1000, height: 1000}); await page.setViewportSize({width: 1000, height: 1000});
await page.printToPDF('blank.pdf'); await page.printToPDF('blank.pdf');
browser.close(); browser.close();
}); });
``` ```
#### Q: What's "Phantom Shim"? #### Q: What is the "Phantom Shim"?
"Phantom Shim" is a layer built atop of Puppeteer API. The layer simulates phantomJS environment, employing unhealthy approaches (e.g. in-process code execution is emulated via [nested event loops](https://github.com/abbr/deasync)). "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.
The shim is developed to run PhantomJS tests and estimate the comprehensiveness of Puppeteer API. At the moment, the shim employs unhealthy approaches (e.g. in-process code execution is emulated via [nested event loops](https://github.com/abbr/deasync)) to mimic Phantom's environment.
# Migration Guide # Migration Guide
[TODO] [TODO]