From 97c3e40ca20bbe2ae1bb799a779c92e52fa7b8c4 Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Thu, 27 Jul 2017 19:15:30 -0700 Subject: [PATCH] Update README.md Leave only essential information in the README.md References #7 --- README.md | 66 +++++++++++++++++++------------------------------------ 1 file changed, 23 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index c1de826770c..c0fee903d92 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file