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
This commit is contained in:
Karl Brown
Andrey Lushnikov
parent
a5db6d412c
commit
63f7e38077
13
README.md
13
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?
|
||||
|
||||
|
||||
27
docs/api.md
27
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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user