github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: implement BrowserContext.closed (#10928)

Browse Source
This commit is contained in:
jrandolf 2023-09-18 20:11:55 +02:00 committed by GitHub
parent fd72101f7b
commit 2292078969
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 168 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/api/index.md
View File

@ -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) | <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) | |
| [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 <code>dialog</code> 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) | <p>Represents a DOM frame.</p><p>To understand frames, you can think of frames as <code>&lt;iframe&gt;</code> 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.</p> |
| [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) | <p>Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).</p><p>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.</p><p>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.</p> |
| [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) | <p>Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in the browser.</p><p>:::note</p><p>One Browser instance might have multiple Page instances.</p><p>:::</p> |
| [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) | <p>The main Puppeteer class.</p><p>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 <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p> |
| [PuppeteerNode](./puppeteer.puppeteernode.md) | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p> |
| [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) | <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) | <p>[BrowserContext](./puppeteer.browsercontext.md) represents individual sessions within a [browser](./puppeteer.browser.md).</p><p>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).</p><p>[BrowserContext](./puppeteer.browsercontext.md) [emits](./puppeteer.eventemitter.md) various events which are documented in the [BrowserContextEvent](./puppeteer.browsercontextevent.md) enum.</p><p>If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g. using <code>window.open</code>, the popup will belong to the parent [page's browser context](./puppeteer.page.browsercontext.md).</p> |
| [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> 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 <code>dialog</code> 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) | <p>Represents a DOM frame.</p><p>To understand frames, you can think of frames as <code>&lt;iframe&gt;</code> 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.</p> |
| [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) | <p>Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).</p><p>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.</p><p>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.</p> |
| [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) | <p>Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in the browser.</p><p>:::note</p><p>One Browser instance might have multiple Page instances.</p><p>:::</p> |
| [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) | <p>The main Puppeteer class.</p><p>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 <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p> |
| [PuppeteerNode](./puppeteer.puppeteernode.md) | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p> |
| [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

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

@ -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;
}
```

4
docs/api/puppeteer.browsercontext.clearpermissionoverrides.md
View File

@ -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&lt;void&gt;
## 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']);

6
docs/api/puppeteer.browsercontext.close.md
View File

@ -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<void>;
abstract close(): Promise<void>;
}
```
@ -20,4 +20,4 @@ Promise&lt;void&gt;
## Remarks
Only incognito browser contexts can be closed.
The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) cannot be closed.

10
docs/api/puppeteer.browsercontext.isincognito.md
View File

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

47
docs/api/puppeteer.browsercontext.md
View File

@ -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<BrowserContextEvents>
export declare abstract class BrowserContext extends EventEmitter<BrowserContextEvents>
```
**Extends:** [EventEmitter](./puppeteer.eventemitter.md)&lt;[BrowserContextEvents](./puppeteer.browsercontextevents.md)&gt;
## Remarks
The Browser class extends from Puppeteer's [EventEmitter](./puppeteer.eventemitter.md) class and will emit various events which are documented in the [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 | <code>readonly</code> | string \| undefined | |
| Property | Modifiers | Type | Description |
| -------- | --------------------- | ------------------- | ------------------------------------------------------------------------ |
| closed | <code>readonly</code> | boolean | Whether this [browser context](./puppeteer.browsercontext.md) is closed. |
| id | <code>readonly</code> | 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) | | <p>Whether this [browser context](./puppeteer.browsercontext.md) is incognito.</p><p>The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context.</p> |
| [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 <code>permissions</code> within the given <code>origin</code>. |
| [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) | | <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> |

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

@ -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<Page>;
abstract newPage(): Promise<Page>;
}
```

4
docs/api/puppeteer.browsercontext.overridepermissions.md
View File

@ -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&lt;void&gt;
## Example
Overriding permissions in the [default browser context](./puppeteer.browser.defaultbrowsercontext.md):
```ts
const context = browser.defaultBrowserContext();
await context.overridePermissions('https://html5demos.com', ['geolocation']);

8
docs/api/puppeteer.browsercontext.pages.md
View File

@ -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<Page[]>;
abstract pages(): Promise<Page[]>;
}
```
@ -18,4 +18,6 @@ class BrowserContext {
Promise&lt;[Page](./puppeteer.page.md)\[\]&gt;
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).

2
docs/api/puppeteer.browsercontext.targets.md
View File

@ -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:

18
docs/api/puppeteer.browsercontext.waitfortarget.md
View File

@ -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<boolean>,
options?: {
timeout?: number;
@ -21,20 +23,18 @@ class BrowserContext {
## Parameters
| Parameter | Type | Description |
| --------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| predicate | (x: [Target](./puppeteer.target.md)) =&gt; boolean \| Promise&lt;boolean&gt; | 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 <code>0</code> to disable the timeout. Defaults to 30 seconds. |
| Parameter | Type | Description |
| --------- | ---------------------------------------------------------------------------- | ------------ |
| predicate | (x: [Target](./puppeteer.target.md)) =&gt; boolean \| Promise&lt;boolean&gt; | |
| options | { timeout?: number; } | _(Optional)_ |
**Returns:**
Promise&lt;[Target](./puppeteer.target.md)&gt;
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/'));

139
packages/puppeteer-core/src/api/BrowserContext.ts
View File

@ -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<EventType, unknown> {
}
/**
* 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<EventType, unknown> {
* @public
*/
export class BrowserContext extends EventEmitter<BrowserContextEvents> {
export abstract class BrowserContext extends EventEmitter<BrowserContextEvents> {
/**
* @internal
*/
@ -106,17 +103,20 @@ export class BrowserContext extends EventEmitter<BrowserContextEvents> {
}
/**
* 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<BrowserContextEvents> {
* 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<boolean>,
options?: {timeout?: number}
): Promise<Target>;
waitForTarget(): Promise<Target> {
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<Page[]> {
throw new Error('Not implemented');
}
abstract pages(): Promise<Page[]>;
/**
* 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<BrowserContextEvents> {
* ]);
* ```
*
* @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<void>;
overridePermissions(): Promise<void> {
@ -182,9 +172,11 @@ export class BrowserContext extends EventEmitter<BrowserContextEvents> {
}
/**
* 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<BrowserContextEvents> {
}
/**
* Creates a new page in the browser context.
* Creates a new {@link Page | page} in this
* {@link BrowserContext | browser context}.
*/
newPage(): Promise<Page> {
throw new Error('Not implemented');
}
abstract newPage(): Promise<Page>;
/**
* 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<void> {
throw new Error('Not implemented');
abstract close(): Promise<void>;
/**
* 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<void> {
return this.close();
}
}