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: add the word the everywhere (#1988)

Browse Source
This commit is contained in:
JoelEinbinder 2018-02-07 14:20:28 -08:00 committed by Andrey Lushnikov
parent a363a733b7
commit cde6d6c4d0
1 changed files with 35 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/api.md
View File

@ -237,14 +237,14 @@
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.
The Puppeteer API is hierarchical and mirrors the browser structure. On the following diagram, faded entities are not currently represented in Puppeteer.
![puppeteer overview](https://user-images.githubusercontent.com/746130/31592143-089f6f9a-b1db-11e7-9a20-16b7fc754fa1.png)
- [`Puppeteer`](#class-puppeteer) communicates with browser using [devtools protocol](https://chromedevtools.github.io/devtools-protocol/).
- [`Browser`](#class-browser) instance owns multiple pages.
- [`Puppeteer`](#class-puppeteer) communicates with the browser using [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
- [`Browser`](#class-browser) instance can own multiple pages.
- [`Page`](#class-page) has at least one frame: main frame. There might be other frames created by [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) or [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) tags.
- [`Frame`](#class-frame) has at least one execution context - default execution context - where frame's JavaScript is executed. Frame might have additional execution contexts associated with [extensions](https://developer.chrome.com/extensions).
- [`Frame`](#class-frame) has at least one execution context - the default execution context - where the frame's JavaScript is executed. A Frame might have additional execution contexts that are associated with [extensions](https://developer.chrome.com/extensions).
(Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing))
@ -260,7 +260,7 @@ Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wik
### class: Puppeteer
Puppeteer module provides a method to launch a Chromium instance.
The following is a typical example of using a Puppeteer to drive automation:
The following is a typical example of using Puppeteer to drive automation:
```js
const puppeteer = require('puppeteer');
@ -298,18 +298,18 @@ This methods attaches Puppeteer to an existing Chromium instance.
- `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 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).
- `executablePath` <[string]> Path to a Chromium or Chrome executable to run instead of the 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 browser 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. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
- `ignoreDefaultArgs` <[boolean]> Do not use [`puppeteer.defaultArgs()`](#puppeteerdefaultargs). Dangerous option; use with care. Defaults to `false`.
- `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`.
- `handleSIGINT` <[boolean]> Close the browser process on Ctrl-C. Defaults to `true`.
- `handleSIGTERM` <[boolean]> Close the browser process on SIGTERM. Defaults to `true`.
- `handleSIGHUP` <[boolean]> Close the 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`.
- `dumpio` <[boolean]> Whether to pipe the 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 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`.
- `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
- `devtools` <[boolean]> Whether to auto-open a 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.
@ -330,7 +330,7 @@ BrowserFetcher can download and manage different versions of Chromium.
BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/).
Example on how to use BrowserFetcher to download a specific version of Chromium and run
puppeteer against it:
Puppeteer against it:
```js
const browserFetcher = puppeteer.createBrowserFetcher();
@ -414,9 +414,9 @@ puppeteer.launch().then(async browser => {
});
```
#### event: 'disconnected'
Emitted when puppeteer gets disconnected from the Chromium instance. This might happen because one of the following:
Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following:
- Chromium is closed or crashed
- `browser.disconnect` method was called
- The [`browser.disconnect`](#browserdisconnect) method was called
#### event: 'targetchanged'
- <[Target]>
@ -436,11 +436,11 @@ Emitted when a target is destroyed, for example when a page is closed.
#### browser.close()
- returns: <[Promise]>
Closes Chromium and all of its pages (if any were opened). The browser object itself is considered disposed and cannot be used anymore.
Closes Chromium and all of its pages (if any were opened). The [Browser] object itself is considered to be disposed and cannot be used anymore.
#### browser.disconnect()
Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`, the browser object is considered disposed and cannot be used anymore.
Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`, the [Browser] object is considered disposed and cannot be used anymore.
#### browser.newPage()
- returns: <[Promise]<[Page]>> Promise which resolves to a new [Page] object.
@ -449,7 +449,7 @@ Disconnects Puppeteer from the browser, but leaves the Chromium process running.
- returns: <[Promise]<[Array]<[Page]>>> Promise which resolves to an array of all open pages.
#### browser.process()
- returns: <?[ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with `puppeteer.connect` method.
- returns: <?[ChildProcess]> Spawned browser process. Returns `null` if the browser instance was created with [`puppeteer.connect`](#puppeteerconnectoptions) method.
#### browser.targets()
- returns: <[Array]<[Target]>> An array of all active targets.
@ -490,7 +490,7 @@ puppeteer.launch().then(async browser => {
});
```
The Page class emits various events (described below) which can be handled using any of Node's native EventEmitter methods, such as `on` or `once`.
The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on` or `once`.
This example logs a message for a single page `load` event:
```js
@ -644,7 +644,7 @@ Shortcut for [page.mainFrame().$x(expression)](#frameexpression)
#### page.addScriptTag(options)
- `options` <[Object]>
- `url` <[string]> Url of a script to be added.
- `url` <[string]> URL of a script to be added.
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw JavaScript content to be injected into frame.
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
@ -655,7 +655,7 @@ Shortcut for [page.mainFrame().addScriptTag(options)](#frameaddscripttagoptions)
#### page.addStyleTag(options)
- `options` <[Object]>
- `url` <[string]> Url of the `<link>` tag.
- `url` <[string]> URL of the `<link>` tag.
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw CSS content to be injected into frame.
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
@ -849,7 +849,7 @@ Adds a function which would be invoked in one of the following scenarios:
- whenever the page is navigated
- whenever the child frame is attached or navigated. In this case, the function is invoked in the context of the newly attached frame
The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed `Math.random`.
The function is invoked after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.
An example of overriding the navigator.languages property before the page loads:
@ -1094,7 +1094,7 @@ The `format` options are:
- `prototypeHandle` <[JSHandle]> A handle to the object prototype.
- returns: <[Promise]<[JSHandle]>> Promise which resolves to a handle to an array of objects with this prototype.
The method iterates JavaScript heap and finds all the objects with the given prototype.
The method iterates the JavaScript heap and finds all the objects with the given prototype.
```js
// Create a Map object
@ -1345,7 +1345,7 @@ Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options[, ...args]
- returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
#### page.waitForSelector(selector[, options])
- `selector` <[string]> A [selector] of an element to wait for,
- `selector` <[string]> A [selector] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
@ -1374,7 +1374,7 @@ puppeteer.launch().then(async browser => {
Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options).
#### page.waitForXPath(xpath[, options])
- `xpath` <[string]> A [xpath] of an element to wait for,
- `xpath` <[string]> A [xpath] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
@ -1695,7 +1695,7 @@ The method evaluates the XPath expression.
#### frame.addScriptTag(options)
- `options` <[Object]>
- `url` <[string]> Url of a script to be added.
- `url` <[string]> URL of a script to be added.
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw JavaScript content to be injected into frame.
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
@ -1704,7 +1704,7 @@ Adds a `<script>` tag into the page with the desired url or content.
#### frame.addStyleTag(options)
- `options` <[Object]>
- `url` <[string]> Url of the `<link>` tag.
- `url` <[string]> URL of the `<link>` tag.
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string]> Raw CSS content to be injected into frame.
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
@ -1915,7 +1915,7 @@ puppeteer.launch().then(async browser => {
```
#### frame.waitForSelector(selector[, options])
- `selector` <[string]> A [selector] of an element to wait for,
- `selector` <[string]> A [selector] of an element to wait for
- `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean]> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
@ -2037,7 +2037,7 @@ await resultHandle.dispose();
- `prototypeHandle` <[JSHandle]> A handle to the object prototype.
- returns: <[JSHandle]> A handle to an array of objects with this prototype
The method iterates JavaScript heap and finds all the objects with the given prototype.
The method iterates the JavaScript heap and finds all the objects with the given prototype.
```js
// Create a Map object
@ -2061,7 +2061,7 @@ const windowHandle = await page.evaluateHandle(() => window);
// ...
```
JSHandle prevents references JavaScript objects from garbage collection unless the handle is [disposed](#jshandledispose). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is [disposed](#jshandledispose). JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
JSHandle instances can be used as arguments in [`page.$eval()`](#pageevalselector-pagefunction-args), [`page.evaluate()`](#pageevaluatepagefunction-args) and [`page.evaluateHandle`](#pageevaluatehandlepagefunction-args) methods.
@ -2106,7 +2106,7 @@ Returns a JSON representation of the object. If the object has a
[`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior)
function, it **will not be called**.
> **NOTE** The method will return an empty JSON if the referenced object is not stringifiable. It will throw an error if the object has circular references.
> **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.
### class: ElementHandle
@ -2477,7 +2477,7 @@ await client.send('Animation.setPlaybackRate', {
#### cdpSession.detach()
- returns: <[Promise]>
Detaches session from target. Once detached, session won't emit any events and can't be used
Detaches the cdpSession from the target. Once detached, the cdpSession object won't emit any events and can't be used
to send messages.
#### cdpSession.send(method[, params])
@ -2546,7 +2546,7 @@ console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);
- `start` <[number]> A start offset in text, inclusive
- `end` <[number]> An end offset in text, exclusive
> **NOTE** JavaScript Coverage doesn't include anonymous scripts; however, scripts with sourceURLs are
> **NOTE** JavaScript Coverage doesn't include anonymous scripts. However, scripts with sourceURLs are
reported.