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

Update README.md

Browse Source 
Leave only essential information in the README.md

References #7
This commit is contained in:
Andrey Lushnikov 2017-07-27 19:15:30 -07:00
parent b9e3cce5fd
commit 97c3e40ca2
1 changed files with 23 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
README.md
View File

@ -1,6 +1,6 @@
# Puppeteer [![Build Status](https://travis-ci.com/GoogleChrome/puppeteer.svg?token=8jabovWqb8afz5RDcYqx&branch=master)](https://travis-ci.com/GoogleChrome/puppeteer)
# Puppeteer [![Build Status](https://travis-ci.com/GoogleChrome/puppeteer.svg?token=8jabovWqb8afz5RDcYqx&branch=master)](https://travis-ci.com/GoogleChrome/puppeteer) | [API](docs/api.md) | [FAQ](#faq)
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.
Puppeteer is a node library which provides a high-level API to control Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
## Use Cases
* Up-to-date testing environment that supports the latest Javascript features.
@ -18,25 +18,18 @@ cd puppeteer
Install the dependencies:
```sh
yarn # or 'npm install'
```
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 (~90Mb) 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
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`:
```javascript
const Browser = require('Puppeteer').Browser;
```js
const Browser = require('puppeteer').Browser;
const browser = new Browser();
browser.newPage().then(async page => {
@ -48,13 +41,14 @@ browser.newPage().then(async page => {
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))
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 400px x 300px, 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
## API Documentation
[API documentation](docs/api.md) is a work in progress.
Explore the [API documentation](docs/api.md) and [examples](https://github.com/GoogleChrome/puppeteer/tree/master/examples/) to learn more.
## Contributing to Puppeteer
@ -66,34 +60,22 @@ Check out [contributing guide](https://github.com/GoogleChrome/puppeteer/blob/ma
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 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?
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]
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.
#### Q: How do I migrate from PhantomJS to Puppeteer?
Current chromium version is declared in [package.json](https://github.com/GoogleChrome/puppeteer/blob/master/package.json) as `chromium_revision` field.
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: 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.
However, if you're using Node 8 or higher, `async/await` make life easier:
```javascript
It is recommended to use `async/await` to consume asynchronous api:
```js
browser.newPage().then(async page => {
await page.setViewport({width: 1000, height: 1000});
await page.pdf({path: 'blank.pdf'});
@ -103,16 +85,14 @@ browser.newPage().then(async page => {
#### Q: What is the "Phantom Shim"?
"Phantom Shim" is a layer built atop the Puppeteer API that simulates Phantom's environment.
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.
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.
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.
# Migration Guide
[TODO]
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.