refactor!: rename createIncognitoBrowserContext to createBrowserConte…

…xt (#11834)
puppeteer · Feb 5, 2024 · 46a3ef2 · 46a3ef2
1 parent c63414d
commit 46a3ef2
Show file tree

Hide file tree

Showing 18 changed files with 117 additions and 115 deletions.
diff --git a/docs/api/index.md b/docs/api/index.md
diff --git a/....browser.createincognitobrowsercontext.md → ...puppeteer.browser.createbrowsercontext.md b/....browser.createincognitobrowsercontext.md → ...puppeteer.browser.createbrowsercontext.md
@@ -1,18 +1,18 @@
 ---
-sidebar_label: Browser.createIncognitoBrowserContext
+sidebar_label: Browser.createBrowserContext
 ---
 
-# Browser.createIncognitoBrowserContext() method
+# Browser.createBrowserContext() method
 
-Creates a new incognito [browser context](./puppeteer.browsercontext.md).
+Creates a new [browser context](./puppeteer.browsercontext.md).
 
 This won't share cookies/cache with other [browser contexts](./puppeteer.browsercontext.md).
 
 #### Signature:
 
 ```typescript
 class Browser {
-  abstract createIncognitoBrowserContext(
+  abstract createBrowserContext(
     options?: BrowserContextOptions
   ): Promise<BrowserContext>;
 }
@@ -34,8 +34,8 @@ Promise&lt;[BrowserContext](./puppeteer.browsercontext.md)&gt;
 import puppeteer from 'puppeteer';
 
 const browser = await puppeteer.launch();
-// Create a new incognito browser context.
-const context = await browser.createIncognitoBrowserContext();
+// Create a new browser context.
+const context = await browser.createBrowserContext();
 // Create a new page in a pristine context.
 const page = await context.newPage();
 // Do stuff

diff --git a/docs/api/puppeteer.browser.md b/docs/api/puppeteer.browser.md
diff --git a/docs/api/puppeteer.browsercontext.isincognito.md b/docs/api/puppeteer.browsercontext.isincognito.md
@@ -6,7 +6,7 @@ sidebar_label: BrowserContext.isIncognito
 
 Whether this [browser context](./puppeteer.browsercontext.md) is incognito.
 
-The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context.
+In Chrome, the [default browser context](./puppeteer.browser.defaultbrowsercontext.md) is the only non-incognito browser context.
 
 #### Signature:
 

diff --git a/docs/api/puppeteer.browsercontext.md b/docs/api/puppeteer.browsercontext.md
@@ -4,9 +4,9 @@ sidebar_label: BrowserContext
 
 # BrowserContext class
 
-[BrowserContext](./puppeteer.browsercontext.md) represents individual sessions within a [browser](./puppeteer.browser.md).
+[BrowserContext](./puppeteer.browsercontext.md) represents individual user contexts 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).
+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.createBrowserContext()](./puppeteer.browser.createbrowsercontext.md). Each context has isolated storage (cookies/localStorage/etc.)
 
 [BrowserContext](./puppeteer.browsercontext.md) [emits](./puppeteer.eventemitter.md) various events which are documented in the [BrowserContextEvent](./puppeteer.browsercontextevent.md) enum.
 
@@ -26,11 +26,11 @@ The constructor for this class is marked as internal. Third-party code should no
 
 ## Example
 
-Creating an incognito [browser context](./puppeteer.browsercontext.md):
+Creating a new [browser context](./puppeteer.browsercontext.md):
 
 ```ts
-// Create a new incognito browser context
-const context = await browser.createIncognitoBrowserContext();
+// Create a new browser context
+const context = await browser.createBrowserContext();
 // Create a new page inside context.
 const page = await context.newPage();
 // ... do stuff with page ...
@@ -48,14 +48,14 @@ await context.close();
 
 ## Methods
 
-| 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>         |
+| 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>In Chrome, 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/packages/puppeteer-core/src/api/Browser.ts b/packages/puppeteer-core/src/api/Browser.ts
@@ -136,7 +136,7 @@ export const enum BrowserEvent {
    * Emitted when the URL of a target changes. Contains a {@link Target}
    * instance.
    *
-   * @remarks Note that this includes target changes in incognito browser
+   * @remarks Note that this includes target changes in all browser
    * contexts.
    */
   TargetChanged = 'targetchanged',
@@ -147,15 +147,15 @@ export const enum BrowserEvent {
    *
    * Contains a {@link Target} instance.
    *
-   * @remarks Note that this includes target creations in incognito browser
+   * @remarks Note that this includes target creations in all browser
    * contexts.
    */
   TargetCreated = 'targetcreated',
   /**
    * Emitted when a target is destroyed, for example when a page is closed.
    * Contains a {@link Target} instance.
    *
-   * @remarks Note that this includes target destructions in incognito browser
+   * @remarks Note that this includes target destructions in all browser
    * contexts.
    */
   TargetDestroyed = 'targetdestroyed',
@@ -244,7 +244,7 @@ export abstract class Browser extends EventEmitter<BrowserEvents> {
   abstract process(): ChildProcess | null;
 
   /**
-   * Creates a new incognito {@link BrowserContext | browser context}.
+   * Creates a new {@link BrowserContext | browser context}.
    *
    * This won't share cookies/cache with other {@link BrowserContext | browser contexts}.
    *
@@ -254,15 +254,15 @@ export abstract class Browser extends EventEmitter<BrowserEvents> {
    * import puppeteer from 'puppeteer';
    *
    * const browser = await puppeteer.launch();
-   * // Create a new incognito browser context.
-   * const context = await browser.createIncognitoBrowserContext();
+   * // Create a new browser context.
+   * const context = await browser.createBrowserContext();
    * // Create a new page in a pristine context.
    * const page = await context.newPage();
    * // Do stuff
    * await page.goto('https://example.com');
    * ```
    */
-  abstract createIncognitoBrowserContext(
+  abstract createBrowserContext(
     options?: BrowserContextOptions
   ): Promise<BrowserContext>;
 

diff --git a/packages/puppeteer-core/src/api/BrowserContext.ts b/packages/puppeteer-core/src/api/BrowserContext.ts
@@ -48,12 +48,13 @@ export interface BrowserContextEvents extends Record<EventType, unknown> {
 }
 
 /**
- * {@link BrowserContext} represents individual sessions within a
+ * {@link BrowserContext} represents individual user contexts within a
  * {@link Browser | browser}.
  *
  * 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}.
+ * using {@link Browser.createBrowserContext}. Each context has isolated storage
+ * (cookies/localStorage/etc.)
  *
  * {@link BrowserContext} {@link EventEmitter | emits} various events which are
  * documented in the {@link BrowserContextEvent} enum.
@@ -62,11 +63,11 @@ export interface BrowserContextEvents extends Record<EventType, unknown> {
  * `window.open`, the popup will belong to the parent {@link Page.browserContext
  * | page's browser context}.
  *
- * @example Creating an incognito {@link BrowserContext | browser context}:
+ * @example Creating a new {@link BrowserContext | browser context}:
  *
  * ```ts
- * // Create a new incognito browser context
- * const context = await browser.createIncognitoBrowserContext();
+ * // Create a new browser context
+ * const context = await browser.createBrowserContext();
  * // Create a new page inside context.
  * const page = await context.newPage();
  * // ... do stuff with page ...
@@ -124,8 +125,9 @@ export abstract class BrowserContext extends EventEmitter<BrowserContextEvents>
   /**
    * Whether this {@link BrowserContext | browser context} is incognito.
    *
-   * The {@link Browser.defaultBrowserContext | default browser context} is the
-   * only non-incognito browser context.
+   * In Chrome, the
+   * {@link Browser.defaultBrowserContext | default browser context} is the only
+   * non-incognito browser context.
    */
   abstract isIncognito(): boolean;
 

diff --git a/packages/puppeteer-core/src/bidi/Browser.ts b/packages/puppeteer-core/src/bidi/Browser.ts
@@ -262,7 +262,7 @@ export class BidiBrowser extends Browser {
     return this.#process ?? null;
   }
 
-  override async createIncognitoBrowserContext(
+  override async createBrowserContext(
     _options?: BrowserContextOptions
   ): Promise<BidiBrowserContext> {
     const userContext = await this.#browserCore.createUserContext();

diff --git a/packages/puppeteer-core/src/cdp/Browser.ts b/packages/puppeteer-core/src/cdp/Browser.ts
@@ -201,7 +201,7 @@ export class CdpBrowser extends BrowserBase {
     return this.#isPageTargetCallback;
   }
 
-  override async createIncognitoBrowserContext(
+  override async createBrowserContext(
     options: BrowserContextOptions = {}
   ): Promise<CdpBrowserContext> {
     const {proxyServer, proxyBypassList} = options;

diff --git a/test/src/browsercontext.spec.ts b/test/src/browsercontext.spec.ts
@@ -34,7 +34,7 @@ describe('BrowserContext', function () {
     });
 
     expect(browser.browserContexts()).toHaveLength(1);
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     expect(context.isIncognito()).toBe(true);
     expect(browser.browserContexts()).toHaveLength(2);
     expect(browser.browserContexts().indexOf(context) !== -1).toBe(true);
@@ -48,7 +48,7 @@ describe('BrowserContext', function () {
 
     expect(await browser.pages()).toHaveLength(1);
 
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     await context.newPage();
     expect(await browser.pages()).toHaveLength(2);
     expect(await context.pages()).toHaveLength(1);
@@ -128,7 +128,7 @@ describe('BrowserContext', function () {
   it('should timeout waiting for a non-existent target', async () => {
     const {browser, server} = await getTestState();
 
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     const error = await context
       .waitForTarget(
         target => {
@@ -151,8 +151,8 @@ describe('BrowserContext', function () {
     });
 
     // Create two incognito contexts.
-    const context1 = await browser.createIncognitoBrowserContext();
-    const context2 = await browser.createIncognitoBrowserContext();
+    const context1 = await browser.createBrowserContext();
+    const context2 = await browser.createBrowserContext();
     expect(context1.targets()).toHaveLength(0);
     expect(context2.targets()).toHaveLength(0);
 
@@ -213,7 +213,7 @@ describe('BrowserContext', function () {
     });
 
     expect(browser.browserContexts()).toHaveLength(1);
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     try {
       expect(browser.browserContexts()).toHaveLength(2);
       const remoteBrowser = await puppeteer.connect({
@@ -236,7 +236,7 @@ describe('BrowserContext', function () {
     expect(browser.browserContexts()).toHaveLength(1);
     expect(browser.browserContexts()[0]!.id).toBeUndefined();
 
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     expect(browser.browserContexts()).toHaveLength(2);
     expect(browser.browserContexts()[1]!.id).toBeDefined();
     await context.close();
@@ -336,7 +336,7 @@ describe('BrowserContext', function () {
       const {page, server, context, browser} = await getTestState();
 
       await page.goto(server.EMPTY_PAGE);
-      const otherContext = await browser.createIncognitoBrowserContext();
+      const otherContext = await browser.createBrowserContext();
       const otherPage = await otherContext.newPage();
       await otherPage.goto(server.EMPTY_PAGE);
       expect(await getPermission(page, 'geolocation')).toBe('prompt');

diff --git a/test/src/cdp/devtools.spec.ts b/test/src/cdp/devtools.spec.ts
@@ -93,7 +93,7 @@ describe('DevTools', function () {
     const browser = await launchBrowser(
       Object.assign({devtools: true}, launchOptions)
     );
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     await Promise.all([
       context.newPage(),
       browser.waitForTarget((target: {url: () => string | string[]}) => {
@@ -106,7 +106,7 @@ describe('DevTools', function () {
     const browser = await launchBrowser(
       Object.assign({devtools: true}, launchOptions)
     );
-    const context = await browser.createIncognitoBrowserContext();
+    const context = await browser.createBrowserContext();
     const [target] = await Promise.all([
       browser.waitForTarget((target: {url: () => string | string[]}) => {
         return target.url().includes('devtools://');

diff --git a/test/src/cookies.spec.ts b/test/src/cookies.spec.ts
@@ -224,7 +224,7 @@ describe('Cookie specs', () => {
     it('should isolate cookies in browser contexts', async () => {
       const {page, server, browser} = await getTestState();
 
-      const anotherContext = await browser.createIncognitoBrowserContext();
+      const anotherContext = await browser.createBrowserContext();
       const anotherPage = await anotherContext.newPage();
 
       await page.goto(server.EMPTY_PAGE);

diff --git a/test/src/device-request-prompt.spec.ts b/test/src/device-request-prompt.spec.ts
@@ -28,7 +28,7 @@ describe('device request prompt', function () {
   });
 
   beforeEach(async () => {
-    state.context = await state.browser.createIncognitoBrowserContext();
+    state.context = await state.browser.createBrowserContext();
     state.page = await state.context.newPage();
   });
 

diff --git a/test/src/ignorehttpserrors.spec.ts b/test/src/ignorehttpserrors.spec.ts
@@ -32,7 +32,7 @@ describe('ignoreHTTPSErrors', function () {
   });
 
   beforeEach(async () => {
-    state.context = await state.browser.createIncognitoBrowserContext();
+    state.context = await state.browser.createBrowserContext();
     state.page = await state.context.newPage();
   });