docs: improve Browser docs (#10925)

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

View File

@ -9,7 +9,7 @@ sidebar_label: API
| 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). |
| [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. |
| [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
| [Connection](./puppeteer.connection.md) | |
@ -73,7 +73,7 @@ sidebar_label: API
| [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. |
| [BrowserContextEvents](./puppeteer.browsercontextevents.md) | |
| [BrowserContextOptions](./puppeteer.browsercontextoptions.md) | BrowserContext options. |
| [BrowserContextOptions](./puppeteer.browsercontextoptions.md) | |
| [BrowserEvents](./puppeteer.browserevents.md) | |
| [BrowserLaunchArgumentOptions](./puppeteer.browserlaunchargumentoptions.md) | Launcher options that only apply to Chrome. |
| [CDPSessionEvents](./puppeteer.cdpsessionevents.md) | |

View File

@ -4,13 +4,15 @@ sidebar_label: Browser.browserContexts
# 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:
```typescript
class Browser {
browserContexts(): BrowserContext[];
abstract browserContexts(): BrowserContext[];
}
```

View File

@ -4,13 +4,13 @@ sidebar_label: Browser.close
# 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:
```typescript
class Browser {
close(): Promise<void>;
abstract close(): Promise<void>;
}
```

View File

@ -4,13 +4,15 @@ sidebar_label: Browser.createIncognitoBrowserContext
# 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:
```typescript
class Browser {
createIncognitoBrowserContext(
abstract createIncognitoBrowserContext(
options?: BrowserContextOptions
): Promise<BrowserContext>;
}
@ -29,13 +31,13 @@ Promise&lt;[BrowserContext](./puppeteer.browsercontext.md)&gt;
## Example
```ts
(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');
})();
import puppeteer from 'puppeteer';
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');
```

View File

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

View File

@ -4,7 +4,7 @@ sidebar_label: Browser.disconnect
# 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:

View File

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

View File

@ -4,74 +4,72 @@ sidebar_label: Browser
# 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:
```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;
## 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.
## 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
import puppeteer from 'puppeteer';
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();
})();
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();
```
## 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
import puppeteer from 'puppeteer';
(async () => {
const browser = await puppeteer.launch();
// Store the endpoint to be able to reconnect to the browser.
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from the browser.
browser.disconnect();
const browser = await puppeteer.launch();
// Store the endpoint to be able to reconnect to the browser.
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from the browser.
browser.disconnect();
// Use the endpoint to reestablish a connection
const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close the browser.
await browser2.close();
})();
// Use the endpoint to reestablish a connection
const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close the browser.
await browser2.close();
```
## Methods
| 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). |
| [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. |
| [createIncognitoBrowserContext(options)](./puppeteer.browser.createincognitobrowsercontext.md) | | Creates a new incognito browser context. This won't share cookies/cache with other browser contexts. |
| [defaultBrowserContext()](./puppeteer.browser.defaultbrowsercontext.md) | | Returns the default browser context. The default browser context cannot be closed. |
| [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. |
| [isConnected()](./puppeteer.browser.isconnected.md) | | Indicates that the browser is connected. |
| [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. |
| [pages()](./puppeteer.browser.pages.md) | | An array of all open pages inside the Browser. |
| [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). |
| [target()](./puppeteer.browser.target.md) | | The target associated with the browser. |
| [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. |
| [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). |
| [version()](./puppeteer.browser.version.md) | | A string representing the browser name and version. |
| [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | | Searches for a target in all browser contexts. |
| [wsEndpoint()](./puppeteer.browser.wsendpoint.md) | | The browser websocket endpoint which can be used as an argument to [Puppeteer.connect()](./puppeteer.puppeteer.connect.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 this [browser](./puppeteer.browser.md) and all associated [pages](./puppeteer.page.md). |
| [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) | | Gets the default [browser context](./puppeteer.browsercontext.md). |
| [disconnect()](./puppeteer.browser.disconnect.md) | | Disconnects Puppeteer from this [browser](./puppeteer.browser.md), but leaves the process running. |
| [isConnected()](./puppeteer.browser.isconnected.md) | | Whether Puppeteer is connected to this [browser](./puppeteer.browser.md). |
| [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) | | <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) | | Gets the associated [ChildProcess](https://nodejs.org/api/child_process.html#class-childprocess). |
| [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) | | <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) | | <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) | | <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) | | <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) | | <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> |

View File

@ -4,13 +4,13 @@ sidebar_label: Browser.newPage
# 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:
```typescript
class Browser {
newPage(): Promise<Page>;
abstract newPage(): Promise<Page>;
}
```

View File

@ -4,7 +4,9 @@ sidebar_label: Browser.pages
# 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:
@ -20,4 +22,4 @@ 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).
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).

View File

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

View File

@ -4,13 +4,13 @@ sidebar_label: Browser.target
# 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:
```typescript
class Browser {
target(): Target;
abstract target(): Target;
}
```

View File

@ -4,13 +4,15 @@ sidebar_label: Browser.targets
# 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:
```typescript
class Browser {
targets(): Target[];
abstract targets(): Target[];
}
```

View File

@ -4,7 +4,9 @@ sidebar_label: Browser.userAgent
# 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:

View File

@ -4,22 +4,20 @@ sidebar_label: Browser.version
# 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:
```typescript
class Browser {
version(): Promise<string>;
abstract version(): Promise<string>;
}
```
**Returns:**
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.

View File

@ -4,7 +4,9 @@ sidebar_label: Browser.waitForTarget
# 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:
@ -20,19 +22,17 @@ class Browser {
## Parameters
| 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)_ |
**Returns:**
Promise&lt;[Target](./puppeteer.target.md)&gt;
The first target found that matches the `predicate` function.
## 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
await page.evaluate(() => window.open('https://www.example.com/'));

View File

@ -4,13 +4,19 @@ sidebar_label: Browser.wsEndpoint
# 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:
```typescript
class Browser {
wsEndpoint(): string;
abstract wsEndpoint(): string;
}
```
@ -18,10 +24,6 @@ class Browser {
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).
The format is always `ws://${host}:${port}/devtools/browser/<id>`.

View File

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

View File

@ -16,7 +16,7 @@ export declare const enum BrowserEvent
| 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> |
| TargetChanged | <code>&quot;targetchanged&quot;</code> | Emitted when the url of a target changes. Contains a [Target](./puppeteer.target.md) instance. |
| 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. |
| 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. |

View File

@ -14,8 +14,6 @@
* limitations under the License.
*/
/* eslint-disable @typescript-eslint/no-unused-vars */
import {type ChildProcess} from 'child_process';
import {type Protocol} from 'devtools-protocol';
@ -30,8 +28,6 @@ import type {Page} from './Page.js';
import type {Target} from './Target.js';
/**
* BrowserContext options.
*
* @public
*/
export interface BrowserContextOptions {
@ -120,6 +116,7 @@ export type Permission =
export interface WaitForTargetOptions {
/**
* Maximum wait time in milliseconds. Pass `0` to disable the timeout.
*
* @defaultValue `30_000`
*/
timeout?: number;
@ -133,19 +130,18 @@ export interface WaitForTargetOptions {
export const enum BrowserEvent {
/**
* 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 {@link Browser.disconnect | browser.disconnect } method was called.
* - The browser closes/crashes or
* - {@link Browser.disconnect} was called.
*/
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
*
* Note that this includes target changes in incognito browser contexts.
* @remarks Note that this includes target changes in incognito browser
* contexts.
*/
TargetChanged = 'targetchanged',
/**
@ -155,18 +151,16 @@ export const enum BrowserEvent {
*
* Contains a {@link Target} instance.
*
* @remarks
*
* Note that this includes target creations in incognito browser contexts.
* @remarks Note that this includes target creations in incognito browser
* contexts.
*/
TargetCreated = 'targetcreated',
/**
* Emitted when a target is destroyed, for example when a page is closed.
* Contains a {@link Target} instance.
*
* @remarks
*
* Note that this includes target destructions in incognito browser contexts.
* @remarks Note that this includes target destructions in incognito browser
* contexts.
*/
TargetDestroyed = 'targetdestroyed',
/**
@ -197,35 +191,30 @@ export interface BrowserEvents extends Record<EventType, unknown> {
}
/**
* A Browser is created when Puppeteer connects to a browser instance, either through
* {@link PuppeteerNode.launch} or {@link Puppeteer.connect}.
* {@link Browser} represents a browser instance that is either:
*
* @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
* emit various events which are documented in the {@link BrowserEvent} enum.
* {@link Browser} {@link EventEmitter | emits} various events which are
* documented in the {@link BrowserEvent} enum.
*
* @example
* An example of using a {@link Browser} to create a {@link Page}:
* @example Using a {@link Browser} to create a {@link Page}:
*
* ```ts
* import puppeteer from '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}:
* @example Disconnecting from and reconnecting to a {@link Browser}:
*
* ```ts
* import puppeteer from 'puppeteer';
*
* (async () => {
* const browser = await puppeteer.launch();
* // Store the endpoint to be able to reconnect to the browser.
* const browserWSEndpoint = browser.wsEndpoint();
@ -236,12 +225,11 @@ export interface BrowserEvents extends Record<EventType, unknown> {
* const browser2 = await puppeteer.connect({browserWSEndpoint});
* // Close the browser.
* await browser2.close();
* })();
* ```
*
* @public
*/
export class Browser extends EventEmitter<BrowserEvents> {
export abstract class Browser extends EventEmitter<BrowserEvents> {
/**
* @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}.
*/
process(): ChildProcess | null {
@ -286,13 +277,15 @@ export class Browser extends EventEmitter<BrowserEvents> {
}
/**
* Creates a new incognito browser context. This won't share cookies/cache with other
* browser contexts.
* Creates a new incognito {@link BrowserContext | browser context}.
*
* This won't share cookies/cache with other {@link BrowserContext | browser contexts}.
*
* @example
*
* ```ts
* (async () => {
* import puppeteer from 'puppeteer';
*
* const browser = await puppeteer.launch();
* // Create a new incognito browser context.
* const context = await browser.createIncognitoBrowserContext();
@ -300,30 +293,27 @@ export class Browser extends EventEmitter<BrowserEvents> {
* const page = await context.newPage();
* // Do stuff
* await page.goto('https://example.com');
* })();
* ```
*/
createIncognitoBrowserContext(
abstract createIncognitoBrowserContext(
options?: BrowserContextOptions
): 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
* return a single instance of {@link BrowserContext}.
* Gets a list of open {@link BrowserContext | browser contexts}.
*
* In a newly-created {@link Browser | browser}, this will return a single
* instance of {@link BrowserContext}.
*/
browserContexts(): BrowserContext[] {
throw new Error('Not implemented');
}
abstract browserContexts(): BrowserContext[];
/**
* 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 {
throw new Error('Not implemented');
}
abstract defaultBrowserContext(): BrowserContext;
/**
* @internal
@ -334,33 +324,26 @@ export class Browser extends EventEmitter<BrowserEvents> {
}
/**
* The browser websocket endpoint which can be used as an argument to
* {@link Puppeteer.connect}.
* Gets the WebSocket URL to connect to this {@link Browser | browser}.
*
* @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>`.
*
* 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
* See {@link
* 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 {
throw new Error('Not implemented');
}
abstract wsEndpoint(): string;
/**
* Promise which resolves to a new {@link Page} object. The Page is created in
* a default browser context.
* Creates a new {@link Page | page} in the
* {@link Browser.defaultBrowserContext | default browser context}.
*/
newPage(): Promise<Page> {
throw new Error('Not implemented');
}
abstract newPage(): Promise<Page>;
/**
* @internal
@ -371,29 +354,27 @@ export class Browser extends EventEmitter<BrowserEvents> {
}
/**
* 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 {@link Target | targets}.
*
* In case of multiple {@link BrowserContext | browser contexts}, this returns
* all {@link Target | targets} in all
* {@link BrowserContext | browser contexts}.
*/
targets(): Target[] {
throw new Error('Not implemented');
}
abstract targets(): Target[];
/**
* The target associated with the browser.
* Gets the {@link Target | target} associated with the
* {@link Browser.defaultBrowserContext | default browser context}).
*/
target(): Target {
throw new Error('Not implemented');
}
abstract target(): Target;
/**
* 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.
* @returns The first target found that matches the `predicate` function.
* This will look all open {@link BrowserContext | browser contexts}.
*
* @example
*
* An example of finding a target for a page opened via `window.open`:
* @example Finding a target for a page opened via `window.open`:
*
* ```ts
* 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
* browser contexts. Non-visible pages, such as `"background_page"`, will not be listed
* here. You can find them using {@link Target.page}.
* @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
* will not be listed here. You can find them using {@link Target.page}.
*/
async pages(): Promise<Page[]> {
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
* 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
* The format of {@link Browser.version} might change with future releases of
* browsers.
*/
version(): Promise<string> {
throw new Error('Not implemented');
}
abstract version(): Promise<string>;
/**
* 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}.
*/
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
* {@link Browser} object itself is considered to be disposed and cannot be
* used anymore.
* Closes this {@link Browser | browser} and all associated
* {@link Page | pages}.
*/
close(): Promise<void> {
throw new Error('Not implemented');
}
abstract close(): Promise<void>;
/**
* Disconnects Puppeteer from the browser, but leaves the browser process running.
* After calling `disconnect`, the {@link Browser} object is considered disposed and
* cannot be used anymore.
* Disconnects Puppeteer from this {@link Browser | browser}, but leaves the
* process running.
*/
disconnect(): void {
throw new Error('Not implemented');
}
/**
* Indicates that the browser is connected.
* Whether Puppeteer is connected to this {@link Browser | browser}.
*/
isConnected(): boolean {
throw new Error('Not implemented');
}
abstract isConnected(): boolean;
/** @internal */
[Symbol.dispose](): void {