feat: implement BrowserContext.closed (#10928)

puppeteer · Sep 18, 2023 · 2292078 · 2292078
1 parent fd72101
commit 2292078
Show file tree

Hide file tree

Showing 12 changed files with 169 additions and 151 deletions.
diff --git a/docs/api/index.md b/docs/api/index.md
diff --git a/docs/api/puppeteer.browsercontext.browser.md b/docs/api/puppeteer.browsercontext.browser.md
@@ -4,13 +4,13 @@ sidebar_label: BrowserContext.browser
 
 # BrowserContext.browser() method
 
-The browser this browser context belongs to.
+Gets the [browser](./puppeteer.browser.md) associated with this [browser context](./puppeteer.browsercontext.md).
 
 #### Signature:
 
 ```typescript
 class BrowserContext {
-  browser(): Browser;
+  abstract browser(): Browser;
 }
 ```
 

diff --git a/docs/api/puppeteer.browsercontext.clearpermissionoverrides.md b/docs/api/puppeteer.browsercontext.clearpermissionoverrides.md
@@ -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']);

diff --git a/docs/api/puppeteer.browsercontext.close.md b/docs/api/puppeteer.browsercontext.close.md
@@ -4,13 +4,13 @@ sidebar_label: BrowserContext.close
 
 # BrowserContext.close() method
 
-Closes the browser context. All the targets that belong to the browser context will be closed.
+Closes this [browser context](./puppeteer.browsercontext.md) and all associated [pages](./puppeteer.page.md).
 
 #### Signature:
 
 ```typescript
 class BrowserContext {
-  close(): Promise<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.
diff --git a/docs/api/puppeteer.browsercontext.isincognito.md b/docs/api/puppeteer.browsercontext.isincognito.md
@@ -4,20 +4,18 @@ sidebar_label: BrowserContext.isIncognito
 
 # BrowserContext.isIncognito() method
 
-Returns whether BrowserContext is incognito. The default browser context is the only non-incognito browser context.
+Whether this [browser context](./puppeteer.browsercontext.md) is incognito.
+
+The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context.
 
 #### Signature:
 
 ```typescript
 class BrowserContext {
-  isIncognito(): boolean;
+  abstract isIncognito(): boolean;
 }
 ```
 
 **Returns:**
 
 boolean
-
-## Remarks
-
-The default browser context cannot be closed.
diff --git a/docs/api/puppeteer.browsercontext.md b/docs/api/puppeteer.browsercontext.md
@@ -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>         |
diff --git a/docs/api/puppeteer.browsercontext.newpage.md b/docs/api/puppeteer.browsercontext.newpage.md
@@ -4,13 +4,13 @@ sidebar_label: BrowserContext.newPage
 
 # BrowserContext.newPage() method
 
-Creates a new page in the browser context.
+Creates a new [page](./puppeteer.page.md) in this [browser context](./puppeteer.browsercontext.md).
 
 #### Signature:
 
 ```typescript
 class BrowserContext {
-  newPage(): Promise<Page>;
+  abstract newPage(): Promise<Page>;
 }
 ```
 

diff --git a/docs/api/puppeteer.browsercontext.overridepermissions.md b/docs/api/puppeteer.browsercontext.overridepermissions.md
@@ -4,6 +4,8 @@ sidebar_label: BrowserContext.overridePermissions
 
 # BrowserContext.overridePermissions() method
 
+Grants this [browser context](./puppeteer.browsercontext.md) the given `permissions` within the given `origin`.
+
 #### Signature:
 
 ```typescript
@@ -25,6 +27,8 @@ Promise&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']);

diff --git a/docs/api/puppeteer.browsercontext.pages.md b/docs/api/puppeteer.browsercontext.pages.md
@@ -4,18 +4,20 @@ 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[]>;
 }
 ```
 
 **Returns:**
 
 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).
diff --git a/docs/api/puppeteer.browsercontext.targets.md b/docs/api/puppeteer.browsercontext.targets.md
@@ -4,7 +4,7 @@ sidebar_label: BrowserContext.targets
 
 # BrowserContext.targets() method
 
-An array of all active targets inside the browser context.
+Gets all active [targets](./puppeteer.target.md) inside this [browser context](./puppeteer.browsercontext.md).
 
 #### Signature:
 

diff --git a/docs/api/puppeteer.browsercontext.waitfortarget.md b/docs/api/puppeteer.browsercontext.waitfortarget.md
@@ -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/'));