From 63f7e38077bcf7882eb641817ed825cbeb5407d3 Mon Sep 17 00:00:00 2001 From: Karl Brown Date: Thu, 14 Dec 2017 22:09:48 -0500 Subject: [PATCH] docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574) This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default) and Chrome. Fixes #1516 --- README.md | 13 ++++++++----- docs/api.md | 27 +++++++++++++++++---------- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 538abd9f54f..f6948a0235b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ###### [API](docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md) -> 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 over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). It can also be configured to use full (non-headless) Chrome. +> 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? @@ -112,7 +112,7 @@ const browser = await puppeteer.launch({headless: false}); // default is true **2. Runs a bundled version of Chromium** By default, Puppeteer downloads and uses a specific version of Chromium so its API -is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome, +is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome or Chromium, pass in the executable's path when creating a `Browser` instance: ```js @@ -121,6 +121,9 @@ const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'}); See [`Puppeteer.launch()`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) for more information. +See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description +of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. + **3. Creates a fresh user profile** Puppeteer creates its own Chromium user profile which it **cleans up on every run**. @@ -133,7 +136,7 @@ Explore the [API documentation](docs/api.md) and [examples](https://github.com/G 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 - Chrome using `headless: false`: + the browser using `headless: false`: ```js const browser = await puppeteer.launch({headless: false}); @@ -194,9 +197,9 @@ Puppeteer bundles Chromium to ensure that the latest features it uses are guaran Selenium / WebDriver is a well-established cross-browser API that is useful for testing cross-browser support. -Puppeteer works only with Chrome. However, many teams only run unit tests with a single browser (e.g. PhantomJS). 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. +Puppeteer works only with Chromium or Chrome. However, many teams only run unit tests with a single browser (e.g. PhantomJS). 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. -Puppeteer uses the latest versions of Chromium. +Puppeteer bundles the latest versions of Chromium. #### Q: Who maintains Puppeteer? diff --git a/docs/api.md b/docs/api.md index f5f0700fb07..2f280208d18 100644 --- a/docs/api.md +++ b/docs/api.md @@ -198,7 +198,7 @@ ### Overview -Puppeteer is a Node library which provides a high-level API to control Chromium over the DevTools Protocol. +Puppeteer is a Node library which provides a high-level API to control Chromium or Chrome over the DevTools Protocol. Puppeteer API is hierarchical and mirrors browser structure. On the following diagram, faded entities are not currently represented in Puppeteer. @@ -249,23 +249,30 @@ This methods attaches Puppeteer to an existing Chromium instance. #### puppeteer.launch([options]) - `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - `ignoreHTTPSErrors` <[boolean]> Whether to ignore HTTPS errors during navigation. Defaults to `false`. - - `headless` <[boolean]> Whether to run Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. - - `executablePath` <[string]> Path to a Chromium executable to run instead of bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). + - `headless` <[boolean]> Whether to run browser in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). Defaults to `true` unless the `devtools` option is `true`. + - `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of bundled Chromium. If `executablePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `slowMo` <[number]> Slows down Puppeteer operations by the specified amount of milliseconds. Useful so that you can see what is going on. - - `args` <[Array]<[string]>> Additional arguments to pass to the Chromium instance. List of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/). - - `handleSIGINT` <[boolean]> Close chrome process on Ctrl-C. Defaults to `true`. - - `handleSIGTERM` <[boolean]> Close chrome process on SIGTERM. Defaults to `true`. - - `handleSIGHUP` <[boolean]> Close chrome process on SIGHUP. Defaults to `true`. - - `timeout` <[number]> Maximum time in milliseconds to wait for the Chrome instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. + - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. List of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/). + - `handleSIGINT` <[boolean]> Close browser process on Ctrl-C. Defaults to `true`. + - `handleSIGTERM` <[boolean]> Close browser process on SIGTERM. Defaults to `true`. + - `handleSIGHUP` <[boolean]> Close browser process on SIGHUP. Defaults to `true`. + - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - `dumpio` <[boolean]> Whether to pipe browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`. - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md). - - `env` <[Object]> Specify environment variables that will be visible to Chromium. Defaults to `process.env`. + - `env` <[Object]> Specify environment variables that will be visible to browser. Defaults to `process.env`. - `devtools` <[boolean]> Whether to auto-open DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`. - returns: <[Promise]<[Browser]>> Promise which resolves to browser instance. The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed. -> **NOTE** Puppeteer works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. +> **NOTE** Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no + guarantee it will work with any other version. Use `executablePath` option with extreme caution. +If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. +> +> In [puppeteer.launch([options])](#puppeteerlaunchoptions) above, any mention of Chromium also applies to Chrome. +> +> See [`this article`](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description + of the differences between Chromium and Chrome. [`This article`](https://chromium.googlesource.com/chromium/src/+/lkcr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. ### class: Browser