From 92eefea511d0ecebfd2137c031a444451ae82a35 Mon Sep 17 00:00:00 2001 From: Eric Bidelman Date: Mon, 19 Jun 2017 19:17:11 -0700 Subject: [PATCH] Tweaks to readme. API doc link --- README.md | 78 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 50 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index f83db5fabd3..c113884ea03 100644 --- a/README.md +++ b/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]