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

docs(README.md): Update docs to more clearly differentiate between Chromium and Chrome (#1574)

Browse Source 
This patch clarifies the documentation to more clearly note that Puppeteer works with both Chromium (by default)
and Chrome.

Fixes #1516
This commit is contained in:
Karl Brown 2017-12-14 22:09:48 -05:00 committed by Andrey Lushnikov
parent a5db6d412c
commit 63f7e38077
2 changed files with 25 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -4,7 +4,7 @@
###### [API](docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md) ###### [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? ###### 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** **2. Runs a bundled version of Chromium**
By default, Puppeteer downloads and uses a specific version of Chromium so its API 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: pass in the executable's path when creating a `Browser` instance:
```js ```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 [`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** **3. Creates a fresh user profile**
Puppeteer creates its own Chromium user profile which it **cleans up on every run**. 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 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 displaying. Instead of launching in headless mode, launch a full version of
Chrome using `headless: false`: the browser using `headless: false`:
```js ```js
const browser = await puppeteer.launch({headless: false}); 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. 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? #### Q: Who maintains Puppeteer?

27
docs/api.md
View File

@ -198,7 +198,7 @@
### Overview ### 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. 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]) #### puppeteer.launch([options])
- `options` <[Object]> Set of configurable options to set on the browser. Can have the following fields: - `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`. - `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`. - `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 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). - `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. - `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/). - `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 chrome process on Ctrl-C. Defaults to `true`. - `handleSIGINT` <[boolean]> Close browser process on Ctrl-C. Defaults to `true`.
- `handleSIGTERM` <[boolean]> Close chrome process on SIGTERM. Defaults to `true`. - `handleSIGTERM` <[boolean]> Close browser process on SIGTERM. Defaults to `true`.
- `handleSIGHUP` <[boolean]> Close chrome process on SIGHUP. Defaults to `true`. - `handleSIGHUP` <[boolean]> Close browser 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. - `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`. - `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). - `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`. - `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. - 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. 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 ### class: Browser