mirror of
https://github.com/puppeteer/puppeteer
synced 2024-06-14 14:02:48 +00:00
docs: improve Browser docs (#10925)
This commit is contained in:
jrandolf
GitHub
parent
1bac89e284
commit
d088da31b2
@ -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) | |
|
||||
|
||||
@ -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[];
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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>;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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<[BrowserContext](./puppeteer.browsercontext.md)>
|
||||
## 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');
|
||||
```
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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)<[BrowserEvents](./puppeteer.browserevents.md)>
|
||||
|
||||
## 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). |
|
||||
| Method | Modifiers | Description |
|
||||
| ---------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [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>"HeadlessChrome/61.0.3153.0"</code>. For non-headless or new-headless, this is similar to <code>"Chrome/61.0.3153.0"</code>. For Firefox, it is similar to <code>"Firefox/116.0a1"</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> |
|
||||
|
||||
@ -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>;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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<[Page](./puppeteer.page.md)\[\]>
|
||||
|
||||
## 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,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).
|
||||
|
||||
@ -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;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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[];
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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<string>
|
||||
|
||||
## 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.
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -19,20 +21,18 @@ class Browser {
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ---------------------------------------------------------------------------- | -------------------------------------- |
|
||||
| predicate | (x: [Target](./puppeteer.target.md)) => boolean \| Promise<boolean> | A function to be run for every target. |
|
||||
| options | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | _(Optional)_ |
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ---------------------------------------------------------------------------- | ------------ |
|
||||
| predicate | (x: [Target](./puppeteer.target.md)) => boolean \| Promise<boolean> | |
|
||||
| options | [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | _(Optional)_ |
|
||||
|
||||
**Returns:**
|
||||
|
||||
Promise<[Target](./puppeteer.target.md)>
|
||||
|
||||
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/'));
|
||||
|
||||
@ -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>`.
|
||||
|
||||
@ -4,8 +4,6 @@ sidebar_label: BrowserContextOptions
|
||||
|
||||
# BrowserContextOptions interface
|
||||
|
||||
BrowserContext options.
|
||||
|
||||
#### Signature:
|
||||
|
||||
```typescript
|
||||
|
||||
@ -16,7 +16,7 @@ export declare const enum BrowserEvent
|
||||
|
||||
| Member | Value | Description |
|
||||
| --------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Disconnected | <code>"disconnected"</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>"targetchanged"</code> | Emitted when the url of a target changes. Contains a [Target](./puppeteer.target.md) instance. |
|
||||
| Disconnected | <code>"disconnected"</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>"targetchanged"</code> | Emitted when the URL of a target changes. Contains a [Target](./puppeteer.target.md) instance. |
|
||||
| TargetCreated | <code>"targetcreated"</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>"targetdestroyed"</code> | Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance. |
|
||||
|
||||
@ -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,51 +191,45 @@ 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();
|
||||
* })();
|
||||
* 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();
|
||||
* // 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();
|
||||
* ```
|
||||
*
|
||||
* @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,44 +277,43 @@ 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 () => {
|
||||
* 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');
|
||||
* ```
|
||||
*/
|
||||
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 {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user