Tweaks to readme. API doc link
This commit is contained in:
Eric Bidelman
Pavel Feldman
parent
9ad4938fcb
commit
92eefea511
78
README.md
78
README.md
@ -1,36 +1,55 @@
|
||||
# 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
|
||||
|
||||
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](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
|
||||
|
||||
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
|
||||
var Browser = require('Puppeteer').Browser;
|
||||
var browser = new Browser();
|
||||
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.jpg'});
|
||||
browser.close();
|
||||
await page.navigate('https://example.com');
|
||||
await page.screenshot({path: 'example.jpg'});
|
||||
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))
|
||||
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
|
||||
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.setSize()` method
|
||||
|
||||
## API
|
||||
|
||||
[API documentation](docs/api.md) is a work in progress.
|
||||
|
||||
## Contributing
|
||||
|
||||
@ -40,19 +59,20 @@ Check out our [contributing guide](https://github.com/GoogleChrome/puppeteer/blo
|
||||
|
||||
#### 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?
|
||||
|
||||
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
|
||||
- Node.js runtime environment and npm ecosystem
|
||||
- Debuggability (thanks to node.js debugging and non-headless chromium mode)
|
||||
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?
|
||||
|
||||
@ -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?
|
||||
|
||||
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?
|
||||
|
||||
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
|
||||
browser.newPage().then(async page => {
|
||||
await page.setViewportSize({width: 1000, height: 1000});
|
||||
await page.printToPDF('blank.pdf');
|
||||
browser.close();
|
||||
await page.setViewportSize({width: 1000, height: 1000});
|
||||
await page.printToPDF('blank.pdf');
|
||||
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
|
||||
|
||||
[TODO]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user