From c7fecdb30b75c735afb9e38fba4fe4905405ea4a Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Mon, 22 Jun 2020 11:41:15 +0100 Subject: [PATCH] feat(new-docs): add TSDoc comments to BrowserContext --- new-docs/puppeteer.browsercontext._browser.md | 11 -- .../puppeteer.browsercontext._connection.md | 11 -- .../puppeteer.browsercontext._constructor_.md | 22 ---- new-docs/puppeteer.browsercontext._id.md | 11 -- new-docs/puppeteer.browsercontext.browser.md | 2 + ...browsercontext.clearpermissionoverrides.md | 13 +++ new-docs/puppeteer.browsercontext.close.md | 6 + .../puppeteer.browsercontext.isincognito.md | 6 + new-docs/puppeteer.browsercontext.md | 47 +++++--- new-docs/puppeteer.browsercontext.newpage.md | 2 + ...teer.browsercontext.overridepermissions.md | 13 ++- new-docs/puppeteer.browsercontext.pages.md | 4 + new-docs/puppeteer.browsercontext.targets.md | 2 + .../puppeteer.browsercontext.waitfortarget.md | 18 ++- new-docs/puppeteer.md | 2 +- src/common/Browser.ts | 105 +++++++++++++++++- 16 files changed, 194 insertions(+), 81 deletions(-) delete mode 100644 new-docs/puppeteer.browsercontext._browser.md delete mode 100644 new-docs/puppeteer.browsercontext._connection.md delete mode 100644 new-docs/puppeteer.browsercontext._constructor_.md delete mode 100644 new-docs/puppeteer.browsercontext._id.md diff --git a/new-docs/puppeteer.browsercontext._browser.md b/new-docs/puppeteer.browsercontext._browser.md deleted file mode 100644 index 159f43c313142..0000000000000 --- 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 63309bbd6ac26..0000000000000 --- 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 e9372622d1152..0000000000000 --- 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 f238969a7950b..0000000000000 --- 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 fcf10e94eb7cd..92bfd8429862d 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 1dfbd4ceb98e1..0ca4c2f5ced38 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 21916a420fb02..88455198dad50 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 bd5090732955f..f54f9189acb27 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 393509a20ef7a..7cf0d65392a23 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. + +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. -## Properties +## Example -| 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 | | + +```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 dd176f891500b..b68ba5cc78a64 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 a917a22fc3518..cebc0666c3017 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 0fc2ac1807a10..23a563b0da234 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 05f76d59142da..57326cc646697 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 f1d3b24520dd4..c079c048b3f59 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 d6ba6af699f70..f56497cb9ef47 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -10,7 +10,7 @@ | --- | --- | | [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) | | -| [BrowserContext](./puppeteer.browsercontext.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) | | | [Connection](./puppeteer.connection.md) | | diff --git a/src/common/Browser.ts b/src/common/Browser.ts index 8aa7d7a291ad6..9b44876bd6429 100644 --- a/src/common/Browser.ts +++ b/src/common/Browser.ts @@ -290,11 +290,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; @@ -302,12 +332,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 } @@ -318,6 +368,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() @@ -327,10 +384,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[] @@ -371,20 +446,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);