thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(new): add TSDoc comments to BrowserContext (#6066)

Browse Source
This commit is contained in:
Tim van der Lippe 2020-06-23 06:21:01 +01:00 committed by Mathias Bynens
parent ccae54644c
commit 4659ee8daa
16 changed files with 270 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
new-docs/puppeteer.browsercontext._browser.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [\_browser](./puppeteer.browsercontext._browser.md)
## BrowserContext.\_browser property
<b>Signature:</b>
```typescript
_browser: Browser;
```

11
new-docs/puppeteer.browsercontext._connection.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [\_connection](./puppeteer.browsercontext._connection.md)
## BrowserContext.\_connection property
<b>Signature:</b>
```typescript
_connection: Connection;
```

22
new-docs/puppeteer.browsercontext._constructor_.md
View File

@ -1,22 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [(constructor)](./puppeteer.browsercontext._constructor_.md)
## BrowserContext.(constructor)
Constructs a new instance of the `BrowserContext` class
<b>Signature:</b>
```typescript
constructor(connection: Connection, browser: Browser, contextId?: string);
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| connection | [Connection](./puppeteer.connection.md) | |
| browser | [Browser](./puppeteer.browser.md) | |
| contextId | string | |

11
new-docs/puppeteer.browsercontext._id.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserContext](./puppeteer.browsercontext.md) &gt; [\_id](./puppeteer.browsercontext._id.md)
## BrowserContext.\_id property
<b>Signature:</b>
```typescript
_id?: string;
```

2
new-docs/puppeteer.browsercontext.browser.md
View File

@ -4,6 +4,8 @@
## BrowserContext.browser() method
The browser this browser context belongs to.
<b>Signature:</b>
```typescript

13
new-docs/puppeteer.browsercontext.clearpermissionoverrides.md
View File

@ -4,6 +4,8 @@
## BrowserContext.clearPermissionOverrides() method
Clears all permission overrides for the browser context.
<b>Signature:</b>
```typescript
@ -13,3 +15,14 @@ clearPermissionOverrides(): Promise<void>;
Promise&lt;void&gt;
## Example
```js
const context = browser.defaultBrowserContext();
context.overridePermissions('https://example.com', ['clipboard-read']);
// do stuff ..
context.clearPermissionOverrides();
```

6
new-docs/puppeteer.browsercontext.close.md
View File

@ -4,6 +4,8 @@
## BrowserContext.close() method
Closes the browser context. All the targets that belong to the browser context will be closed.
<b>Signature:</b>
```typescript
@ -13,3 +15,7 @@ close(): Promise<void>;
Promise&lt;void&gt;
## Remarks
Only incognito browser contexts can be closed.

6
new-docs/puppeteer.browsercontext.isincognito.md
View File

@ -4,6 +4,8 @@
## BrowserContext.isIncognito() method
Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context.
<b>Signature:</b>
```typescript
@ -13,3 +15,7 @@ isIncognito(): boolean;
boolean
## Remarks
The default browser context cannot be closed.

47
new-docs/puppeteer.browsercontext.md
View File

@ -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.
<b>Signature:</b>
```typescript
@ -11,31 +13,40 @@ export declare class BrowserContext extends EventEmitter
```
<b>Extends:</b> [EventEmitter](./puppeteer.eventemitter.md)
## Constructors
## Remarks
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(connection, browser, contextId)](./puppeteer.browsercontext._constructor_.md) | | Constructs a new instance of the <code>BrowserContext</code> 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. |

2
new-docs/puppeteer.browsercontext.newpage.md
View File

@ -4,6 +4,8 @@
## BrowserContext.newPage() method
Creates a new page in the browser context.
<b>Signature:</b>
```typescript

13
new-docs/puppeteer.browsercontext.overridepermissions.md
View File

@ -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. |
<b>Returns:</b>
Promise&lt;void&gt;
## Example
```js
const context = browser.defaultBrowserContext();
await context.overridePermissions('https://html5demos.com', ['geolocation']);
```

4
new-docs/puppeteer.browsercontext.pages.md
View File

@ -4,6 +4,8 @@
## BrowserContext.pages() method
An array of all pages inside the browser context.
<b>Signature:</b>
```typescript
@ -13,3 +15,5 @@ pages(): Promise<Page[]>;
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)<!-- -->.

2
new-docs/puppeteer.browsercontext.targets.md
View File

@ -4,6 +4,8 @@
## BrowserContext.targets() method
An array of all active targets inside the browser context.
<b>Signature:</b>
```typescript

18
new-docs/puppeteer.browsercontext.waitfortarget.md
View File

@ -4,6 +4,8 @@
## BrowserContext.waitForTarget() method
This searches for a target in this specific browser context.
<b>Signature:</b>
```typescript
@ -16,10 +18,22 @@ waitForTarget(predicate: (x: Target) => boolean, options: {
| Parameter | Type | Description |
| --- | --- | --- |
| predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; boolean | |
| options | { timeout?: number; } | |
| predicate | (x: [Target](./puppeteer.target.md)<!-- -->) =&gt; 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 <code>0</code> to disable the timeout. Defaults to 30 seconds. |
<b>Returns:</b>
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`<!-- -->:
```js
await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browserContext.waitForTarget(target => target.url() === 'https://www.example.com/');
```

2
new-docs/puppeteer.md
View File

@ -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) | 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) | |
| [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 <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
| [Connection](./puppeteer.connection.md) | |

105
src/common/Browser.ts
View File

@ -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<Page[]> {
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<void> {
await this._connection.send('Browser.resetPermissions', {
browserContextId: this._id || undefined,
});
}
/**
* Creates a new page in the browser context.
*/
newPage(): Promise<Page> {
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<void> {
assert(this._id, 'Non-incognito profiles cannot be closed!');
await this._browser._disposeContext(this._id);