From 9b06ed28ae72ee3aa6de1f8b534f51347320b4a6 Mon Sep 17 00:00:00 2001 From: Eric Bidelman Date: Thu, 11 Jan 2018 00:28:36 -0800 Subject: [PATCH] docs(README): updates to make d.g.c/web/ happy (#1773) Adds devsite's comment markers so we can pull sections of the readme into the site. We lose a few syntax highlighting sections here on github, but everything looks great on developers.google.com! --- README.md | 69 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 1979a57c..184faf79 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@ -# Puppeteer [![Linux Build Status](https://img.shields.io/travis/GoogleChrome/puppeteer/master.svg)](https://travis-ci.org/GoogleChrome/puppeteer) [![Windows Build Status](https://img.shields.io/appveyor/ci/aslushnikov/puppeteer/master.svg?logo=appveyor)](https://ci.appveyor.com/project/aslushnikov/puppeteer/branch/master) [![NPM puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer) +# Puppeteer + + +[![Linux Build Status](https://img.shields.io/travis/GoogleChrome/puppeteer/master.svg)](https://travis-ci.org/GoogleChrome/puppeteer) [![Windows Build Status](https://img.shields.io/appveyor/ci/aslushnikov/puppeteer/master.svg?logo=appveyor)](https://ci.appveyor.com/project/aslushnikov/puppeteer/branch/master) [![NPM puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer) + @@ -6,6 +10,7 @@ > Puppeteer is a Node library which provides a high-level API to control [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). It can also be configured to use full (non-headless) Chrome or Chromium. + ###### What can I do? Most things that you can do manually in the browser can be done using Puppeteer! Here are a few examples to get you started: @@ -16,25 +21,27 @@ Most things that you can do manually in the browser can be done using Puppeteer! * Automate form submission, UI testing, keyboard input, etc. * Create an up-to-date, automated testing environment. Run your tests directly in the latest version of Chrome using the latest JavaScript and browser features. * Capture a [timeline trace](https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/reference) of your site to help diagnose performance issues. + Give it a spin: https://try-puppeteer.appspot.com/ + ## Getting Started ### Installation -> *Note: Puppeteer requires at least Node v6.4.0, but the examples below use async/await which is only supported in Node v7.6.0 or greater* - To use Puppeteer in your project, run: ``` yarn add puppeteer # or "npm i puppeteer" ``` -> **Note**: When you install Puppeteer, it downloads a recent version of Chromium (~71Mb Mac, ~90Mb Linux, ~110Mb Win) that is guaranteed to work with the API. To skip the download, see [Environment variables](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#environment-variables). +Note: When you install Puppeteer, it downloads a recent version of Chromium (~71Mb Mac, ~90Mb Linux, ~110Mb Win) that is guaranteed to work with the API. To skip the download, see [Environment variables](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#environment-variables). ### Usage +Caution: Puppeteer requires at least Node v6.4.0, but the examples below use async/await which is only supported in Node v7.6.0 or greater. + Puppeteer will be familiar to people using other browser testing frameworks. You create an instance of `Browser`, open pages, and then manipulate them with [Puppeteer's API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#). @@ -99,6 +106,9 @@ const puppeteer = require('puppeteer'); See [`Page.evaluate()`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageevaluatepagefunction-args) for more information on `evaluate` and related methods like `evaluateOnNewDocument` and `exposeFunction`. + + + ## Default runtime settings **1. Uses Headless mode** @@ -128,63 +138,60 @@ of the differences between Chromium and Chrome. [`This article`](https://chromiu Puppeteer creates its own Chromium user profile which it **cleans up on every run**. + + ## API Documentation Explore the [API documentation](docs/api.md) and [examples](https://github.com/GoogleChrome/puppeteer/tree/master/examples/) to learn more. + + ## Debugging tips 1. Turn off headless mode - sometimes it's useful to see what the browser is displaying. Instead of launching in headless mode, launch a full version of the browser using `headless: false`: - ```js - const browser = await puppeteer.launch({headless: false}); - ``` + const browser = await puppeteer.launch({headless: false}); 1. Slow it down - the `slowMo` option slows down Puppeteer operations by the specified amount of milliseconds. It's another way to help see what's going on. - ```js - const browser = await puppeteer.launch({ - headless: false, - slowMo: 250 // slow down by 250ms - }); - ``` + const browser = await puppeteer.launch({ + headless: false, + slowMo: 250 // slow down by 250ms + }); 1. Capture console output - You can listen for the `console` event. This is also handy when debugging code in `page.evaluate()`: - ```js - page.on('console', msg => console.log('PAGE LOG:', ...msg.args)); - - await page.evaluate(() => console.log(`url is ${location.href}`)); - ``` + page.on('console', msg => console.log('PAGE LOG:', ...msg.args)); + + await page.evaluate(() => console.log(`url is ${location.href}`)); 1. Enable verbose logging - All public API calls and internal protocol traffic will be logged via the [`debug`](https://github.com/visionmedia/debug) module under the `puppeteer` namespace. - ```sh - # Basic verbose logging - env DEBUG="puppeteer:*" node script.js - - # Debug output can be enabled/disabled by namespace - env DEBUG="puppeteer:*,-puppeteer:protocol" node script.js # everything BUT protocol messages - env DEBUG="puppeteer:session" node script.js # protocol session messages (protocol messages to targets) - env DEBUG="puppeteer:mouse,puppeteer:keyboard" node script.js # only Mouse and Keyboard API calls - - # Protocol traffic can be rather noisy. This example filters out all Network domain messages - env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network' - ``` + # Basic verbose logging + env DEBUG="puppeteer:*" node script.js + # Debug output can be enabled/disabled by namespace + env DEBUG="puppeteer:*,-puppeteer:protocol" node script.js # everything BUT protocol messages + env DEBUG="puppeteer:session" node script.js # protocol session messages (protocol messages to targets) + env DEBUG="puppeteer:mouse,puppeteer:keyboard" node script.js # only Mouse and Keyboard API calls + # Protocol traffic can be rather noisy. This example filters out all Network domain messages + env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network' + ## Contributing to Puppeteer Check out [contributing guide](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md) to get an overview of Puppeteer development. + + # FAQ #### Q: Which Chromium version does Puppeteer use? @@ -229,3 +236,5 @@ You may find that Puppeteer does not behave as expected when controlling pages t * Puppeteer is bundled with Chromium--not Chrome--and so by default, it inherits all of [Chromium's media-related limitations](https://www.chromium.org/audio-video). This means that Puppeteer does not support licensed formats such as AAC or H.264. (However, it is possible to force Puppeteer to use a separately-installed version Chrome instead of Chromium via the [`executablePath` option to `puppeteer.launch`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions). You should only use this configuration if you need an official release of Chrome that supports these media formats.) * Since Puppeteer (in all configurations) controls a desktop version of Chromium/Chrome, features that are only supported by the mobile version of Chrome are not supported. This means that Puppeteer [does not support HTTP Live Streaming (HLS)](https://caniuse.com/#feat=http-live-streaming). + +