diff --git a/new-docs/puppeteer.browsercontext._browser.md b/new-docs/puppeteer.browsercontext._browser.md deleted file mode 100644 index 159f43c3..00000000 --- a/new-docs/puppeteer.browsercontext._browser.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserContext](./puppeteer.browsercontext.md) > [\_browser](./puppeteer.browsercontext._browser.md) - -## BrowserContext.\_browser property - -Signature: - -```typescript -_browser: Browser; -``` diff --git a/new-docs/puppeteer.browsercontext._connection.md b/new-docs/puppeteer.browsercontext._connection.md deleted file mode 100644 index 63309bbd..00000000 --- a/new-docs/puppeteer.browsercontext._connection.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserContext](./puppeteer.browsercontext.md) > [\_connection](./puppeteer.browsercontext._connection.md) - -## BrowserContext.\_connection property - -Signature: - -```typescript -_connection: Connection; -``` diff --git a/new-docs/puppeteer.browsercontext._constructor_.md b/new-docs/puppeteer.browsercontext._constructor_.md deleted file mode 100644 index e9372622..00000000 --- a/new-docs/puppeteer.browsercontext._constructor_.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserContext](./puppeteer.browsercontext.md) > [(constructor)](./puppeteer.browsercontext._constructor_.md) - -## BrowserContext.(constructor) - -Constructs a new instance of the `BrowserContext` class - -Signature: - -```typescript -constructor(connection: Connection, browser: Browser, contextId?: string); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| connection | [Connection](./puppeteer.connection.md) | | -| browser | [Browser](./puppeteer.browser.md) | | -| contextId | string | | - diff --git a/new-docs/puppeteer.browsercontext._id.md b/new-docs/puppeteer.browsercontext._id.md deleted file mode 100644 index f238969a..00000000 --- a/new-docs/puppeteer.browsercontext._id.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserContext](./puppeteer.browsercontext.md) > [\_id](./puppeteer.browsercontext._id.md) - -## BrowserContext.\_id property - -Signature: - -```typescript -_id?: string; -``` diff --git a/new-docs/puppeteer.browsercontext.browser.md b/new-docs/puppeteer.browsercontext.browser.md index fcf10e94..92bfd842 100644 --- a/new-docs/puppeteer.browsercontext.browser.md +++ b/new-docs/puppeteer.browsercontext.browser.md @@ -4,6 +4,8 @@ ## BrowserContext.browser() method +The browser this browser context belongs to. + Signature: ```typescript diff --git a/new-docs/puppeteer.browsercontext.clearpermissionoverrides.md b/new-docs/puppeteer.browsercontext.clearpermissionoverrides.md index 1dfbd4ce..0ca4c2f5 100644 --- a/new-docs/puppeteer.browsercontext.clearpermissionoverrides.md +++ b/new-docs/puppeteer.browsercontext.clearpermissionoverrides.md @@ -4,6 +4,8 @@ ## BrowserContext.clearPermissionOverrides() method +Clears all permission overrides for the browser context. + Signature: ```typescript @@ -13,3 +15,14 @@ clearPermissionOverrides(): Promise; Promise<void> +## Example + + +```js +const context = browser.defaultBrowserContext(); +context.overridePermissions('https://example.com', ['clipboard-read']); +// do stuff .. +context.clearPermissionOverrides(); + +``` + diff --git a/new-docs/puppeteer.browsercontext.close.md b/new-docs/puppeteer.browsercontext.close.md index 21916a42..88455198 100644 --- a/new-docs/puppeteer.browsercontext.close.md +++ b/new-docs/puppeteer.browsercontext.close.md @@ -4,6 +4,8 @@ ## BrowserContext.close() method +Closes the browser context. All the targets that belong to the browser context will be closed. + Signature: ```typescript @@ -13,3 +15,7 @@ close(): Promise; Promise<void> +## Remarks + +Only incognito browser contexts can be closed. + diff --git a/new-docs/puppeteer.browsercontext.isincognito.md b/new-docs/puppeteer.browsercontext.isincognito.md index bd509073..f54f9189 100644 --- a/new-docs/puppeteer.browsercontext.isincognito.md +++ b/new-docs/puppeteer.browsercontext.isincognito.md @@ -4,6 +4,8 @@ ## BrowserContext.isIncognito() method +Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context. + Signature: ```typescript @@ -13,3 +15,7 @@ isIncognito(): boolean; boolean +## Remarks + +The default browser context cannot be closed. + diff --git a/new-docs/puppeteer.browsercontext.md b/new-docs/puppeteer.browsercontext.md index 393509a2..7cf0d653 100644 --- a/new-docs/puppeteer.browsercontext.md +++ b/new-docs/puppeteer.browsercontext.md @@ -4,6 +4,8 @@ ## 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. + Signature: ```typescript @@ -11,31 +13,40 @@ export declare class BrowserContext extends EventEmitter ``` Extends: [EventEmitter](./puppeteer.eventemitter.md) -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(connection, browser, contextId)](./puppeteer.browsercontext._constructor_.md) | | Constructs a new instance of the BrowserContext class | +If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser context. -## Properties +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. -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_browser](./puppeteer.browsercontext._browser.md) | | [Browser](./puppeteer.browser.md) | | -| [\_connection](./puppeteer.browsercontext._connection.md) | | [Connection](./puppeteer.connection.md) | | -| [\_id](./puppeteer.browsercontext._id.md) | | string | | +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 + + +```js +// Create a new incognito browser context +const context = await browser.createIncognitoBrowserContext(); +// Create a new page inside context. +const page = await context.newPage(); +// ... do stuff with page ... +await page.goto('https://example.com'); +// Dispose context once it's no longer needed. +await context.close(); + +``` ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [browser()](./puppeteer.browsercontext.browser.md) | | | -| [clearPermissionOverrides()](./puppeteer.browsercontext.clearpermissionoverrides.md) | | | -| [close()](./puppeteer.browsercontext.close.md) | | | -| [isIncognito()](./puppeteer.browsercontext.isincognito.md) | | | -| [newPage()](./puppeteer.browsercontext.newpage.md) | | | +| [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) | | | -| [targets()](./puppeteer.browsercontext.targets.md) | | | -| [waitForTarget(predicate, options)](./puppeteer.browsercontext.waitfortarget.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. | diff --git a/new-docs/puppeteer.browsercontext.newpage.md b/new-docs/puppeteer.browsercontext.newpage.md index dd176f89..b68ba5cc 100644 --- a/new-docs/puppeteer.browsercontext.newpage.md +++ b/new-docs/puppeteer.browsercontext.newpage.md @@ -4,6 +4,8 @@ ## BrowserContext.newPage() method +Creates a new page in the browser context. + Signature: ```typescript diff --git a/new-docs/puppeteer.browsercontext.overridepermissions.md b/new-docs/puppeteer.browsercontext.overridepermissions.md index a917a22f..cebc0666 100644 --- a/new-docs/puppeteer.browsercontext.overridepermissions.md +++ b/new-docs/puppeteer.browsercontext.overridepermissions.md @@ -14,10 +14,19 @@ overridePermissions(origin: string, permissions: Protocol.Browser.PermissionType | Parameter | Type | Description | | --- | --- | --- | -| origin | string | | -| permissions | Protocol.Browser.PermissionType\[\] | | +| origin | string | The origin to grant permissions to, e.g. "https://example.com". | +| permissions | Protocol.Browser.PermissionType\[\] | An array of permissions to grant. All permissions that are not listed here will be automatically denied. | Returns: Promise<void> +## Example + + +```js +const context = browser.defaultBrowserContext(); +await context.overridePermissions('https://html5demos.com', ['geolocation']); + +``` + diff --git a/new-docs/puppeteer.browsercontext.pages.md b/new-docs/puppeteer.browsercontext.pages.md index 0fc2ac18..23a563b0 100644 --- a/new-docs/puppeteer.browsercontext.pages.md +++ b/new-docs/puppeteer.browsercontext.pages.md @@ -4,6 +4,8 @@ ## BrowserContext.pages() method +An array of all pages inside the browser context. + Signature: ```typescript @@ -13,3 +15,5 @@ pages(): Promise; 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). + diff --git a/new-docs/puppeteer.browsercontext.targets.md b/new-docs/puppeteer.browsercontext.targets.md index 05f76d59..57326cc6 100644 --- a/new-docs/puppeteer.browsercontext.targets.md +++ b/new-docs/puppeteer.browsercontext.targets.md @@ -4,6 +4,8 @@ ## BrowserContext.targets() method +An array of all active targets inside the browser context. + Signature: ```typescript diff --git a/new-docs/puppeteer.browsercontext.waitfortarget.md b/new-docs/puppeteer.browsercontext.waitfortarget.md index f1d3b245..c079c048 100644 --- a/new-docs/puppeteer.browsercontext.waitfortarget.md +++ b/new-docs/puppeteer.browsercontext.waitfortarget.md @@ -4,6 +4,8 @@ ## BrowserContext.waitForTarget() method +This searches for a target in this specific browser context. + Signature: ```typescript @@ -16,10 +18,22 @@ waitForTarget(predicate: (x: Target) => boolean, options: { | Parameter | Type | Description | | --- | --- | --- | -| predicate | (x: [Target](./puppeteer.target.md)) => boolean | | -| options | { timeout?: number; } | | +| predicate | (x: [Target](./puppeteer.target.md)) => boolean | A function to be run for every target | +| options | { timeout?: number; } | An object of options. Accepts a timout, which is the maximum wait time in milliseconds. Pass 0 to disable the timeout. Defaults to 30 seconds. | 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`: + +```js +await page.evaluate(() => window.open('https://www.example.com/')); +const newWindowTarget = await browserContext.waitForTarget(target => target.url() === 'https://www.example.com/'); + +``` + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 706a89e1..57bc10a2 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -1,77 +1,77 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) - -## puppeteer package - -## Classes - -| Class | Description | -| --- | --- | -| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium'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 Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | -| [BrowserContext](./puppeteer.browsercontext.md) | | -| [BrowserFetcher](./puppeteer.browserfetcher.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) | | -| [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. | -| [ExecutionContext](./puppeteer.executioncontext.md) | | -| [FileChooser](./puppeteer.filechooser.md) | | -| [Frame](./puppeteer.frame.md) | | -| [FrameManager](./puppeteer.framemanager.md) | | -| [HTTPRequest](./puppeteer.httprequest.md) | | -| [HTTPResponse](./puppeteer.httpresponse.md) | | -| [JSHandle](./puppeteer.jshandle.md) | | -| [Keyboard](./puppeteer.keyboard.md) | | -| [Mouse](./puppeteer.mouse.md) | | -| [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 Chromium. One \[Browser\] instance might have multiple \[Page\] instances. | -| [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class | -| [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) | | -| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | -| [Touchscreen](./puppeteer.touchscreen.md) | | -| [Tracing](./puppeteer.tracing.md) | | -| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | - -## Enumerations - -| Enumeration | Description | -| --- | --- | -| [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [BoundingBox](./puppeteer.boundingbox.md) | | -| [BoxModel](./puppeteer.boxmodel.md) | | -| [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | -| [ClickOptions](./puppeteer.clickoptions.md) | | -| [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | -| [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | -| [PressOptions](./puppeteer.pressoptions.md) | | -| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | -| [SnapshotOptions](./puppeteer.snapshotoptions.md) | | -| [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | - -## Variables - -| Variable | Description | -| --- | --- | -| [EVALUATION\_SCRIPT\_URL](./puppeteer.evaluation_script_url.md) | | -| [keyDefinitions](./puppeteer.keydefinitions.md) | | -| [puppeteerErrors](./puppeteer.puppeteererrors.md) | | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. | -| [KeyInput](./puppeteer.keyinput.md) | | -| [MouseButtonInput](./puppeteer.mousebuttoninput.md) | | -| [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | - + + +[Home](./index.md) > [puppeteer](./puppeteer.md) + +## puppeteer package + +## Classes + +| Class | Description | +| --- | --- | +| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium'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 Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | +| [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. | +| [BrowserFetcher](./puppeteer.browserfetcher.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) | | +| [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. | +| [ExecutionContext](./puppeteer.executioncontext.md) | | +| [FileChooser](./puppeteer.filechooser.md) | | +| [Frame](./puppeteer.frame.md) | | +| [FrameManager](./puppeteer.framemanager.md) | | +| [HTTPRequest](./puppeteer.httprequest.md) | | +| [HTTPResponse](./puppeteer.httpresponse.md) | | +| [JSHandle](./puppeteer.jshandle.md) | | +| [Keyboard](./puppeteer.keyboard.md) | | +| [Mouse](./puppeteer.mouse.md) | | +| [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 Chromium. One \[Browser\] instance might have multiple \[Page\] instances. | +| [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class | +| [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) | | +| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | +| [Touchscreen](./puppeteer.touchscreen.md) | | +| [Tracing](./puppeteer.tracing.md) | | +| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | + +## Enumerations + +| Enumeration | Description | +| --- | --- | +| [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [BoundingBox](./puppeteer.boundingbox.md) | | +| [BoxModel](./puppeteer.boxmodel.md) | | +| [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | +| [ClickOptions](./puppeteer.clickoptions.md) | | +| [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | +| [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | +| [PressOptions](./puppeteer.pressoptions.md) | | +| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | +| [SnapshotOptions](./puppeteer.snapshotoptions.md) | | +| [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | + +## Variables + +| Variable | Description | +| --- | --- | +| [EVALUATION\_SCRIPT\_URL](./puppeteer.evaluation_script_url.md) | | +| [keyDefinitions](./puppeteer.keydefinitions.md) | | +| [puppeteerErrors](./puppeteer.puppeteererrors.md) | | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. | +| [KeyInput](./puppeteer.keyinput.md) | | +| [MouseButtonInput](./puppeteer.mousebuttoninput.md) | | +| [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | + diff --git a/src/common/Browser.ts b/src/common/Browser.ts index 49fe9da7..05fc859d 100644 --- a/src/common/Browser.ts +++ b/src/common/Browser.ts @@ -451,11 +451,41 @@ export class Browser extends EventEmitter { } } +/** + * 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. + * + * @remarks + * + * 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 + * {@link Browser.createIncognitoBrowserContext | Browser.createIncognitoBrowserContext} + * method. "Incognito" browser contexts don't write any browsing data to disk. + * + * @example + * ```js + * // Create a new incognito browser context + * const context = await browser.createIncognitoBrowserContext(); + * // Create a new page inside context. + * const page = await context.newPage(); + * // ... do stuff with page ... + * await page.goto('https://example.com'); + * // Dispose context once it's no longer needed. + * await context.close(); + * ``` + */ export class BrowserContext extends EventEmitter { - _connection: Connection; - _browser: Browser; - _id?: string; + private _connection: Connection; + private _browser: Browser; + private _id?: string; + /** + * @internal + */ constructor(connection: Connection, browser: Browser, contextId?: string) { super(); this._connection = connection; @@ -463,12 +493,32 @@ export class BrowserContext extends EventEmitter { this._id = contextId; } + /** + * An array of all active targets inside the browser context. + */ targets(): Target[] { return this._browser .targets() .filter((target) => target.browserContext() === this); } + /** + * This searches for a target in this specific browser context. + * + * @example + * An example of finding a target for a page opened via `window.open`: + * ```js + * await page.evaluate(() => window.open('https://www.example.com/')); + * const newWindowTarget = await browserContext.waitForTarget(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 timout, + * 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( predicate: (x: Target) => boolean, options: { timeout?: number } = {} @@ -479,6 +529,13 @@ export class BrowserContext extends EventEmitter { ); } + /** + * An array of all pages inside the 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}. + */ async pages(): Promise { const pages = await Promise.all( this.targets() @@ -488,10 +545,28 @@ export class BrowserContext extends EventEmitter { return pages.filter((page) => !!page); } + /** + * Returns whether BrowserContext is incognito. + * The default browser context is the only non-incognito browser context. + * + * @remarks + * The default browser context cannot be closed. + */ isIncognito(): boolean { return !!this._id; } + /** + * @example + * ```js + * const context = browser.defaultBrowserContext(); + * await context.overridePermissions('https://html5demos.com', ['geolocation']); + * ``` + * + * @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. + */ async overridePermissions( origin: string, permissions: Protocol.Browser.PermissionType[] @@ -532,20 +607,44 @@ export class BrowserContext extends EventEmitter { }); } + /** + * Clears all permission overrides for the browser context. + * + * @example + * ```js + * const context = browser.defaultBrowserContext(); + * context.overridePermissions('https://example.com', ['clipboard-read']); + * // do stuff .. + * context.clearPermissionOverrides(); + * ``` + */ async clearPermissionOverrides(): Promise { await this._connection.send('Browser.resetPermissions', { browserContextId: this._id || undefined, }); } + /** + * Creates a new page in the browser context. + */ newPage(): Promise { return this._browser._createPageInContext(this._id); } + /** + * The browser this browser context belongs to. + */ browser(): Browser { return this._browser; } + /** + * Closes the browser context. All the targets that belong to the browser context + * will be closed. + * + * @remarks + * Only incognito browser contexts can be closed. + */ async close(): Promise { assert(this._id, 'Non-incognito profiles cannot be closed!'); await this._browser._disposeContext(this._id);