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: improve Browser docs (#10925)

Browse Source
This commit is contained in:
jrandolf 2023-09-18 11:05:23 +02:00 committed by GitHub
parent 1bac89e284
commit d088da31b2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 219 additions and 232 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/api/index.md
View File

@ -9,7 +9,7 @@ sidebar_label: API
| Class | Description | | Class | Description |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting the browser'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 the browser'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) | A Browser is created when Puppeteer connects to a browser instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | | [Browser](./puppeteer.browser.md) | <p>[Browser](./puppeteer.browser.md) represents a browser instance that is either:</p><p>- connected to via [Puppeteer.connect()](./puppeteer.puppeteer.connect.md) or - launched by [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md).</p><p>[Browser](./puppeteer.browser.md) [emits](./puppeteer.eventemitter.md) various events which are documented in the [BrowserEvent](./puppeteer.browserevent.md) enum.</p> |
| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | | [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. |
| [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. |
| [Connection](./puppeteer.connection.md) | | | [Connection](./puppeteer.connection.md) | |
@ -73,7 +73,7 @@ sidebar_label: API
| [BoxModel](./puppeteer.boxmodel.md) | | | [BoxModel](./puppeteer.boxmodel.md) | |
| [BrowserConnectOptions](./puppeteer.browserconnectoptions.md) | Generic browser options that can be passed when launching any browser or when connecting to an existing browser instance. | | [BrowserConnectOptions](./puppeteer.browserconnectoptions.md) | Generic browser options that can be passed when launching any browser or when connecting to an existing browser instance. |
| [BrowserContextEvents](./puppeteer.browsercontextevents.md) | | | [BrowserContextEvents](./puppeteer.browsercontextevents.md) | |
| [BrowserContextOptions](./puppeteer.browsercontextoptions.md) | BrowserContext options. | | [BrowserContextOptions](./puppeteer.browsercontextoptions.md) | |
| [BrowserEvents](./puppeteer.browserevents.md) | | | [BrowserEvents](./puppeteer.browserevents.md) | |
| [BrowserLaunchArgumentOptions](./puppeteer.browserlaunchargumentoptions.md) | Launcher options that only apply to Chrome. | | [BrowserLaunchArgumentOptions](./puppeteer.browserlaunchargumentoptions.md) | Launcher options that only apply to Chrome. |
| [CDPSessionEvents](./puppeteer.cdpsessionevents.md) | | | [CDPSessionEvents](./puppeteer.cdpsessionevents.md) | |

6
docs/api/puppeteer.browser.browsercontexts.md
View File

@ -4,13 +4,15 @@ sidebar_label: Browser.browserContexts
# 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). Gets a list of open [browser contexts](./puppeteer.browsercontext.md).
In a newly-created [browser](./puppeteer.browser.md), this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
browserContexts(): BrowserContext[]; abstract browserContexts(): BrowserContext[];
} }
``` ```

4
docs/api/puppeteer.browser.close.md
View File

@ -4,13 +4,13 @@ sidebar_label: Browser.close
# Browser.close() method # Browser.close() method
Closes the browser 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. Closes this [browser](./puppeteer.browser.md) and all associated [pages](./puppeteer.page.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
close(): Promise<void>; abstract close(): Promise<void>;
} }
``` ```

24
docs/api/puppeteer.browser.createincognitobrowsercontext.md
View File

@ -4,13 +4,15 @@ sidebar_label: Browser.createIncognitoBrowserContext
# Browser.createIncognitoBrowserContext() method # Browser.createIncognitoBrowserContext() method
Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. Creates a new incognito [browser context](./puppeteer.browsercontext.md).
This won't share cookies/cache with other [browser contexts](./puppeteer.browsercontext.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
createIncognitoBrowserContext( abstract createIncognitoBrowserContext(
options?: BrowserContextOptions options?: BrowserContextOptions
): Promise<BrowserContext>; ): Promise<BrowserContext>;
} }
@ -29,13 +31,13 @@ Promise&lt;[BrowserContext](./puppeteer.browsercontext.md)&gt;
## Example ## Example
```ts ```ts
(async () => { import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
// Create a new incognito browser context. const browser = await puppeteer.launch();
const context = await browser.createIncognitoBrowserContext(); // Create a new incognito browser context.
// Create a new page in a pristine context. const context = await browser.createIncognitoBrowserContext();
const page = await context.newPage(); // Create a new page in a pristine context.
// Do stuff const page = await context.newPage();
await page.goto('https://example.com'); // Do stuff
})(); await page.goto('https://example.com');
``` ```

8
docs/api/puppeteer.browser.defaultbrowsercontext.md
View File

@ -4,16 +4,20 @@ sidebar_label: Browser.defaultBrowserContext
# Browser.defaultBrowserContext() method # Browser.defaultBrowserContext() method
Returns the default browser context. The default browser context cannot be closed. Gets the default [browser context](./puppeteer.browsercontext.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
defaultBrowserContext(): BrowserContext; abstract defaultBrowserContext(): BrowserContext;
} }
``` ```
**Returns:** **Returns:**
[BrowserContext](./puppeteer.browsercontext.md) [BrowserContext](./puppeteer.browsercontext.md)
## Remarks
The default [browser context](./puppeteer.browsercontext.md) cannot be closed.

2
docs/api/puppeteer.browser.disconnect.md
View File

@ -4,7 +4,7 @@ sidebar_label: Browser.disconnect
# Browser.disconnect() method # Browser.disconnect() method
Disconnects Puppeteer from the browser, but leaves the browser process running. After calling `disconnect`, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore. Disconnects Puppeteer from this [browser](./puppeteer.browser.md), but leaves the process running.
#### Signature: #### Signature:

4
docs/api/puppeteer.browser.isconnected.md
View File

@ -4,13 +4,13 @@ sidebar_label: Browser.isConnected
# Browser.isConnected() method # Browser.isConnected() method
Indicates that the browser is connected. Whether Puppeteer is connected to this [browser](./puppeteer.browser.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
isConnected(): boolean; abstract isConnected(): boolean;
} }
``` ```

78
docs/api/puppeteer.browser.md
View File

@ -4,74 +4,72 @@ sidebar_label: Browser
# Browser class # Browser class
A Browser is created when Puppeteer connects to a browser instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). [Browser](./puppeteer.browser.md) represents a browser instance that is either:
- connected to via [Puppeteer.connect()](./puppeteer.puppeteer.connect.md) or - launched by [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md).
[Browser](./puppeteer.browser.md) [emits](./puppeteer.eventemitter.md) various events which are documented in the [BrowserEvent](./puppeteer.browserevent.md) enum.
#### Signature: #### Signature:
```typescript ```typescript
export declare class Browser extends EventEmitter<BrowserEvents> export declare abstract class Browser extends EventEmitter<BrowserEvents>
``` ```
**Extends:** [EventEmitter](./puppeteer.eventemitter.md)&lt;[BrowserEvents](./puppeteer.browserevents.md)&gt; **Extends:** [EventEmitter](./puppeteer.eventemitter.md)&lt;[BrowserEvents](./puppeteer.browserevents.md)&gt;
## Remarks ## Remarks
The Browser class extends from Puppeteer's [EventEmitter](./puppeteer.eventemitter.md) class and will emit various events which are documented in the [BrowserEvent](./puppeteer.browserevent.md) enum.
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. 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.
## Example 1 ## Example 1
An example of using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md): Using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md):
```ts ```ts
import puppeteer from 'puppeteer'; import puppeteer from 'puppeteer';
(async () => { const browser = await puppeteer.launch();
const browser = await puppeteer.launch(); const page = await browser.newPage();
const page = await browser.newPage(); await page.goto('https://example.com');
await page.goto('https://example.com'); await browser.close();
await browser.close();
})();
``` ```
## Example 2 ## Example 2
An example of disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md): Disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md):
```ts ```ts
import puppeteer from 'puppeteer'; import puppeteer from 'puppeteer';
(async () => { const browser = await puppeteer.launch();
const browser = await puppeteer.launch(); // Store the endpoint to be able to reconnect to the browser.
// Store the endpoint to be able to reconnect to the browser. const browserWSEndpoint = browser.wsEndpoint();
const browserWSEndpoint = browser.wsEndpoint(); // Disconnect puppeteer from the browser.
// Disconnect puppeteer from the browser. browser.disconnect();
browser.disconnect();
// Use the endpoint to reestablish a connection // Use the endpoint to reestablish a connection
const browser2 = await puppeteer.connect({browserWSEndpoint}); const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close the browser. // Close the browser.
await browser2.close(); await browser2.close();
})();
``` ```
## Methods ## Methods
| Method | Modifiers | Description | | Method | Modifiers | Description |
| ---------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ---------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [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). | | [browserContexts()](./puppeteer.browser.browsercontexts.md) | | <p>Gets a list of open [browser contexts](./puppeteer.browsercontext.md).</p><p>In a newly-created [browser](./puppeteer.browser.md), this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md).</p> |
| [close()](./puppeteer.browser.close.md) | | Closes the browser 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. | | [close()](./puppeteer.browser.close.md) | | Closes this [browser](./puppeteer.browser.md) and all associated [pages](./puppeteer.page.md). |
| [createIncognitoBrowserContext(options)](./puppeteer.browser.createincognitobrowsercontext.md) | | Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. | | [createIncognitoBrowserContext(options)](./puppeteer.browser.createincognitobrowsercontext.md) | | <p>Creates a new incognito [browser context](./puppeteer.browsercontext.md).</p><p>This won't share cookies/cache with other [browser contexts](./puppeteer.browsercontext.md).</p> |
| [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | Returns the default browser context. The default browser context cannot be closed. | | [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | Gets the default [browser context](./puppeteer.browsercontext.md). |
| [disconnect()](./puppeteer.browser.disconnect.md) | | Disconnects Puppeteer from the browser, but leaves the browser process running. After calling <code>disconnect</code>, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore. | | [disconnect()](./puppeteer.browser.disconnect.md) | | Disconnects Puppeteer from this [browser](./puppeteer.browser.md), but leaves the process running. |
| [isConnected()](./puppeteer.browser.isconnected.md) | | Indicates that the browser is connected. | | [isConnected()](./puppeteer.browser.isconnected.md) | | Whether Puppeteer is connected to this [browser](./puppeteer.browser.md). |
| [newPage()](./puppeteer.browser.newpage.md) | | Promise which resolves to a new [Page](./puppeteer.page.md) object. The Page is created in a default browser context. | | [newPage()](./puppeteer.browser.newpage.md) | | Creates a new [page](./puppeteer.page.md) in the [default browser context](./puppeteer.browser.defaultbrowsercontext.md). |
| [pages()](./puppeteer.browser.pages.md) | | An array of all open pages inside the Browser. | | [pages()](./puppeteer.browser.pages.md) | | <p>Gets a list of all open [pages](./puppeteer.page.md) inside this .</p><p>If there ar multiple [browser contexts](./puppeteer.browsercontext.md), this returns all [pages](./puppeteer.page.md) in all [browser contexts](./puppeteer.browsercontext.md).</p> |
| [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). | | [process()](./puppeteer.browser.process.md) | | Gets the associated [ChildProcess](https://nodejs.org/api/child_process.html#class-childprocess). |
| [target()](./puppeteer.browser.target.md) | | The target associated with the browser. | | [target()](./puppeteer.browser.target.md) | | Gets the [target](./puppeteer.target.md) associated with the [default browser context](./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. | | [targets()](./puppeteer.browser.targets.md) | | <p>Gets all active [targets](./puppeteer.target.md).</p><p>In case of multiple [browser contexts](./puppeteer.browsercontext.md), this returns all [targets](./puppeteer.target.md) in all [browser contexts](./puppeteer.browsercontext.md).</p> |
| [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). | | [userAgent()](./puppeteer.browser.useragent.md) | | <p>Gets this [browser's](./puppeteer.browser.md) original user agent.</p><p>[Pages](./puppeteer.page.md) can override the user agent with [Page.setUserAgent()](./puppeteer.page.setuseragent.md).</p> |
| [version()](./puppeteer.browser.version.md) | | A string representing the browser name and version. | | [version()](./puppeteer.browser.version.md) | | <p>Gets a string representing this [browser's](./puppeteer.browser.md) name and version.</p><p>For headless browser, this is similar to <code>&quot;HeadlessChrome/61.0.3153.0&quot;</code>. For non-headless or new-headless, this is similar to <code>&quot;Chrome/61.0.3153.0&quot;</code>. For Firefox, it is similar to <code>&quot;Firefox/116.0a1&quot;</code>.</p><p>The format of [Browser.version()](./puppeteer.browser.version.md) might change with future releases of browsers.</p> |
| [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | Searches for a target in all browser contexts. | | [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | <p>Waits until a [target](./puppeteer.target.md) matching the given <code>predicate</code> appears and returns it.</p><p>This will look all open [browser contexts](./puppeteer.browsercontext.md).</p> |
| [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | | [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | <p>Gets the WebSocket URL to connect to this [browser](./puppeteer.browser.md).</p><p>This is usually used with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).</p><p>You can find the debugger URL (<code>webSocketDebuggerUrl</code>) from <code>http://${host}:${port}/json/version</code>.</p><p>See [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target) for more information.</p> |

4
docs/api/puppeteer.browser.newpage.md
View File

@ -4,13 +4,13 @@ sidebar_label: Browser.newPage
# Browser.newPage() method # Browser.newPage() method
Promise which resolves to a new [Page](./puppeteer.page.md) object. The Page is created in a default browser context. Creates a new [page](./puppeteer.page.md) in the [default browser context](./puppeteer.browser.defaultbrowsercontext.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
newPage(): Promise<Page>; abstract newPage(): Promise<Page>;
} }
``` ```

6
docs/api/puppeteer.browser.pages.md
View File

@ -4,7 +4,9 @@ sidebar_label: Browser.pages
# Browser.pages() method # Browser.pages() method
An array of all open pages inside the Browser. Gets a list of all open [pages](./puppeteer.page.md) inside this .
If there ar multiple [browser contexts](./puppeteer.browsercontext.md), this returns all [pages](./puppeteer.page.md) in all [browser contexts](./puppeteer.browsercontext.md).
#### Signature: #### Signature:
@ -20,4 +22,4 @@ Promise&lt;[Page](./puppeteer.page.md)\[\]&gt;
## Remarks ## 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). Non-visible [pages](./puppeteer.page.md), such as `"background_page"`, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md).

4
docs/api/puppeteer.browser.process.md
View File

@ -4,7 +4,7 @@ sidebar_label: Browser.process
# 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). Gets the associated [ChildProcess](https://nodejs.org/api/child_process.html#class-childprocess).
#### Signature: #### Signature:
@ -17,3 +17,5 @@ class Browser {
**Returns:** **Returns:**
ChildProcess \| null ChildProcess \| null
`null` if this instance was connected to via [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).

4
docs/api/puppeteer.browser.target.md
View File

@ -4,13 +4,13 @@ sidebar_label: Browser.target
# Browser.target() method # Browser.target() method
The target associated with the browser. Gets the [target](./puppeteer.target.md) associated with the [default browser context](./puppeteer.browser.defaultbrowsercontext.md)).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
target(): Target; abstract target(): Target;
} }
``` ```

6
docs/api/puppeteer.browser.targets.md
View File

@ -4,13 +4,15 @@ sidebar_label: Browser.targets
# 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. Gets all active [targets](./puppeteer.target.md).
In case of multiple [browser contexts](./puppeteer.browsercontext.md), this returns all [targets](./puppeteer.target.md) in all [browser contexts](./puppeteer.browsercontext.md).
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
targets(): Target[]; abstract targets(): Target[];
} }
``` ```

4
docs/api/puppeteer.browser.useragent.md
View File

@ -4,7 +4,9 @@ sidebar_label: Browser.userAgent
# 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). Gets this [browser's](./puppeteer.browser.md) original user agent.
[Pages](./puppeteer.page.md) can override the user agent with [Page.setUserAgent()](./puppeteer.page.setuseragent.md).
#### Signature: #### Signature:

14
docs/api/puppeteer.browser.version.md
View File

@ -4,22 +4,20 @@ sidebar_label: Browser.version
# Browser.version() method # Browser.version() method
A string representing the browser name and version. Gets a string representing this [browser's](./puppeteer.browser.md) name and version.
For headless browser, this is similar to `"HeadlessChrome/61.0.3153.0"`. For non-headless or new-headless, this is similar to `"Chrome/61.0.3153.0"`. For Firefox, it is similar to `"Firefox/116.0a1"`.
The format of [Browser.version()](./puppeteer.browser.version.md) might change with future releases of browsers.
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
version(): Promise<string>; abstract version(): Promise<string>;
} }
``` ```
**Returns:** **Returns:**
Promise&lt;string&gt; Promise&lt;string&gt;
## Remarks
For headless browser, this is similar to `HeadlessChrome/61.0.3153.0`. For non-headless or new-headless, this is similar to `Chrome/61.0.3153.0`. For Firefox, it is similar to `Firefox/116.0a1`.
The format of browser.version() might change with future releases of browsers.

16
docs/api/puppeteer.browser.waitfortarget.md
View File

@ -4,7 +4,9 @@ sidebar_label: Browser.waitForTarget
# Browser.waitForTarget() method # Browser.waitForTarget() method
Searches for a target in all browser contexts. Waits until a [target](./puppeteer.target.md) matching the given `predicate` appears and returns it.
This will look all open [browser contexts](./puppeteer.browsercontext.md).
#### Signature: #### Signature:
@ -19,20 +21,18 @@ class Browser {
## Parameters ## Parameters
| Parameter | Type | Description | | Parameter | Type | Description |
| --------- | ---------------------------------------------------------------------------- | -------------------------------------- | | --------- | ---------------------------------------------------------------------------- | ------------ |
| predicate | (x: [Target](./puppeteer.target.md)) =&gt; boolean \| Promise&lt;boolean&gt; | A function to be run for every target. | | predicate | (x: [Target](./puppeteer.target.md)) =&gt; boolean \| Promise&lt;boolean&gt; | |
| options | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | _(Optional)_ | | options | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | _(Optional)_ |
**Returns:** **Returns:**
Promise&lt;[Target](./puppeteer.target.md)&gt; Promise&lt;[Target](./puppeteer.target.md)&gt;
The first target found that matches the `predicate` function.
## Example ## Example
An example of finding a target for a page opened via `window.open`: Finding a target for a page opened via `window.open`:
```ts ```ts
await page.evaluate(() => window.open('https://www.example.com/')); await page.evaluate(() => window.open('https://www.example.com/'));

16
docs/api/puppeteer.browser.wsendpoint.md
View File

@ -4,13 +4,19 @@ sidebar_label: Browser.wsEndpoint
# Browser.wsEndpoint() method # Browser.wsEndpoint() method
The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). Gets the WebSocket URL to connect to this [browser](./puppeteer.browser.md).
This is usually used with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).
You can find the debugger URL (`webSocketDebuggerUrl`) from `http://${host}:${port}/json/version`.
See [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target) for more information.
#### Signature: #### Signature:
```typescript ```typescript
class Browser { class Browser {
wsEndpoint(): string; abstract wsEndpoint(): string;
} }
``` ```
@ -18,10 +24,6 @@ class Browser {
string string
The Browser websocket url.
## Remarks ## Remarks
The format is `ws://${host}:${port}/devtools/browser/<id>`. The format is always `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).

2
docs/api/puppeteer.browsercontextoptions.md
View File

@ -4,8 +4,6 @@ sidebar_label: BrowserContextOptions
# BrowserContextOptions interface # BrowserContextOptions interface
BrowserContext options.
#### Signature: #### Signature:
```typescript ```typescript

4
docs/api/puppeteer.browserevent.md
View File

@ -16,7 +16,7 @@ export declare const enum BrowserEvent
| Member | Value | Description | | Member | Value | Description |
| --------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disconnected | <code>&quot;disconnected&quot;</code> | <p>Emitted when Puppeteer gets disconnected from the browser instance. This might happen because of one of the following:</p><p>- browser is closed or crashed</p><p>- The [browser.disconnect](./puppeteer.browser.disconnect.md) method was called.</p> | | Disconnected | <code>&quot;disconnected&quot;</code> | <p>Emitted when Puppeteer gets disconnected from the browser instance. This might happen because either:</p><p>- The browser closes/crashes or - [Browser.disconnect()](./puppeteer.browser.disconnect.md) was called.</p> |
| TargetChanged | <code>&quot;targetchanged&quot;</code> | Emitted when the url of a target changes. Contains a [Target](./puppeteer.target.md) instance. | | TargetChanged | <code>&quot;targetchanged&quot;</code> | Emitted when the URL of a target changes. Contains a [Target](./puppeteer.target.md) instance. |
| TargetCreated | <code>&quot;targetcreated&quot;</code> | <p>Emitted when a target is created, for example when a new page is opened by [window.open](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or by [browser.newPage](./puppeteer.browser.newpage.md)</p><p>Contains a [Target](./puppeteer.target.md) instance.</p> | | TargetCreated | <code>&quot;targetcreated&quot;</code> | <p>Emitted when a target is created, for example when a new page is opened by [window.open](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) or by [browser.newPage](./puppeteer.browser.newpage.md)</p><p>Contains a [Target](./puppeteer.target.md) instance.</p> |
| TargetDestroyed | <code>&quot;targetdestroyed&quot;</code> | Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance. | | TargetDestroyed | <code>&quot;targetdestroyed&quot;</code> | Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance. |

241
packages/puppeteer-core/src/api/Browser.ts
View File

@ -14,8 +14,6 @@
* limitations under the License. * limitations under the License.
*/ */
/* eslint-disable @typescript-eslint/no-unused-vars */
import {type ChildProcess} from 'child_process'; import {type ChildProcess} from 'child_process';
import {type Protocol} from 'devtools-protocol'; import {type Protocol} from 'devtools-protocol';
@ -30,8 +28,6 @@ import type {Page} from './Page.js';
import type {Target} from './Target.js'; import type {Target} from './Target.js';
/** /**
* BrowserContext options.
*
* @public * @public
*/ */
export interface BrowserContextOptions { export interface BrowserContextOptions {
@ -120,6 +116,7 @@ export type Permission =
export interface WaitForTargetOptions { export interface WaitForTargetOptions {
/** /**
* Maximum wait time in milliseconds. Pass `0` to disable the timeout. * Maximum wait time in milliseconds. Pass `0` to disable the timeout.
*
* @defaultValue `30_000` * @defaultValue `30_000`
*/ */
timeout?: number; timeout?: number;
@ -133,19 +130,18 @@ export interface WaitForTargetOptions {
export const enum BrowserEvent { export const enum BrowserEvent {
/** /**
* Emitted when Puppeteer gets disconnected from the browser instance. This * Emitted when Puppeteer gets disconnected from the browser instance. This
* might happen because of one of the following: * might happen because either:
* *
* - browser is closed or crashed * - The browser closes/crashes or
* * - {@link Browser.disconnect} was called.
* - The {@link Browser.disconnect | browser.disconnect } method was called.
*/ */
Disconnected = 'disconnected', Disconnected = 'disconnected',
/** /**
* Emitted when the url of a target changes. Contains a {@link Target} instance. * Emitted when the URL of a target changes. Contains a {@link Target}
* instance.
* *
* @remarks * @remarks Note that this includes target changes in incognito browser
* * contexts.
* Note that this includes target changes in incognito browser contexts.
*/ */
TargetChanged = 'targetchanged', TargetChanged = 'targetchanged',
/** /**
@ -155,18 +151,16 @@ export const enum BrowserEvent {
* *
* Contains a {@link Target} instance. * Contains a {@link Target} instance.
* *
* @remarks * @remarks Note that this includes target creations in incognito browser
* * contexts.
* Note that this includes target creations in incognito browser contexts.
*/ */
TargetCreated = 'targetcreated', TargetCreated = 'targetcreated',
/** /**
* Emitted when a target is destroyed, for example when a page is closed. * Emitted when a target is destroyed, for example when a page is closed.
* Contains a {@link Target} instance. * Contains a {@link Target} instance.
* *
* @remarks * @remarks Note that this includes target destructions in incognito browser
* * contexts.
* Note that this includes target destructions in incognito browser contexts.
*/ */
TargetDestroyed = 'targetdestroyed', TargetDestroyed = 'targetdestroyed',
/** /**
@ -197,51 +191,45 @@ export interface BrowserEvents extends Record<EventType, unknown> {
} }
/** /**
* A Browser is created when Puppeteer connects to a browser instance, either through * {@link Browser} represents a browser instance that is either:
* {@link PuppeteerNode.launch} or {@link Puppeteer.connect}.
* *
* @remarks * - connected to via {@link Puppeteer.connect} or
* - launched by {@link PuppeteerNode.launch}.
* *
* The Browser class extends from Puppeteer's {@link EventEmitter} class and will * {@link Browser} {@link EventEmitter | emits} various events which are
* emit various events which are documented in the {@link BrowserEvent} enum. * documented in the {@link BrowserEvent} enum.
* *
* @example * @example Using a {@link Browser} to create a {@link Page}:
* An example of using a {@link Browser} to create a {@link Page}:
* *
* ```ts * ```ts
* import puppeteer from 'puppeteer'; * import puppeteer from 'puppeteer';
* *
* (async () => { * const browser = await puppeteer.launch();
* const browser = await puppeteer.launch(); * const page = await browser.newPage();
* const page = await browser.newPage(); * await page.goto('https://example.com');
* await page.goto('https://example.com'); * await browser.close();
* await browser.close();
* })();
* ``` * ```
* *
* @example * @example Disconnecting from and reconnecting to a {@link Browser}:
* An example of disconnecting from and reconnecting to a {@link Browser}:
* *
* ```ts * ```ts
* import puppeteer from 'puppeteer'; * import puppeteer from 'puppeteer';
* *
* (async () => { * const browser = await puppeteer.launch();
* const browser = await puppeteer.launch(); * // Store the endpoint to be able to reconnect to the browser.
* // Store the endpoint to be able to reconnect to the browser. * const browserWSEndpoint = browser.wsEndpoint();
* const browserWSEndpoint = browser.wsEndpoint(); * // Disconnect puppeteer from the browser.
* // Disconnect puppeteer from the browser. * browser.disconnect();
* browser.disconnect();
* *
* // Use the endpoint to reestablish a connection * // Use the endpoint to reestablish a connection
* const browser2 = await puppeteer.connect({browserWSEndpoint}); * const browser2 = await puppeteer.connect({browserWSEndpoint});
* // Close the browser. * // Close the browser.
* await browser2.close(); * await browser2.close();
* })();
* ``` * ```
* *
* @public * @public
*/ */
export class Browser extends EventEmitter<BrowserEvents> { export abstract class Browser extends EventEmitter<BrowserEvents> {
/** /**
* @internal * @internal
*/ */
@ -271,7 +259,10 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* The spawned browser process. Returns `null` if the browser instance was created with * Gets the associated
* {@link https://nodejs.org/api/child_process.html#class-childprocess | ChildProcess}.
*
* @returns `null` if this instance was connected to via
* {@link Puppeteer.connect}. * {@link Puppeteer.connect}.
*/ */
process(): ChildProcess | null { process(): ChildProcess | null {
@ -286,44 +277,43 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* Creates a new incognito browser context. This won't share cookies/cache with other * Creates a new incognito {@link BrowserContext | browser context}.
* browser contexts. *
* This won't share cookies/cache with other {@link BrowserContext | browser contexts}.
* *
* @example * @example
* *
* ```ts * ```ts
* (async () => { * import puppeteer from 'puppeteer';
* const browser = await puppeteer.launch(); *
* // Create a new incognito browser context. * const browser = await puppeteer.launch();
* const context = await browser.createIncognitoBrowserContext(); * // Create a new incognito browser context.
* // Create a new page in a pristine context. * const context = await browser.createIncognitoBrowserContext();
* const page = await context.newPage(); * // Create a new page in a pristine context.
* // Do stuff * const page = await context.newPage();
* await page.goto('https://example.com'); * // Do stuff
* })(); * await page.goto('https://example.com');
* ``` * ```
*/ */
createIncognitoBrowserContext( abstract createIncognitoBrowserContext(
options?: BrowserContextOptions options?: BrowserContextOptions
): Promise<BrowserContext>; ): Promise<BrowserContext>;
createIncognitoBrowserContext(): Promise<BrowserContext> {
throw new Error('Not implemented');
}
/** /**
* Returns an array of all open browser contexts. In a newly created browser, this will * Gets a list of open {@link BrowserContext | browser contexts}.
* return a single instance of {@link BrowserContext}. *
* In a newly-created {@link Browser | browser}, this will return a single
* instance of {@link BrowserContext}.
*/ */
browserContexts(): BrowserContext[] { abstract browserContexts(): BrowserContext[];
throw new Error('Not implemented');
}
/** /**
* Returns the default browser context. The default browser context cannot be closed. * Gets the default {@link BrowserContext | browser context}.
*
* @remarks The default {@link BrowserContext | browser context} cannot be
* closed.
*/ */
defaultBrowserContext(): BrowserContext { abstract defaultBrowserContext(): BrowserContext;
throw new Error('Not implemented');
}
/** /**
* @internal * @internal
@ -334,33 +324,26 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* The browser websocket endpoint which can be used as an argument to * Gets the WebSocket URL to connect to this {@link Browser | browser}.
* {@link Puppeteer.connect}.
* *
* @returns The Browser websocket url. * This is usually used with {@link Puppeteer.connect}.
* *
* @remarks * You can find the debugger URL (`webSocketDebuggerUrl`) from
* `http://${host}:${port}/json/version`.
* *
* The format is `ws://${host}:${port}/devtools/browser/<id>`. * See {@link
*
* 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 * https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
* | browser endpoint}. * | browser endpoint} for more information.
*
* @remarks The format is always `ws://${host}:${port}/devtools/browser/<id>`.
*/ */
wsEndpoint(): string { abstract wsEndpoint(): string;
throw new Error('Not implemented');
}
/** /**
* Promise which resolves to a new {@link Page} object. The Page is created in * Creates a new {@link Page | page} in the
* a default browser context. * {@link Browser.defaultBrowserContext | default browser context}.
*/ */
newPage(): Promise<Page> { abstract newPage(): Promise<Page>;
throw new Error('Not implemented');
}
/** /**
* @internal * @internal
@ -371,29 +354,27 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* All active targets inside the Browser. In case of multiple browser contexts, returns * Gets all active {@link Target | targets}.
* an array with all the targets in all browser contexts. *
* In case of multiple {@link BrowserContext | browser contexts}, this returns
* all {@link Target | targets} in all
* {@link BrowserContext | browser contexts}.
*/ */
targets(): Target[] { abstract targets(): Target[];
throw new Error('Not implemented');
}
/** /**
* The target associated with the browser. * Gets the {@link Target | target} associated with the
* {@link Browser.defaultBrowserContext | default browser context}).
*/ */
target(): Target { abstract target(): Target;
throw new Error('Not implemented');
}
/** /**
* Searches for a target in all browser contexts. * Waits until a {@link Target | target} matching the given `predicate`
* appears and returns it.
* *
* @param predicate - A function to be run for every target. * This will look all open {@link BrowserContext | browser contexts}.
* @returns The first target found that matches the `predicate` function.
* *
* @example * @example Finding a target for a page opened via `window.open`:
*
* An example of finding a target for a page opened via `window.open`:
* *
* ```ts * ```ts
* await page.evaluate(() => window.open('https://www.example.com/')); * await page.evaluate(() => window.open('https://www.example.com/'));
@ -434,13 +415,14 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* An array of all open pages inside the Browser. * Gets a list of all open {@link Page | pages} inside this {@link browser}.
* *
* @remarks * If there ar multiple {@link BrowserContext | browser contexts}, this
* returns all {@link Page | pages} in all
* {@link BrowserContext | browser contexts}.
* *
* In case of multiple browser contexts, returns an array with all the pages in all * @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
* browser contexts. Non-visible pages, such as `"background_page"`, will not be listed * will not be listed here. You can find them using {@link Target.page}.
* 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(
@ -455,23 +437,22 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* A string representing the browser name and version. * Gets a string representing this {@link Browser | browser's} name and
* version.
* *
* @remarks * For headless browser, this is similar to `"HeadlessChrome/61.0.3153.0"`. For
* non-headless or new-headless, this is similar to `"Chrome/61.0.3153.0"`. For
* Firefox, it is similar to `"Firefox/116.0a1"`.
* *
* For headless browser, this is similar to `HeadlessChrome/61.0.3153.0`. For * The format of {@link Browser.version} might change with future releases of
* non-headless or new-headless, this is similar to `Chrome/61.0.3153.0`. For
* Firefox, it is similar to `Firefox/116.0a1`.
*
* The format of browser.version() might change with future releases of
* browsers. * browsers.
*/ */
version(): Promise<string> { abstract version(): Promise<string>;
throw new Error('Not implemented');
}
/** /**
* The browser's original user agent. Pages can override the browser user agent with * Gets this {@link Browser | browser's} original user agent.
*
* {@link Page | Pages} can override the user agent with
* {@link Page.setUserAgent}. * {@link Page.setUserAgent}.
*/ */
userAgent(): Promise<string> { userAgent(): Promise<string> {
@ -479,29 +460,23 @@ export class Browser extends EventEmitter<BrowserEvents> {
} }
/** /**
* Closes the browser and all of its pages (if any were opened). The * Closes this {@link Browser | browser} and all associated
* {@link Browser} object itself is considered to be disposed and cannot be * {@link Page | pages}.
* used anymore.
*/ */
close(): Promise<void> { abstract close(): Promise<void>;
throw new Error('Not implemented');
}
/** /**
* Disconnects Puppeteer from the browser, but leaves the browser process running. * Disconnects Puppeteer from this {@link Browser | browser}, but leaves the
* After calling `disconnect`, the {@link Browser} object is considered disposed and * process running.
* cannot be used anymore.
*/ */
disconnect(): void { disconnect(): void {
throw new Error('Not implemented'); throw new Error('Not implemented');
} }
/** /**
* Indicates that the browser is connected. * Whether Puppeteer is connected to this {@link Browser | browser}.
*/ */
isConnected(): boolean { abstract isConnected(): boolean;
throw new Error('Not implemented');
}
/** @internal */ /** @internal */
[Symbol.dispose](): void { [Symbol.dispose](): void {