feat(launchServer): accept wsPath option (#8353)

docs/src/api/class-browsertype.md

@@ -284,6 +284,18 @@ const { chromium } = require('playwright');  // Or 'webkit' or 'firefox'.
 
 Port to use for the web socket. Defaults to 0 that picks any available port.
 
+### option: BrowserType.launchServer.wsPath
+- `wsPath` <[string]>
+
+Path at which to serve the Browser Server. For security, this defaults to an
+unguessable string.
+
+:::warning
+Any process or web page (including those running in Playwright) with knowledge
+of the `wsPath` can take control of the OS user. For this reason, you should
+use an unguessable token when using this option.
+:::
+
 ## method: BrowserType.name
 - returns: <[string]>
 

src/browserServerImpl.ts

@@ -52,9 +52,13 @@ export class BrowserServerLauncherImpl implements BrowserServerLauncher {
       env: options.env ? envObjectToArray(options.env) : undefined,
     }, toProtocolLogger(options.logger));
 
+    let path = `/${createGuid()}`;
+    if (options.wsPath)
+      path = options.wsPath.startsWith('/') ? options.wsPath : `/${options.wsPath}`;
+
     // 2. Start the server
     const delegate: PlaywrightServerDelegate = {
-      path: '/' + createGuid(),
+      path,
       allowMultipleClients: true,
       onClose: () => {},
       onConnect: this._onConnect.bind(this, playwright, browser),

src/client/types.ts

@@ -100,6 +100,7 @@ export type LaunchServerOptions = {
   downloadsPath?: string,
   chromiumSandbox?: boolean,
   port?: number,
+  wsPath?: string,
   logger?: Logger,
 } & FirefoxUserPrefs;
 

tests/browsertype-launch-server.spec.ts

@@ -33,6 +33,26 @@ it.describe('launch server', () => {
     await browserServer.close();
   });
 
+  it('should work with wsPath', async ({browserType, browserOptions}) => {
+    const wsPath = '/unguessable-token';
+    const browserServer = await browserType.launchServer({ ...browserOptions, wsPath });
+    expect(browserServer.wsEndpoint()).toMatch(/:\d+\/unguessable-token$/);
+    await browserServer.close();
+  });
+
+  it('should work when wsPath is missing leading slash', async ({browserType, browserOptions}) => {
+    const wsPath = 'unguessable-token';
+    const browserServer = await browserType.launchServer({ ...browserOptions, wsPath });
+    expect(browserServer.wsEndpoint()).toMatch(/:\d+\/unguessable-token$/);
+    await browserServer.close();
+  });
+
+  it('should default to random wsPath', async ({browserType, browserOptions}) => {
+    const browserServer = await browserType.launchServer({ ...browserOptions });
+    expect(browserServer.wsEndpoint()).toMatch(/:\d+\/[a-f\d]{32}$/);
+    await browserServer.close();
+  });
+
   it('should provide an error when ws endpoint is incorrect', async ({browserType, browserOptions}) => {
     const browserServer = await browserType.launchServer(browserOptions);
     const error = await browserType.connect({ wsEndpoint: browserServer.wsEndpoint() + '-foo' }).catch(e => e);

types/types.d.ts

@@ -8725,6 +8725,14 @@ export interface BrowserType<Unused = {}> {
      * If specified, traces are saved into this directory.
      */
     tracesDir?: string;
+
+    /**
+     * Path at which to serve the Browser Server. For security, this defaults to an unguessable string.
+     *
+     * > NOTE: Any process or web page (including those running in Playwright) with knowledge of the `wsPath` can take control
+     * of the OS user. For this reason, you should use an unguessable token when using this option.
+     */
+    wsPath?: string;
   }): Promise<BrowserServer>;
 
   /**