From 2292078969fa46a27d5759989cd44a4d48beb310 Mon Sep 17 00:00:00 2001 From: jrandolf <101637635+jrandolf@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:11:55 +0200 Subject: [PATCH] feat: implement `BrowserContext.closed` (#10928) --- docs/api/index.md | 72 ++++----- docs/api/puppeteer.browsercontext.browser.md | 4 +- ...browsercontext.clearpermissionoverrides.md | 4 +- docs/api/puppeteer.browsercontext.close.md | 6 +- .../puppeteer.browsercontext.isincognito.md | 10 +- docs/api/puppeteer.browsercontext.md | 47 +++--- docs/api/puppeteer.browsercontext.newpage.md | 4 +- ...teer.browsercontext.overridepermissions.md | 4 + docs/api/puppeteer.browsercontext.pages.md | 8 +- docs/api/puppeteer.browsercontext.targets.md | 2 +- .../puppeteer.browsercontext.waitfortarget.md | 18 +-- .../puppeteer-core/src/api/BrowserContext.ts | 139 ++++++++++-------- 12 files changed, 168 insertions(+), 150 deletions(-) diff --git a/docs/api/index.md b/docs/api/index.md index 24b13550..2fd07171 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -6,42 +6,42 @@ sidebar_label: API ## Classes -| 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) |

[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) | | -| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | -| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page. | -| [CSSCoverage](./puppeteer.csscoverage.md) | | -| [CustomError](./puppeteer.customerror.md) | | -| [DeviceRequestPrompt](./puppeteer.devicerequestprompt.md) | Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth. | -| [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md) | Device in a request prompt. | -| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | -| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | -| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | -| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | -| [Frame](./puppeteer.frame.md) |

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

| -| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | -| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | -| [JSCoverage](./puppeteer.jscoverage.md) | | -| [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| -| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | -| [Locator](./puppeteer.locator.md) | Locators describe a strategy of locating objects and performing an action on them. If the action fails because the object is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically. | -| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | -| [Page](./puppeteer.page.md) |

Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in the browser.

:::note

One Browser instance might have multiple Page instances.

:::

| -| [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | -| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | -| [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| -| [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| -| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | -| [Target](./puppeteer.target.md) | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker. | -| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | -| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | -| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | -| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_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) |

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

[BrowserContext](./puppeteer.browsercontext.md) represents individual sessions within a [browser](./puppeteer.browser.md).

When a [browser](./puppeteer.browser.md) is launched, it has a single [browser context](./puppeteer.browsercontext.md) by default. Others can be created using [Browser.createIncognitoBrowserContext()](./puppeteer.browser.createincognitobrowsercontext.md).

[BrowserContext](./puppeteer.browsercontext.md) [emits](./puppeteer.eventemitter.md) various events which are documented in the [BrowserContextEvent](./puppeteer.browsercontextevent.md) enum.

If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g. using window.open, the popup will belong to the parent [page's browser context](./puppeteer.page.browsercontext.md).

| +| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | +| [Connection](./puppeteer.connection.md) | | +| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | +| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page. | +| [CSSCoverage](./puppeteer.csscoverage.md) | | +| [CustomError](./puppeteer.customerror.md) | | +| [DeviceRequestPrompt](./puppeteer.devicerequestprompt.md) | Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth. | +| [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md) | Device in a request prompt. | +| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | +| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | +| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | +| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | +| [Frame](./puppeteer.frame.md) |

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

| +| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | +| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | +| [JSCoverage](./puppeteer.jscoverage.md) | | +| [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| +| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | +| [Locator](./puppeteer.locator.md) | Locators describe a strategy of locating objects and performing an action on them. If the action fails because the object is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically. | +| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | +| [Page](./puppeteer.page.md) |

Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in the browser.

:::note

One Browser instance might have multiple Page instances.

:::

| +| [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | +| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | +| [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| +| [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| +| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | +| [Target](./puppeteer.target.md) | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker. | +| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | +| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | +| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | +| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Enumerations diff --git a/docs/api/puppeteer.browsercontext.browser.md b/docs/api/puppeteer.browsercontext.browser.md index 57d3f795..77f54aaa 100644 --- a/docs/api/puppeteer.browsercontext.browser.md +++ b/docs/api/puppeteer.browsercontext.browser.md @@ -4,13 +4,13 @@ sidebar_label: BrowserContext.browser # BrowserContext.browser() method -The browser this browser context belongs to. +Gets the [browser](./puppeteer.browser.md) associated with this [browser context](./puppeteer.browsercontext.md). #### Signature: ```typescript class BrowserContext { - browser(): Browser; + abstract browser(): Browser; } ``` diff --git a/docs/api/puppeteer.browsercontext.clearpermissionoverrides.md b/docs/api/puppeteer.browsercontext.clearpermissionoverrides.md index 9be59d2d..d86657c7 100644 --- a/docs/api/puppeteer.browsercontext.clearpermissionoverrides.md +++ b/docs/api/puppeteer.browsercontext.clearpermissionoverrides.md @@ -4,7 +4,7 @@ sidebar_label: BrowserContext.clearPermissionOverrides # BrowserContext.clearPermissionOverrides() method -Clears all permission overrides for the browser context. +Clears all permission overrides for this [browser context](./puppeteer.browsercontext.md). #### Signature: @@ -20,6 +20,8 @@ Promise<void> ## Example +Clearing overridden permissions in the [default browser context](./puppeteer.browser.defaultbrowsercontext.md): + ```ts const context = browser.defaultBrowserContext(); context.overridePermissions('https://example.com', ['clipboard-read']); diff --git a/docs/api/puppeteer.browsercontext.close.md b/docs/api/puppeteer.browsercontext.close.md index a96cc587..ad416cd0 100644 --- a/docs/api/puppeteer.browsercontext.close.md +++ b/docs/api/puppeteer.browsercontext.close.md @@ -4,13 +4,13 @@ sidebar_label: BrowserContext.close # BrowserContext.close() method -Closes the browser context. All the targets that belong to the browser context will be closed. +Closes this [browser context](./puppeteer.browsercontext.md) and all associated [pages](./puppeteer.page.md). #### Signature: ```typescript class BrowserContext { - close(): Promise; + abstract close(): Promise; } ``` @@ -20,4 +20,4 @@ Promise<void> ## Remarks -Only incognito browser contexts can be closed. +The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) cannot be closed. diff --git a/docs/api/puppeteer.browsercontext.isincognito.md b/docs/api/puppeteer.browsercontext.isincognito.md index 38b7f39d..a8d6292a 100644 --- a/docs/api/puppeteer.browsercontext.isincognito.md +++ b/docs/api/puppeteer.browsercontext.isincognito.md @@ -4,20 +4,18 @@ sidebar_label: BrowserContext.isIncognito # BrowserContext.isIncognito() method -Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context. +Whether this [browser context](./puppeteer.browsercontext.md) is incognito. + +The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context. #### Signature: ```typescript class BrowserContext { - isIncognito(): boolean; + abstract isIncognito(): boolean; } ``` **Returns:** boolean - -## Remarks - -The default browser context cannot be closed. diff --git a/docs/api/puppeteer.browsercontext.md b/docs/api/puppeteer.browsercontext.md index 9f9dd4bc..87c6540f 100644 --- a/docs/api/puppeteer.browsercontext.md +++ b/docs/api/puppeteer.browsercontext.md @@ -4,28 +4,30 @@ sidebar_label: BrowserContext # BrowserContext class -BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. +[BrowserContext](./puppeteer.browsercontext.md) represents individual sessions within a [browser](./puppeteer.browser.md). + +When a [browser](./puppeteer.browser.md) is launched, it has a single [browser context](./puppeteer.browsercontext.md) by default. Others can be created using [Browser.createIncognitoBrowserContext()](./puppeteer.browser.createincognitobrowsercontext.md). + +[BrowserContext](./puppeteer.browsercontext.md) [emits](./puppeteer.eventemitter.md) various events which are documented in the [BrowserContextEvent](./puppeteer.browsercontextevent.md) enum. + +If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g. using `window.open`, the popup will belong to the parent [page's browser context](./puppeteer.page.browsercontext.md). #### Signature: ```typescript -export declare class BrowserContext extends EventEmitter +export declare abstract class BrowserContext extends EventEmitter ``` **Extends:** [EventEmitter](./puppeteer.eventemitter.md)<[BrowserContextEvents](./puppeteer.browsercontextevents.md)> ## Remarks -The Browser class extends from Puppeteer's [EventEmitter](./puppeteer.eventemitter.md) class and will emit various events which are documented in the [BrowserContextEvents](./puppeteer.browsercontextevents.md) enum. - -If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser context. - -Puppeteer allows creation of "incognito" browser contexts with [Browser.createIncognitoBrowserContext](./puppeteer.browser.createincognitobrowsercontext.md) method. "Incognito" browser contexts don't write any browsing data to disk. - The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BrowserContext` class. ## Example +Creating an incognito [browser context](./puppeteer.browsercontext.md): + ```ts // Create a new incognito browser context const context = await browser.createIncognitoBrowserContext(); @@ -39,20 +41,21 @@ await context.close(); ## Properties -| Property | Modifiers | Type | Description | -| -------- | --------------------- | ------------------- | ----------- | -| id | readonly | string \| undefined | | +| Property | Modifiers | Type | Description | +| -------- | --------------------- | ------------------- | ------------------------------------------------------------------------ | +| closed | readonly | boolean | Whether this [browser context](./puppeteer.browsercontext.md) is closed. | +| id | readonly | string \| undefined | Identifier for this [browser context](./puppeteer.browsercontext.md). | ## Methods -| Method | Modifiers | Description | -| --------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | -| [browser()](./puppeteer.browsercontext.browser.md) | | The browser this browser context belongs to. | -| [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) | | Clears all permission overrides for the browser context. | -| [close()](./puppeteer.browsercontext.close.md) | | Closes the browser context. All the targets that belong to the browser context will be closed. | -| [isIncognito()](./puppeteer.browsercontext.isincognito.md) | | Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context. | -| [newPage()](./puppeteer.browsercontext.newpage.md) | | Creates a new page in the browser context. | -| [overridePermissions(origin, permissions)](./puppeteer.browsercontext.overridepermissions.md) | | | -| [pages()](./puppeteer.browsercontext.pages.md) | | An array of all pages inside the browser context. | -| [targets()](./puppeteer.browsercontext.targets.md) | | An array of all active targets inside the browser context. | -| [waitForTarget(predicate, options)](./puppeteer.browsercontext.waitfortarget.md) | | This searches for a target in this specific browser context. | +| Method | Modifiers | Description | +| --------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [browser()](./puppeteer.browsercontext.browser.md) | | Gets the [browser](./puppeteer.browser.md) associated with this [browser context](./puppeteer.browsercontext.md). | +| [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) | | Clears all permission overrides for this [browser context](./puppeteer.browsercontext.md). | +| [close()](./puppeteer.browsercontext.close.md) | | Closes this [browser context](./puppeteer.browsercontext.md) and all associated [pages](./puppeteer.page.md). | +| [isIncognito()](./puppeteer.browsercontext.isincognito.md) | |

Whether this [browser context](./puppeteer.browsercontext.md) is incognito.

The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context.

| +| [newPage()](./puppeteer.browsercontext.newpage.md) | | Creates a new [page](./puppeteer.page.md) in this [browser context](./puppeteer.browsercontext.md). | +| [overridePermissions(origin, permissions)](./puppeteer.browsercontext.overridepermissions.md) | | Grants this [browser context](./puppeteer.browsercontext.md) the given permissions within the given origin. | +| [pages()](./puppeteer.browsercontext.pages.md) | | Gets a list of all open [pages](./puppeteer.page.md) inside this [browser context](./puppeteer.browsercontext.md). | +| [targets()](./puppeteer.browsercontext.targets.md) | | Gets all active [targets](./puppeteer.target.md) inside this [browser context](./puppeteer.browsercontext.md). | +| [waitForTarget(predicate, options)](./puppeteer.browsercontext.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).

| diff --git a/docs/api/puppeteer.browsercontext.newpage.md b/docs/api/puppeteer.browsercontext.newpage.md index 83c1da98..351bd977 100644 --- a/docs/api/puppeteer.browsercontext.newpage.md +++ b/docs/api/puppeteer.browsercontext.newpage.md @@ -4,13 +4,13 @@ sidebar_label: BrowserContext.newPage # BrowserContext.newPage() method -Creates a new page in the browser context. +Creates a new [page](./puppeteer.page.md) in this [browser context](./puppeteer.browsercontext.md). #### Signature: ```typescript class BrowserContext { - newPage(): Promise; + abstract newPage(): Promise; } ``` diff --git a/docs/api/puppeteer.browsercontext.overridepermissions.md b/docs/api/puppeteer.browsercontext.overridepermissions.md index caf2a47b..d0c3ff9e 100644 --- a/docs/api/puppeteer.browsercontext.overridepermissions.md +++ b/docs/api/puppeteer.browsercontext.overridepermissions.md @@ -4,6 +4,8 @@ sidebar_label: BrowserContext.overridePermissions # BrowserContext.overridePermissions() method +Grants this [browser context](./puppeteer.browsercontext.md) the given `permissions` within the given `origin`. + #### Signature: ```typescript @@ -25,6 +27,8 @@ Promise<void> ## Example +Overriding permissions in the [default browser context](./puppeteer.browser.defaultbrowsercontext.md): + ```ts const context = browser.defaultBrowserContext(); await context.overridePermissions('https://html5demos.com', ['geolocation']); diff --git a/docs/api/puppeteer.browsercontext.pages.md b/docs/api/puppeteer.browsercontext.pages.md index 604050d7..747b6b9b 100644 --- a/docs/api/puppeteer.browsercontext.pages.md +++ b/docs/api/puppeteer.browsercontext.pages.md @@ -4,13 +4,13 @@ sidebar_label: BrowserContext.pages # BrowserContext.pages() method -An array of all pages inside the browser context. +Gets a list of all open [pages](./puppeteer.page.md) inside this [browser context](./puppeteer.browsercontext.md). #### Signature: ```typescript class BrowserContext { - pages(): Promise; + abstract pages(): Promise; } ``` @@ -18,4 +18,6 @@ class BrowserContext { Promise<[Page](./puppeteer.page.md)\[\]> -Promise which resolves to an array of all open pages. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [the target page](./puppeteer.target.page.md). +## Remarks + +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.browsercontext.targets.md b/docs/api/puppeteer.browsercontext.targets.md index 0c3182eb..a5f897dc 100644 --- a/docs/api/puppeteer.browsercontext.targets.md +++ b/docs/api/puppeteer.browsercontext.targets.md @@ -4,7 +4,7 @@ sidebar_label: BrowserContext.targets # BrowserContext.targets() method -An array of all active targets inside the browser context. +Gets all active [targets](./puppeteer.target.md) inside this [browser context](./puppeteer.browsercontext.md). #### Signature: diff --git a/docs/api/puppeteer.browsercontext.waitfortarget.md b/docs/api/puppeteer.browsercontext.waitfortarget.md index dd9c3d0e..690874e8 100644 --- a/docs/api/puppeteer.browsercontext.waitfortarget.md +++ b/docs/api/puppeteer.browsercontext.waitfortarget.md @@ -4,13 +4,15 @@ sidebar_label: BrowserContext.waitForTarget # BrowserContext.waitForTarget() method -This searches for a target in this specific browser context. +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: ```typescript class BrowserContext { - waitForTarget( + abstract waitForTarget( predicate: (x: Target) => boolean | Promise, options?: { timeout?: number; @@ -21,20 +23,18 @@ class BrowserContext { ## Parameters -| Parameter | Type | Description | -| --------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| predicate | (x: [Target](./puppeteer.target.md)) => boolean \| Promise<boolean> | A function to be run for every target | -| options | { timeout?: number; } | _(Optional)_ An object of options. Accepts a timeout, which is the maximum wait time in milliseconds. Pass 0 to disable the timeout. Defaults to 30 seconds. | +| Parameter | Type | Description | +| --------- | ---------------------------------------------------------------------------- | ------------ | +| predicate | (x: [Target](./puppeteer.target.md)) => boolean \| Promise<boolean> | | +| options | { timeout?: number; } | _(Optional)_ | **Returns:** Promise<[Target](./puppeteer.target.md)> -Promise which resolves to 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/packages/puppeteer-core/src/api/BrowserContext.ts b/packages/puppeteer-core/src/api/BrowserContext.ts index bf22e598..4d27f8e9 100644 --- a/packages/puppeteer-core/src/api/BrowserContext.ts +++ b/packages/puppeteer-core/src/api/BrowserContext.ts @@ -15,6 +15,7 @@ */ import {EventEmitter, type EventType} from '../common/EventEmitter.js'; +import {debugError} from '../common/util.js'; import type {Browser, Permission} from './Browser.js'; import {type Page} from './Page.js'; @@ -63,25 +64,21 @@ export interface BrowserContextEvents extends Record { } /** - * 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 {@link Browser.newPage | Browser.newPage} creates a page - * in the default browser context. + * {@link BrowserContext} represents individual sessions within a + * {@link Browser | browser}. * - * @remarks + * When a {@link Browser | browser} is launched, it has a single + * {@link BrowserContext | browser context} by default. Others can be created + * using {@link Browser.createIncognitoBrowserContext}. * - * The Browser class extends from Puppeteer's {@link EventEmitter} class and - * will emit various events which are documented in the - * {@link BrowserContextEvents} enum. + * {@link BrowserContext} {@link EventEmitter | emits} various events which are + * documented in the {@link BrowserContextEvent} enum. * - * If a page opens another page, e.g. with a `window.open` call, the popup will - * belong to the parent page's browser context. + * If a {@link Page | page} opens another {@link Page | page}, e.g. using + * `window.open`, the popup will belong to the parent {@link Page.browserContext + * | page's browser context}. * - * Puppeteer allows creation of "incognito" browser contexts with - * {@link Browser.createIncognitoBrowserContext | Browser.createIncognitoBrowserContext} - * method. "Incognito" browser contexts don't write any browsing data to disk. - * - * @example + * @example Creating an incognito {@link BrowserContext | browser context}: * * ```ts * // Create a new incognito browser context @@ -97,7 +94,7 @@ export interface BrowserContextEvents extends Record { * @public */ -export class BrowserContext extends EventEmitter { +export abstract class BrowserContext extends EventEmitter { /** * @internal */ @@ -106,17 +103,20 @@ export class BrowserContext extends EventEmitter { } /** - * An array of all active targets inside the browser context. + * Gets all active {@link Target | targets} inside this + * {@link BrowserContext | browser context}. */ targets(): Target[] { throw new Error('Not implemented'); } /** - * This searches for a target in this specific browser context. + * Waits until a {@link Target | target} matching the given `predicate` + * appears and returns it. * - * @example - * An example of finding a target for a page opened via `window.open`: + * This will look all open {@link BrowserContext | browser contexts}. + * + * @example Finding a target for a page opened via `window.open`: * * ```ts * await page.evaluate(() => window.open('https://www.example.com/')); @@ -124,46 +124,35 @@ export class BrowserContext extends EventEmitter { * target => target.url() === 'https://www.example.com/' * ); * ``` - * - * @param predicate - A function to be run for every target - * @param options - An object of options. Accepts a timeout, - * which is the maximum wait time in milliseconds. - * Pass `0` to disable the timeout. Defaults to 30 seconds. - * @returns Promise which resolves to the first target found - * that matches the `predicate` function. */ - waitForTarget( + abstract waitForTarget( predicate: (x: Target) => boolean | Promise, options?: {timeout?: number} ): Promise; - waitForTarget(): Promise { - throw new Error('Not implemented'); - } /** - * An array of all pages inside the browser context. + * Gets a list of all open {@link Page | pages} inside this + * {@link BrowserContext | browser context}. * - * @returns Promise which resolves to an array of all open pages. - * Non visible pages, such as `"background_page"`, will not be listed here. - * You can find them using {@link Target.page | the 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}. */ - pages(): Promise { - throw new Error('Not implemented'); - } + abstract pages(): Promise; /** - * Returns whether BrowserContext is incognito. - * The default browser context is the only non-incognito browser context. + * Whether this {@link BrowserContext | browser context} is incognito. * - * @remarks - * The default browser context cannot be closed. + * The {@link Browser.defaultBrowserContext | default browser context} is the + * only non-incognito browser context. */ - isIncognito(): boolean { - throw new Error('Not implemented'); - } + abstract isIncognito(): boolean; /** - * @example + * Grants this {@link BrowserContext | browser context} the given + * `permissions` within the given `origin`. + * + * @example Overriding permissions in the + * {@link Browser.defaultBrowserContext | default browser context}: * * ```ts * const context = browser.defaultBrowserContext(); @@ -172,9 +161,10 @@ export class BrowserContext extends EventEmitter { * ]); * ``` * - * @param origin - The origin to grant permissions to, e.g. "https://example.com". - * @param permissions - An array of permissions to grant. - * All permissions that are not listed here will be automatically denied. + * @param origin - The origin to grant permissions to, e.g. + * "https://example.com". + * @param permissions - An array of permissions to grant. All permissions that + * are not listed here will be automatically denied. */ overridePermissions(origin: string, permissions: Permission[]): Promise; overridePermissions(): Promise { @@ -182,9 +172,11 @@ export class BrowserContext extends EventEmitter { } /** - * Clears all permission overrides for the browser context. + * Clears all permission overrides for this + * {@link BrowserContext | browser context}. * - * @example + * @example Clearing overridden permissions in the + * {@link Browser.defaultBrowserContext | default browser context}: * * ```ts * const context = browser.defaultBrowserContext(); @@ -198,31 +190,48 @@ export class BrowserContext extends EventEmitter { } /** - * Creates a new page in the browser context. + * Creates a new {@link Page | page} in this + * {@link BrowserContext | browser context}. */ - newPage(): Promise { - throw new Error('Not implemented'); - } + abstract newPage(): Promise; /** - * The browser this browser context belongs to. + * Gets the {@link Browser | browser} associated with this + * {@link BrowserContext | browser context}. */ - browser(): Browser { - throw new Error('Not implemented'); - } + abstract browser(): Browser; /** - * Closes the browser context. All the targets that belong to the browser context - * will be closed. + * Closes this {@link BrowserContext | browser context} and all associated + * {@link Page | pages}. * - * @remarks - * Only incognito browser contexts can be closed. + * @remarks The + * {@link Browser.defaultBrowserContext | default browser context} cannot be + * closed. */ - close(): Promise { - throw new Error('Not implemented'); + abstract close(): Promise; + + /** + * Whether this {@link BrowserContext | browser context} is closed. + */ + get closed(): boolean { + return !this.browser().browserContexts().includes(this); } + /** + * Identifier for this {@link BrowserContext | browser context}. + */ get id(): string | undefined { return undefined; } + + /** @internal */ + [Symbol.dispose](): void { + return void this.close().catch(debugError); + } + + /** @internal */ + [Symbol.asyncDispose](): Promise { + return this.close(); + } }