From d088da31b27ff79dc2c03183cf9dc64672b906b2 Mon Sep 17 00:00:00 2001 From: jrandolf <101637635+jrandolf@users.noreply.github.com> Date: Mon, 18 Sep 2023 11:05:23 +0200 Subject: [PATCH] docs: improve Browser docs (#10925) --- docs/api/index.md | 4 +- docs/api/puppeteer.browser.browsercontexts.md | 6 +- docs/api/puppeteer.browser.close.md | 4 +- ...r.browser.createincognitobrowsercontext.md | 24 +- ...puppeteer.browser.defaultbrowsercontext.md | 8 +- docs/api/puppeteer.browser.disconnect.md | 2 +- docs/api/puppeteer.browser.isconnected.md | 4 +- docs/api/puppeteer.browser.md | 78 +++--- docs/api/puppeteer.browser.newpage.md | 4 +- docs/api/puppeteer.browser.pages.md | 6 +- docs/api/puppeteer.browser.process.md | 4 +- docs/api/puppeteer.browser.target.md | 4 +- docs/api/puppeteer.browser.targets.md | 6 +- docs/api/puppeteer.browser.useragent.md | 4 +- docs/api/puppeteer.browser.version.md | 14 +- docs/api/puppeteer.browser.waitfortarget.md | 16 +- docs/api/puppeteer.browser.wsendpoint.md | 16 +- docs/api/puppeteer.browsercontextoptions.md | 2 - docs/api/puppeteer.browserevent.md | 4 +- packages/puppeteer-core/src/api/Browser.ts | 241 ++++++++---------- 20 files changed, 219 insertions(+), 232 deletions(-) diff --git a/docs/api/index.md b/docs/api/index.md index 4a1e020e62b..4bbe55fc3a0 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -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) |

[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.

| | [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 CDPSession 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) | | diff --git a/docs/api/puppeteer.browser.browsercontexts.md b/docs/api/puppeteer.browser.browsercontexts.md index 1e81e41eb0f..1db6858fcdb 100644 --- a/docs/api/puppeteer.browser.browsercontexts.md +++ b/docs/api/puppeteer.browser.browsercontexts.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[]; } ``` diff --git a/docs/api/puppeteer.browser.close.md b/docs/api/puppeteer.browser.close.md index b7c30033e6d..5955b67162b 100644 --- a/docs/api/puppeteer.browser.close.md +++ b/docs/api/puppeteer.browser.close.md @@ -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; + abstract close(): Promise; } ``` diff --git a/docs/api/puppeteer.browser.createincognitobrowsercontext.md b/docs/api/puppeteer.browser.createincognitobrowsercontext.md index 5660dcf31cc..73870039f94 100644 --- a/docs/api/puppeteer.browser.createincognitobrowsercontext.md +++ b/docs/api/puppeteer.browser.createincognitobrowsercontext.md @@ -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; } @@ -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'); ``` diff --git a/docs/api/puppeteer.browser.defaultbrowsercontext.md b/docs/api/puppeteer.browser.defaultbrowsercontext.md index ce6262fb8f0..7070266fae1 100644 --- a/docs/api/puppeteer.browser.defaultbrowsercontext.md +++ b/docs/api/puppeteer.browser.defaultbrowsercontext.md @@ -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. diff --git a/docs/api/puppeteer.browser.disconnect.md b/docs/api/puppeteer.browser.disconnect.md index c102c10b094..b7611b72a23 100644 --- a/docs/api/puppeteer.browser.disconnect.md +++ b/docs/api/puppeteer.browser.disconnect.md @@ -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: diff --git a/docs/api/puppeteer.browser.isconnected.md b/docs/api/puppeteer.browser.isconnected.md index 190afde7aa7..d618a252d1f 100644 --- a/docs/api/puppeteer.browser.isconnected.md +++ b/docs/api/puppeteer.browser.isconnected.md @@ -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; } ``` diff --git a/docs/api/puppeteer.browser.md b/docs/api/puppeteer.browser.md index e92888c54e5..21111eee96a 100644 --- a/docs/api/puppeteer.browser.md +++ b/docs/api/puppeteer.browser.md @@ -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 +export declare abstract class Browser extends EventEmitter ``` **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 disconnect, 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 null 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) | |

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).

| +| [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](./puppeteer.browsercontext.md).

This won't share cookies/cache with other [browser contexts](./puppeteer.browsercontext.md).

| +| [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) | |

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).

| +| [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) | |

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).

| +| [userAgent()](./puppeteer.browser.useragent.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).

| +| [version()](./puppeteer.browser.version.md) | |

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.

| +| [waitForTarget(predicate, options)](./puppeteer.browser.waitfortarget.md) | |

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).

| +| [wsEndpoint()](./puppeteer.browser.wsendpoint.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.

| diff --git a/docs/api/puppeteer.browser.newpage.md b/docs/api/puppeteer.browser.newpage.md index 4f659e3f851..9be04d72dae 100644 --- a/docs/api/puppeteer.browser.newpage.md +++ b/docs/api/puppeteer.browser.newpage.md @@ -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; + abstract newPage(): Promise; } ``` diff --git a/docs/api/puppeteer.browser.pages.md b/docs/api/puppeteer.browser.pages.md index 3b136c48955..98cf276e4ab 100644 --- a/docs/api/puppeteer.browser.pages.md +++ b/docs/api/puppeteer.browser.pages.md @@ -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). diff --git a/docs/api/puppeteer.browser.process.md b/docs/api/puppeteer.browser.process.md index 27c794c7b45..135de89e5fc 100644 --- a/docs/api/puppeteer.browser.process.md +++ b/docs/api/puppeteer.browser.process.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). diff --git a/docs/api/puppeteer.browser.target.md b/docs/api/puppeteer.browser.target.md index 63d29b520b5..8adc46c9957 100644 --- a/docs/api/puppeteer.browser.target.md +++ b/docs/api/puppeteer.browser.target.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; } ``` diff --git a/docs/api/puppeteer.browser.targets.md b/docs/api/puppeteer.browser.targets.md index 2af3229cd86..f3748f794fb 100644 --- a/docs/api/puppeteer.browser.targets.md +++ b/docs/api/puppeteer.browser.targets.md @@ -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[]; } ``` diff --git a/docs/api/puppeteer.browser.useragent.md b/docs/api/puppeteer.browser.useragent.md index d34f16d457f..2e2cb214a92 100644 --- a/docs/api/puppeteer.browser.useragent.md +++ b/docs/api/puppeteer.browser.useragent.md @@ -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: diff --git a/docs/api/puppeteer.browser.version.md b/docs/api/puppeteer.browser.version.md index ed6b027b216..c4e6404f89c 100644 --- a/docs/api/puppeteer.browser.version.md +++ b/docs/api/puppeteer.browser.version.md @@ -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; + abstract version(): Promise; } ``` **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. diff --git a/docs/api/puppeteer.browser.waitfortarget.md b/docs/api/puppeteer.browser.waitfortarget.md index 4e7794259a9..d83d47ea9b9 100644 --- a/docs/api/puppeteer.browser.waitfortarget.md +++ b/docs/api/puppeteer.browser.waitfortarget.md @@ -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/')); diff --git a/docs/api/puppeteer.browser.wsendpoint.md b/docs/api/puppeteer.browser.wsendpoint.md index 4972912dbed..496719f5279 100644 --- a/docs/api/puppeteer.browser.wsendpoint.md +++ b/docs/api/puppeteer.browser.wsendpoint.md @@ -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/`. - -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/`. diff --git a/docs/api/puppeteer.browsercontextoptions.md b/docs/api/puppeteer.browsercontextoptions.md index 27754f3f0a6..7bbd9bacf4a 100644 --- a/docs/api/puppeteer.browsercontextoptions.md +++ b/docs/api/puppeteer.browsercontextoptions.md @@ -4,8 +4,6 @@ sidebar_label: BrowserContextOptions # BrowserContextOptions interface -BrowserContext options. - #### Signature: ```typescript diff --git a/docs/api/puppeteer.browserevent.md b/docs/api/puppeteer.browserevent.md index 8f4d7c55e0f..4472c3b53a9 100644 --- a/docs/api/puppeteer.browserevent.md +++ b/docs/api/puppeteer.browserevent.md @@ -16,7 +16,7 @@ export declare const enum BrowserEvent | Member | Value | Description | | --------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Disconnected | "disconnected" |

Emitted when Puppeteer gets disconnected from the browser instance. This might happen because of one of the following:

- browser is closed or crashed

- The [browser.disconnect](./puppeteer.browser.disconnect.md) method was called.

| -| TargetChanged | "targetchanged" | Emitted when the url of a target changes. Contains a [Target](./puppeteer.target.md) instance. | +| Disconnected | "disconnected" |

Emitted when Puppeteer gets disconnected from the browser instance. This might happen because either:

- The browser closes/crashes or - [Browser.disconnect()](./puppeteer.browser.disconnect.md) was called.

| +| TargetChanged | "targetchanged" | Emitted when the URL of a target changes. Contains a [Target](./puppeteer.target.md) instance. | | TargetCreated | "targetcreated" |

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)

Contains a [Target](./puppeteer.target.md) instance.

| | TargetDestroyed | "targetdestroyed" | Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance. | diff --git a/packages/puppeteer-core/src/api/Browser.ts b/packages/puppeteer-core/src/api/Browser.ts index 27b4c5393fd..7c1ca47db7b 100644 --- a/packages/puppeteer-core/src/api/Browser.ts +++ b/packages/puppeteer-core/src/api/Browser.ts @@ -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 { } /** - * 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 { +export abstract class Browser extends EventEmitter { /** * @internal */ @@ -271,7 +259,10 @@ export class Browser extends EventEmitter { } /** - * 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 { } /** - * 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; - createIncognitoBrowserContext(): Promise { - 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 { } /** - * 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/`. - * - * 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/`. */ - 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 { - throw new Error('Not implemented'); - } + abstract newPage(): Promise; /** * @internal @@ -371,29 +354,27 @@ export class Browser extends EventEmitter { } /** - * 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 { } /** - * 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 { const contextPages = await Promise.all( @@ -455,23 +437,22 @@ export class Browser extends EventEmitter { } /** - * 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 { - throw new Error('Not implemented'); - } + abstract version(): Promise; /** - * 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 { @@ -479,29 +460,23 @@ export class Browser extends EventEmitter { } /** - * 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 { - throw new Error('Not implemented'); - } + abstract close(): Promise; /** - * 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 {