thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(new): migrate Browser docs to TSDoc (#6070)

Browse Source
This commit is contained in:
Peter Marshall 2020-06-23 07:19:15 +02:00 committed by GitHub
parent 28797dee41
commit ccae54644c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
37 changed files with 357 additions and 333 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
new-docs/puppeteer.browser._closecallback.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_closeCallback](./puppeteer.browser._closecallback.md)
## Browser.\_closeCallback property
<b>Signature:</b>
```typescript
_closeCallback: BrowserCloseCallback;
```

11
new-docs/puppeteer.browser._connection.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_connection](./puppeteer.browser._connection.md)
## Browser.\_connection property
<b>Signature:</b>
```typescript
_connection: Connection;
```

25
new-docs/puppeteer.browser._constructor_.md
View File

@ -1,25 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [(constructor)](./puppeteer.browser._constructor_.md)
## Browser.(constructor)
Constructs a new instance of the `Browser` class
<b>Signature:</b>
```typescript
constructor(connection: Connection, contextIds: string[], ignoreHTTPSErrors: boolean, defaultViewport?: Viewport, process?: ChildProcess, closeCallback?: BrowserCloseCallback);
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| connection | [Connection](./puppeteer.connection.md) | |
| contextIds | string\[\] | |
| ignoreHTTPSErrors | boolean | |
| defaultViewport | Viewport | |
| process | ChildProcess | |
| closeCallback | BrowserCloseCallback | |

11
new-docs/puppeteer.browser._contexts.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_contexts](./puppeteer.browser._contexts.md)
## Browser.\_contexts property
<b>Signature:</b>
```typescript
_contexts: Map<string, BrowserContext>;
```

22
new-docs/puppeteer.browser._createpageincontext.md
View File

@ -1,22 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_createPageInContext](./puppeteer.browser._createpageincontext.md)
## Browser.\_createPageInContext() method
<b>Signature:</b>
```typescript
_createPageInContext(contextId?: string): Promise<Page>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| contextId | string | |
<b>Returns:</b>
Promise&lt;[Page](./puppeteer.page.md)<!-- -->&gt;

11
new-docs/puppeteer.browser._defaultcontext.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_defaultContext](./puppeteer.browser._defaultcontext.md)
## Browser.\_defaultContext property
<b>Signature:</b>
```typescript
_defaultContext: BrowserContext;
```

11
new-docs/puppeteer.browser._defaultviewport.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_defaultViewport](./puppeteer.browser._defaultviewport.md)
## Browser.\_defaultViewport property
<b>Signature:</b>
```typescript
_defaultViewport?: Viewport;
```

22
new-docs/puppeteer.browser._disposecontext.md
View File

@ -1,22 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_disposeContext](./puppeteer.browser._disposecontext.md)
## Browser.\_disposeContext() method
<b>Signature:</b>
```typescript
_disposeContext(contextId?: string): Promise<void>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| contextId | string | |
<b>Returns:</b>
Promise&lt;void&gt;

15
new-docs/puppeteer.browser._getversion.md
View File

@ -1,15 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_getVersion](./puppeteer.browser._getversion.md)
## Browser.\_getVersion() method
<b>Signature:</b>
```typescript
_getVersion(): Promise<Protocol.Browser.getVersionReturnValue>;
```
<b>Returns:</b>
Promise&lt;Protocol.Browser.getVersionReturnValue&gt;

11
new-docs/puppeteer.browser._ignorehttpserrors.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_ignoreHTTPSErrors](./puppeteer.browser._ignorehttpserrors.md)
## Browser.\_ignoreHTTPSErrors property
<b>Signature:</b>
```typescript
_ignoreHTTPSErrors: boolean;
```

11
new-docs/puppeteer.browser._process.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_process](./puppeteer.browser._process.md)
## Browser.\_process property
<b>Signature:</b>
```typescript
_process?: ChildProcess;
```

22
new-docs/puppeteer.browser._targetcreated.md
View File

@ -1,22 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_targetCreated](./puppeteer.browser._targetcreated.md)
## Browser.\_targetCreated() method
<b>Signature:</b>
```typescript
_targetCreated(event: Protocol.Target.targetCreatedPayload): Promise<void>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| event | Protocol.Target.targetCreatedPayload | |
<b>Returns:</b>
Promise&lt;void&gt;

24
new-docs/puppeteer.browser._targetdestroyed.md
View File

@ -1,24 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_targetDestroyed](./puppeteer.browser._targetdestroyed.md)
## Browser.\_targetDestroyed() method
<b>Signature:</b>
```typescript
_targetDestroyed(event: {
targetId: string;
}): Promise<void>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| event | { targetId: string; } | |
<b>Returns:</b>
Promise&lt;void&gt;

22
new-docs/puppeteer.browser._targetinfochanged.md
View File

@ -1,22 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_targetInfoChanged](./puppeteer.browser._targetinfochanged.md)
## Browser.\_targetInfoChanged() method
<b>Signature:</b>
```typescript
_targetInfoChanged(event: Protocol.Target.targetInfoChangedPayload): void;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| event | Protocol.Target.targetInfoChangedPayload | |
<b>Returns:</b>
void

11
new-docs/puppeteer.browser._targets.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [\_targets](./puppeteer.browser._targets.md)
## Browser.\_targets property
<b>Signature:</b>
```typescript
_targets: Map<string, Target>;
```

2
new-docs/puppeteer.browser.browsercontexts.md
View File

@ -4,6 +4,8 @@
## Browser.browserContexts() method ## Browser.browserContexts() method
Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md)<!-- -->.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

2
new-docs/puppeteer.browser.close.md
View File

@ -4,6 +4,8 @@
## Browser.close() method ## Browser.close() method
Closes Chromium and all of its pages (if any were opened). The [Browser](./puppeteer.browser.md) object itself is considered to be disposed and cannot be used anymore.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

27
new-docs/puppeteer.browser.create.md
View File

@ -1,27 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Browser](./puppeteer.browser.md) &gt; [create](./puppeteer.browser.create.md)
## Browser.create() method
<b>Signature:</b>
```typescript
static create(connection: Connection, contextIds: string[], ignoreHTTPSErrors: boolean, defaultViewport?: Viewport, process?: ChildProcess, closeCallback?: BrowserCloseCallback): Promise<Browser>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| connection | [Connection](./puppeteer.connection.md) | |
| contextIds | string\[\] | |
| ignoreHTTPSErrors | boolean | |
| defaultViewport | Viewport | |
| process | ChildProcess | |
| closeCallback | BrowserCloseCallback | |
<b>Returns:</b>
Promise&lt;[Browser](./puppeteer.browser.md)<!-- -->&gt;

18
new-docs/puppeteer.browser.createincognitobrowsercontext.md
View File

@ -4,6 +4,8 @@
## Browser.createIncognitoBrowserContext() method ## Browser.createIncognitoBrowserContext() method
Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript
@ -13,3 +15,19 @@ createIncognitoBrowserContext(): Promise<BrowserContext>;
Promise&lt;[BrowserContext](./puppeteer.browsercontext.md)<!-- -->&gt; Promise&lt;[BrowserContext](./puppeteer.browsercontext.md)<!-- -->&gt;
## Example
```js
(async () => {
const browser = await puppeteer.launch();
// Create a new incognito browser context.
const context = await browser.createIncognitoBrowserContext();
// Create a new page in a pristine context.
const page = await context.newPage();
// Do stuff
await page.goto('https://example.com');
})();
```

2
new-docs/puppeteer.browser.defaultbrowsercontext.md
View File

@ -4,6 +4,8 @@
## Browser.defaultBrowserContext() method ## Browser.defaultBrowserContext() method
Returns the default browser context. The default browser context cannot be closed.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

2
new-docs/puppeteer.browser.disconnect.md
View File

@ -4,6 +4,8 @@
## Browser.disconnect() method ## Browser.disconnect() method
Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`<!-- -->, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

2
new-docs/puppeteer.browser.isconnected.md
View File

@ -4,6 +4,8 @@
## Browser.isConnected() method ## Browser.isConnected() method
Indicates that the browser is connected.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

92
new-docs/puppeteer.browser.md
View File

@ -4,6 +4,8 @@
## Browser class ## Browser class
A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript
@ -11,49 +13,65 @@ export declare class Browser extends EventEmitter
``` ```
<b>Extends:</b> [EventEmitter](./puppeteer.eventemitter.md) <b>Extends:</b> [EventEmitter](./puppeteer.eventemitter.md)
## Constructors ## Remarks
| Constructor | Modifiers | Description | The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Browser` class.
| --- | --- | --- |
| [(constructor)(connection, contextIds, ignoreHTTPSErrors, defaultViewport, process, closeCallback)](./puppeteer.browser._constructor_.md) | | Constructs a new instance of the <code>Browser</code> class |
## Properties ## Example 1
| Property | Modifiers | Type | Description | An example of using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md)<!-- -->:
| --- | --- | --- | --- |
| [\_closeCallback](./puppeteer.browser._closecallback.md) | | BrowserCloseCallback | | ```js
| [\_connection](./puppeteer.browser._connection.md) | | [Connection](./puppeteer.connection.md) | | const puppeteer = require('puppeteer');
| [\_contexts](./puppeteer.browser._contexts.md) | | Map&lt;string, [BrowserContext](./puppeteer.browsercontext.md)<!-- -->&gt; | |
| [\_defaultContext](./puppeteer.browser._defaultcontext.md) | | [BrowserContext](./puppeteer.browsercontext.md) | | (async () => {
| [\_defaultViewport](./puppeteer.browser._defaultviewport.md) | | Viewport | | const browser = await puppeteer.launch();
| [\_ignoreHTTPSErrors](./puppeteer.browser._ignorehttpserrors.md) | | boolean | | const page = await browser.newPage();
| [\_process](./puppeteer.browser._process.md) | | ChildProcess | | await page.goto('https://example.com');
| [\_targets](./puppeteer.browser._targets.md) | | Map&lt;string, [Target](./puppeteer.target.md)<!-- -->&gt; | | await browser.close();
})();
```
## Example 2
An example of disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md)<!-- -->:
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
// Store the endpoint to be able to reconnect to Chromium
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from Chromium
browser.disconnect();
// Use the endpoint to reestablish a connection
const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close Chromium
await browser2.close();
})();
```
## Methods ## Methods
| Method | Modifiers | Description | | Method | Modifiers | Description |
| --- | --- | --- | | --- | --- | --- |
| [\_createPageInContext(contextId)](./puppeteer.browser._createpageincontext.md) | | | | [browserContexts()](./puppeteer.browser.browsercontexts.md) | | Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md)<!-- -->. |
| [\_disposeContext(contextId)](./puppeteer.browser._disposecontext.md) | | | | [close()](./puppeteer.browser.close.md) | | Closes Chromium and all of its pages (if any were opened). The [Browser](./puppeteer.browser.md) object itself is considered to be disposed and cannot be used anymore. |
| [\_getVersion()](./puppeteer.browser._getversion.md) | | | | [createIncognitoBrowserContext()](./puppeteer.browser.createincognitobrowsercontext.md) | | Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. |
| [\_targetCreated(event)](./puppeteer.browser._targetcreated.md) | | | | [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | Returns the default browser context. The default browser context cannot be closed. |
| [\_targetDestroyed(event)](./puppeteer.browser._targetdestroyed.md) | | | | [disconnect()](./puppeteer.browser.disconnect.md) | | Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling <code>disconnect</code>, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore. |
| [\_targetInfoChanged(event)](./puppeteer.browser._targetinfochanged.md) | | | | [isConnected()](./puppeteer.browser.isconnected.md) | | Indicates that the browser is connected. |
| [browserContexts()](./puppeteer.browser.browsercontexts.md) | | | | [newPage()](./puppeteer.browser.newpage.md) | | Creates a [Page](./puppeteer.page.md) in the default browser context. |
| [close()](./puppeteer.browser.close.md) | | | | [pages()](./puppeteer.browser.pages.md) | | An array of all open pages inside the Browser. |
| [create(connection, contextIds, ignoreHTTPSErrors, defaultViewport, process, closeCallback)](./puppeteer.browser.create.md) | <code>static</code> | | | [process()](./puppeteer.browser.process.md) | | The spawned browser process. Returns <code>null</code> if the browser instance was created with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->. |
| [createIncognitoBrowserContext()](./puppeteer.browser.createincognitobrowsercontext.md) | | | | [target()](./puppeteer.browser.target.md) | | The target associated with the browser. |
| [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | | | [targets()](./puppeteer.browser.targets.md) | | All active targets inside the Browser. In case of multiple browser contexts, returns an array with all the targets in all browser contexts. |
| [disconnect()](./puppeteer.browser.disconnect.md) | | | | [userAgent()](./puppeteer.browser.useragent.md) | | The browser's original user agent. Pages can override the browser user agent with [Page.setUserAgent()](./puppeteer.page.setuseragent.md)<!-- -->. |
| [isConnected()](./puppeteer.browser.isconnected.md) | | | | [version()](./puppeteer.browser.version.md) | | A string representing the browser name and version. |
| [newPage()](./puppeteer.browser.newpage.md) | | | | [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | Searches for a target in all browser contexts. |
| [pages()](./puppeteer.browser.pages.md) | | | | [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->. |
| [process()](./puppeteer.browser.process.md) | | |
| [target()](./puppeteer.browser.target.md) | | |
| [targets()](./puppeteer.browser.targets.md) | | |
| [userAgent()](./puppeteer.browser.useragent.md) | | |
| [version()](./puppeteer.browser.version.md) | | |
| [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | |
| [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | |

2
new-docs/puppeteer.browser.newpage.md
View File

@ -4,6 +4,8 @@
## Browser.newPage() method ## Browser.newPage() method
Creates a [Page](./puppeteer.page.md) in the default browser context.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

6
new-docs/puppeteer.browser.pages.md
View File

@ -4,6 +4,8 @@
## Browser.pages() method ## Browser.pages() method
An array of all open pages inside the Browser.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript
@ -13,3 +15,7 @@ pages(): Promise<Page[]>;
Promise&lt;[Page](./puppeteer.page.md)<!-- -->\[\]&gt; Promise&lt;[Page](./puppeteer.page.md)<!-- -->\[\]&gt;
## Remarks
In case of multiple browser contexts, returns an array with all the pages in all browser contexts. Non-visible pages, such as `"background_page"`<!-- -->, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md)<!-- -->.

2
new-docs/puppeteer.browser.process.md
View File

@ -4,6 +4,8 @@
## Browser.process() method ## Browser.process() method
The spawned browser process. Returns `null` if the browser instance was created with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

2
new-docs/puppeteer.browser.target.md
View File

@ -4,6 +4,8 @@
## Browser.target() method ## Browser.target() method
The target associated with the browser.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

2
new-docs/puppeteer.browser.targets.md
View File

@ -4,6 +4,8 @@
## Browser.targets() method ## Browser.targets() method
All active targets inside the Browser. In case of multiple browser contexts, returns an array with all the targets in all browser contexts.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

2
new-docs/puppeteer.browser.useragent.md
View File

@ -4,6 +4,8 @@
## Browser.userAgent() method ## Browser.userAgent() method
The browser's original user agent. Pages can override the browser user agent with [Page.setUserAgent()](./puppeteer.page.setuseragent.md)<!-- -->.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript

8
new-docs/puppeteer.browser.version.md
View File

@ -4,6 +4,8 @@
## Browser.version() method ## Browser.version() method
A string representing the browser name and version.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript
@ -13,3 +15,9 @@ version(): Promise<string>;
Promise&lt;string&gt; Promise&lt;string&gt;
## Remarks
For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`<!-- -->. For non-headless, this is similar to `Chrome/61.0.3153.0`<!-- -->.
The format of browser.version() might change with future releases of Chromium.

22
new-docs/puppeteer.browser.waitfortarget.md
View File

@ -4,24 +4,34 @@
## Browser.waitForTarget() method ## Browser.waitForTarget() method
Searches for a target in all browser contexts.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript
waitForTarget(predicate: (x: Target) => boolean, options?: { waitForTarget(predicate: (x: Target) => boolean, options?: WaitForTargetOptions): Promise<Target>;
timeout?: number;
}): Promise<Target>;
``` ```
## Parameters ## Parameters
| Parameter | Type | Description | | Parameter | Type | Description |
| --- | --- | --- | | --- | --- | --- |
| predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean | | | predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean | A function to be run for every target. |
| options | { timeout?: number; } | | | options | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | |
<b>Returns:</b> <b>Returns:</b>
Promise&lt;[Target](./puppeteer.target.md)<!-- -->&gt; Promise&lt;[Target](./puppeteer.target.md)<!-- -->&gt;
{<!-- -->!Promise<!-- -->&lt;<!-- -->!Target<!-- -->&gt;<!-- -->} The first target found that matches the `predicate` function.
## Example
An example of finding a target for a page opened via `window.open`<!-- -->:
```js
await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');
```

10
new-docs/puppeteer.browser.wsendpoint.md
View File

@ -4,6 +4,8 @@
## Browser.wsEndpoint() method ## Browser.wsEndpoint() method
The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->.
<b>Signature:</b> <b>Signature:</b>
```typescript ```typescript
@ -13,3 +15,11 @@ wsEndpoint(): string;
string string
The Browser websocket url.
## Remarks
The format is `ws://${host}:${port}/devtools/browser/<id>`<!-- -->.
You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`<!-- -->. Learn more about the [devtools protocol](https://chromedevtools.github.io/devtools-protocol) and the [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target)<!-- -->.

3
new-docs/puppeteer.md
View File

@ -9,7 +9,7 @@
| Class | Description | | Class | Description |
| --- | --- | | --- | --- |
| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access)<!-- -->. | | [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access)<!-- -->. |
| [Browser](./puppeteer.browser.md) | | | [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->. |
| [BrowserContext](./puppeteer.browsercontext.md) | | | [BrowserContext](./puppeteer.browsercontext.md) | |
| [BrowserFetcher](./puppeteer.browserfetcher.md) | | | [BrowserFetcher](./puppeteer.browserfetcher.md) | |
| [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. | | [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
@ -56,6 +56,7 @@
| [PressOptions](./puppeteer.pressoptions.md) | | | [PressOptions](./puppeteer.pressoptions.md) | |
| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | | [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. |
| [SnapshotOptions](./puppeteer.snapshotoptions.md) | | | [SnapshotOptions](./puppeteer.snapshotoptions.md) | |
| [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | |
## Variables ## Variables

19
new-docs/puppeteer.waitfortargetoptions.md Normal file
View File

@ -0,0 +1,19 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md)
## WaitForTargetOptions interface
<b>Signature:</b>
```typescript
export interface WaitForTargetOptions
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [timeout](./puppeteer.waitfortargetoptions.timeout.md) | number | Maximum wait time in milliseconds. Pass <code>0</code> to disable the timeout. |

13
new-docs/puppeteer.waitfortargetoptions.timeout.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) &gt; [timeout](./puppeteer.waitfortargetoptions.timeout.md)
## WaitForTargetOptions.timeout property
Maximum wait time in milliseconds. Pass `0` to disable the timeout.
<b>Signature:</b>
```typescript
timeout?: number;
```

205
src/common/Browser.ts
View File

@ -27,7 +27,61 @@ import { Viewport } from './PuppeteerViewport';
type BrowserCloseCallback = () => Promise<void> | void; type BrowserCloseCallback = () => Promise<void> | void;
/**
* @public
*/
export interface WaitForTargetOptions {
/**
* Maximum wait time in milliseconds. Pass `0` to disable the timeout.
* @defaultValue 30 seconds.
*/
timeout?: number;
}
/**
* A Browser is created when Puppeteer connects to a Chromium instance, either through
* {@link Puppeteer.launch} or {@link Puppeteer.connect}.
*
* @example
*
* An example of using a {@link Browser} to create a {@link Page}:
* ```js
* const puppeteer = require('puppeteer');
*
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* await page.goto('https://example.com');
* await browser.close();
* })();
* ```
*
* @example
*
* An example of disconnecting from and reconnecting to a {@link Browser}:
* ```js
* const puppeteer = require('puppeteer');
*
* (async () => {
* const browser = await puppeteer.launch();
* // Store the endpoint to be able to reconnect to Chromium
* const browserWSEndpoint = browser.wsEndpoint();
* // Disconnect puppeteer from Chromium
* browser.disconnect();
*
* // Use the endpoint to reestablish a connection
* const browser2 = await puppeteer.connect({browserWSEndpoint});
* // Close Chromium
* await browser2.close();
* })();
* ```
*
* @public
*/
export class Browser extends EventEmitter { export class Browser extends EventEmitter {
/**
* @internal
*/
static async create( static async create(
connection: Connection, connection: Connection,
contextIds: string[], contextIds: string[],
@ -47,15 +101,22 @@ export class Browser extends EventEmitter {
await connection.send('Target.setDiscoverTargets', { discover: true }); await connection.send('Target.setDiscoverTargets', { discover: true });
return browser; return browser;
} }
_ignoreHTTPSErrors: boolean; private _ignoreHTTPSErrors: boolean;
_defaultViewport?: Viewport; private _defaultViewport?: Viewport;
_process?: ChildProcess; private _process?: ChildProcess;
_connection: Connection; private _connection: Connection;
_closeCallback: BrowserCloseCallback; private _closeCallback: BrowserCloseCallback;
_defaultContext: BrowserContext; private _defaultContext: BrowserContext;
_contexts: Map<string, BrowserContext>; private _contexts: Map<string, BrowserContext>;
/**
* @internal
* Used in Target.ts directly so cannot be marked private.
*/
_targets: Map<string, Target>; _targets: Map<string, Target>;
/**
* @internal
*/
constructor( constructor(
connection: Connection, connection: Connection,
contextIds: string[], contextIds: string[],
@ -94,10 +155,31 @@ export class Browser extends EventEmitter {
); );
} }
/**
* The spawned browser process. Returns `null` if the browser instance was created with
* {@link Puppeteer.connect}.
*/
process(): ChildProcess | null { process(): ChildProcess | null {
return this._process; return this._process;
} }
/**
* Creates a new incognito browser context. This won't share cookies/cache with other
* browser contexts.
*
* @example
* ```js
* (async () => {
* const browser = await puppeteer.launch();
* // Create a new incognito browser context.
* const context = await browser.createIncognitoBrowserContext();
* // Create a new page in a pristine context.
* const page = await context.newPage();
* // Do stuff
* await page.goto('https://example.com');
* })();
* ```
*/
async createIncognitoBrowserContext(): Promise<BrowserContext> { async createIncognitoBrowserContext(): Promise<BrowserContext> {
const { browserContextId } = await this._connection.send( const { browserContextId } = await this._connection.send(
'Target.createBrowserContext' 'Target.createBrowserContext'
@ -111,16 +193,24 @@ export class Browser extends EventEmitter {
return context; return context;
} }
/**
* Returns an array of all open browser contexts. In a newly created browser, this will
* return a single instance of {@link BrowserContext}.
*/
browserContexts(): BrowserContext[] { browserContexts(): BrowserContext[] {
return [this._defaultContext, ...Array.from(this._contexts.values())]; return [this._defaultContext, ...Array.from(this._contexts.values())];
} }
/**
* Returns the default browser context. The default browser context cannot be closed.
*/
defaultBrowserContext(): BrowserContext { defaultBrowserContext(): BrowserContext {
return this._defaultContext; return this._defaultContext;
} }
/** /**
* @param {?string} contextId * @internal
* Used by BrowserContext directly so cannot be marked private.
*/ */
async _disposeContext(contextId?: string): Promise<void> { async _disposeContext(contextId?: string): Promise<void> {
await this._connection.send('Target.disposeBrowserContext', { await this._connection.send('Target.disposeBrowserContext', {
@ -129,7 +219,7 @@ export class Browser extends EventEmitter {
this._contexts.delete(contextId); this._contexts.delete(contextId);
} }
async _targetCreated( private async _targetCreated(
event: Protocol.Target.targetCreatedPayload event: Protocol.Target.targetCreatedPayload
): Promise<void> { ): Promise<void> {
const targetInfo = event.targetInfo; const targetInfo = event.targetInfo;
@ -158,10 +248,7 @@ export class Browser extends EventEmitter {
} }
} }
/** private async _targetDestroyed(event: { targetId: string }): Promise<void> {
* @param {{targetId: string}} event
*/
async _targetDestroyed(event: { targetId: string }): Promise<void> {
const target = this._targets.get(event.targetId); const target = this._targets.get(event.targetId);
target._initializedCallback(false); target._initializedCallback(false);
this._targets.delete(event.targetId); this._targets.delete(event.targetId);
@ -174,10 +261,9 @@ export class Browser extends EventEmitter {
} }
} }
/** private _targetInfoChanged(
* @param {!Protocol.Target.targetInfoChangedPayload} event event: Protocol.Target.targetInfoChangedPayload
*/ ): void {
_targetInfoChanged(event: Protocol.Target.targetInfoChangedPayload): void {
const target = this._targets.get(event.targetInfo.targetId); const target = this._targets.get(event.targetInfo.targetId);
assert(target, 'target should exist before targetInfoChanged'); assert(target, 'target should exist before targetInfoChanged');
const previousURL = target.url(); const previousURL = target.url();
@ -189,14 +275,38 @@ export class Browser extends EventEmitter {
} }
} }
/**
* The browser websocket endpoint which can be used as an argument to
* {@link Puppeteer.connect}.
*
* @returns The Browser websocket url.
*
* @remarks
*
* The format is `ws://${host}:${port}/devtools/browser/<id>`.
*
* You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`.
* Learn more about the
* {@link https://chromedevtools.github.io/devtools-protocol | devtools protocol} and
* the {@link
* https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
* | browser endpoint}.
*/
wsEndpoint(): string { wsEndpoint(): string {
return this._connection.url(); return this._connection.url();
} }
/**
* Creates a {@link Page} in the default browser context.
*/
async newPage(): Promise<Page> { async newPage(): Promise<Page> {
return this._defaultContext.newPage(); return this._defaultContext.newPage();
} }
/**
* @internal
* Used by BrowserContext directly so cannot be marked private.
*/
async _createPageInContext(contextId?: string): Promise<Page> { async _createPageInContext(contextId?: string): Promise<Page> {
const { targetId } = await this._connection.send('Target.createTarget', { const { targetId } = await this._connection.send('Target.createTarget', {
url: 'about:blank', url: 'about:blank',
@ -211,24 +321,40 @@ export class Browser extends EventEmitter {
return page; return page;
} }
/**
* All active targets inside the Browser. In case of multiple browser contexts, returns
* an array with all the targets in all browser contexts.
*/
targets(): Target[] { targets(): Target[] {
return Array.from(this._targets.values()).filter( return Array.from(this._targets.values()).filter(
(target) => target._isInitialized (target) => target._isInitialized
); );
} }
/**
* The target associated with the browser.
*/
target(): Target { target(): Target {
return this.targets().find((target) => target.type() === 'browser'); return this.targets().find((target) => target.type() === 'browser');
} }
/** /**
* @param {function(!Target):boolean} predicate * Searches for a target in all browser contexts.
* @param {{timeout?: number}=} options *
* @returns {!Promise<!Target>} * @param predicate - A function to be run for every target.
* @returns The first target found that matches the `predicate` function.
*
* @example
*
* An example of finding a target for a page opened via `window.open`:
* ```js
* await page.evaluate(() => window.open('https://www.example.com/'));
* const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');
* ```
*/ */
async waitForTarget( async waitForTarget(
predicate: (x: Target) => boolean, predicate: (x: Target) => boolean,
options: { timeout?: number } = {} options: WaitForTargetOptions = {}
): Promise<Target> { ): Promise<Target> {
const { timeout = 30000 } = options; const { timeout = 30000 } = options;
const existingTarget = this.targets().find(predicate); const existingTarget = this.targets().find(predicate);
@ -254,6 +380,15 @@ export class Browser extends EventEmitter {
} }
} }
/**
* An array of all open pages inside the Browser.
*
* @remarks
*
* In case of multiple browser contexts, returns an array with all the pages in all
* browser contexts. Non-visible pages, such as `"background_page"`, will not be listed
* here. You can find them using {@link Target.page}.
*/
async pages(): Promise<Page[]> { async pages(): Promise<Page[]> {
const contextPages = await Promise.all( const contextPages = await Promise.all(
this.browserContexts().map((context) => context.pages()) this.browserContexts().map((context) => context.pages())
@ -262,30 +397,56 @@ export class Browser extends EventEmitter {
return contextPages.reduce((acc, x) => acc.concat(x), []); return contextPages.reduce((acc, x) => acc.concat(x), []);
} }
/**
* A string representing the browser name and version.
*
* @remarks
*
* For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For
* non-headless, this is similar to `Chrome/61.0.3153.0`.
*
* The format of browser.version() might change with future releases of Chromium.
*/
async version(): Promise<string> { async version(): Promise<string> {
const version = await this._getVersion(); const version = await this._getVersion();
return version.product; return version.product;
} }
/**
* The browser's original user agent. Pages can override the browser user agent with
* {@link Page.setUserAgent}.
*/
async userAgent(): Promise<string> { async userAgent(): Promise<string> {
const version = await this._getVersion(); const version = await this._getVersion();
return version.userAgent; return version.userAgent;
} }
/**
* Closes Chromium and all of its pages (if any were opened). The {@link Browser} object
* itself is considered to be disposed and cannot be used anymore.
*/
async close(): Promise<void> { async close(): Promise<void> {
await this._closeCallback.call(null); await this._closeCallback.call(null);
this.disconnect(); this.disconnect();
} }
/**
* Disconnects Puppeteer from the browser, but leaves the Chromium process running.
* After calling `disconnect`, the {@link Browser} object is considered disposed and
* cannot be used anymore.
*/
disconnect(): void { disconnect(): void {
this._connection.dispose(); this._connection.dispose();
} }
/**
* Indicates that the browser is connected.
*/
isConnected(): boolean { isConnected(): boolean {
return !this._connection._closed; return !this._connection._closed;
} }
_getVersion(): Promise<Protocol.Browser.getVersionReturnValue> { private _getVersion(): Promise<Protocol.Browser.getVersionReturnValue> {
return this._connection.send('Browser.getVersion'); return this._connection.send('Browser.getVersion');
} }
} }

7
utils/doclint/check_public_api/index.js
View File

@ -664,6 +664,13 @@ function compareDocumentations(actual, expected) {
expectedName: 'SnapshotOptions', expectedName: 'SnapshotOptions',
}, },
], ],
[
'Method Browser.waitForTarget() options',
{
actualName: 'Object',
expectedName: 'WaitForTargetOptions',
},
],
[ [
'Method EventEmitter.emit() event', 'Method EventEmitter.emit() event',
{ {