feat: add proxy and bypass list parameters to createIncognitoBrowserC…

…ontext (#7516)

Example:

(async () => {
  const browser = await puppeteer.launch();
  const context = await browser.createIncognitoBrowserContext('myproxy.com:3128');
  const page = await context.newPage()
  await page.authenticate({username: 'foo', password: 'bar' });
  await page.goto('https://google.com');
  await browser.close();
})();

Issue: #678

docs/api.md

@@ -75,7 +75,7 @@
   * [event: 'targetdestroyed'](#event-targetdestroyed)
   * [browser.browserContexts()](#browserbrowsercontexts)
   * [browser.close()](#browserclose)
-  * [browser.createIncognitoBrowserContext()](#browsercreateincognitobrowsercontext)
+  * [browser.createIncognitoBrowserContext([options])](#browsercreateincognitobrowsercontextoptions)
   * [browser.defaultBrowserContext()](#browserdefaultbrowsercontext)
   * [browser.disconnect()](#browserdisconnect)
   * [browser.isConnected()](#browserisconnected)
@@ -886,8 +886,10 @@ Closes Chromium and all of its pages (if any were opened). The [Browser] object
 
 During the process of closing the browser, Puppeteer attempts to delete the temp folder created exclusively for this browser instance. If this fails (either because a file in the temp folder is locked by another process or because of insufficient permissions) an error is logged. This implies that: a) the folder and/or its content is not fully deleted; and b) the connection with the browser is not properly disposed (see [browser.disconnect()](#browserdisconnect)).
 
-#### browser.createIncognitoBrowserContext()
-
+#### browser.createIncognitoBrowserContext([options])
+- `options` <[Object]> Set of configurable options to set on the browserContext. Can have the following fields:
+  - `proxyServer` <[string]> Optional proxy server with optional port to use for all requests. Username and password can be set in [page.authenticate(credentials)](#pageauthenticatecredentials).
+  - `proxyBypassList` <[string]> Optional: Bypass the proxy for the given semi-colon-separated list of hosts.
 - returns: <[Promise]<[BrowserContext]>>
 
 Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.

src/common/Browser.ts

@@ -24,6 +24,23 @@ import { Page } from './Page.js';
 import { ChildProcess } from 'child_process';
 import { Viewport } from './PuppeteerViewport.js';
 
+/**
+ * BrowserContext options.
+ *
+ * @public
+ */
+export interface BrowserContextOptions {
+  /**
+   * Proxy server with optional port to use for all requests.
+   * Username and password can be set in `Page.authenticate`.
+   */
+  proxyServer?: string;
+  /**
+   * Bypass the proxy for the given semi-colon-separated list of hosts.
+   */
+  proxyBypassList?: string[];
+}
+
 /**
  * @internal
  */
@@ -295,9 +312,17 @@ export class Browser extends EventEmitter {
    * })();
    * ```
    */
-  async createIncognitoBrowserContext(): Promise<BrowserContext> {
+  async createIncognitoBrowserContext(
+    options: BrowserContextOptions = {}
+  ): Promise<BrowserContext> {
+    const { proxyServer = '', proxyBypassList = [] } = options;
+
     const { browserContextId } = await this._connection.send(
-      'Target.createBrowserContext'
+      'Target.createBrowserContext',
+      {
+        proxyServer,
+        proxyBypassList: proxyBypassList && proxyBypassList.join(','),
+      }
     );
     const context = new BrowserContext(
       this._connection,

utils/doclint/check_public_api/index.js

@@ -655,6 +655,13 @@ function compareDocumentations(actual, expected) {
             '"load"|"domcontentloaded"|"networkidle0"|"networkidle2"|Array<PuppeteerLifeCycleEvent>',
         },
       ],
+      [
+        'Method Browser.createIncognitoBrowserContext() options',
+        {
+          actualName: 'Object',
+          expectedName: 'BrowserContextOptions',
+        },
+      ],
       [
         'Method BrowserContext.overridePermissions() permissions',
         {