Fix Playwright tunnel restart race

Author: justinTM

common/changes/playwright-local-browser-server/fix-tunnel-stop-start-race_2026-06-29-18-00.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "playwright-local-browser-server",
+      "comment": "Fix a race where restarting the Playwright tunnel could create a replacement before the previous tunnel finished stopping.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "playwright-local-browser-server",
+  "email": "9123665+justinTM@users.noreply.github.com"
+}

common/config/subspaces/default/pnpm-lock.yaml

@@ -0,0 +1,4 @@
+{
+  "extends": "@rushstack/heft-vscode-extension-rig/profiles/default/config/jest.config.json",
+  "testPathIgnorePatterns": ["/node_modules/", "/lib/vscodeTest/"]
+}

vscode-extensions/playwright-local-browser-server-vscode-extension/config/jest.config.json

@@ -34,8 +34,9 @@
     "build": "heft build --clean",
     "build:watch": "heft build-watch",
     "start": "heft start",
+    "test:vscode": "node ./lib/vscodeTest/runTest.js",
     "_phase:build": "heft run --only build -- --clean",
-    "_phase:test": ""
+    "_phase:test": "heft run --only test -- --clean"
   },
   "contributes": {
     "commands": [
@@ -106,9 +107,14 @@
     "@rushstack/heft-vscode-extension-rig": "workspace:*",
     "@rushstack/heft-node-rig": "workspace:*",
     "@rushstack/heft": "workspace:*",
+    "@types/glob": "7.1.1",
+    "@types/mocha": "10.0.6",
     "@types/node": "20.17.19",
     "@types/vscode": "1.103.0",
-    "@types/webpack-env": "1.18.8"
+    "@types/webpack-env": "1.18.8",
+    "@vscode/test-electron": "^1.6.2",
+    "glob": "~7.0.5",
+    "mocha": "^10.1.0"
   },
   "sideEffects": false
 }

vscode-extensions/playwright-local-browser-server-vscode-extension/package.json

@@ -157,6 +157,7 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
 
   // Tunnel instance
   let tunnel: PlaywrightTunnel | undefined;
+  let stopTunnelPromise: Promise<void> | undefined;
 
   function getTmpPath(): string {
     return path.join(os.tmpdir(), 'playwright-browser-tunnel');
@@ -290,6 +291,12 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
   }
 
   async function handleStartTunnelAsync(isAutoStart: boolean = false): Promise<void> {
+    const pendingStopPromise: Promise<void> | undefined = stopTunnelPromise;
+    if (pendingStopPromise) {
+      outputChannel.appendLine('Waiting for Playwright tunnel to stop before starting again...');
+      await pendingStopPromise;
+    }
+
     // Store current tunnel reference to avoid race conditions
     const existingTunnel: PlaywrightTunnel | undefined = tunnel;
     if (existingTunnel && currentStatus !== 'stopped' && currentStatus !== 'error') {
@@ -439,27 +446,39 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
   }
 
   async function handleStopTunnelAsync(): Promise<void> {
+    const pendingStopPromise: Promise<void> | undefined = stopTunnelPromise;
+    if (pendingStopPromise) {
+      outputChannel.appendLine('Tunnel stop already in progress.');
+      await pendingStopPromise;
+      return;
+    }
+
     const currentTunnel: PlaywrightTunnel | undefined = tunnel;
     if (!currentTunnel) {
       outputChannel.appendLine('No tunnel instance to stop.');
       void vscode.window.showInformationMessage('Playwright tunnel is not running.');
       return;
     }
 
-    // Clear the reference before awaiting to avoid race condition
-    tunnel = undefined;
-
-    try {
+    const currentStopPromise: Promise<void> = (async () => {
       outputChannel.appendLine('Stopping Playwright tunnel...');
-      await currentTunnel.stopAsync();
-      updateStatusBar('stopped');
-      outputChannel.appendLine('Tunnel stopped.');
-      void vscode.window.showInformationMessage('Playwright tunnel stopped.');
-    } catch (error) {
-      const errorMessage: string = getNormalizedErrorString(error);
-      outputChannel.appendLine(`Failed to stop tunnel: ${errorMessage}`);
-      void vscode.window.showErrorMessage(`Failed to stop Playwright tunnel: ${errorMessage}`);
-    }
+      try {
+        await currentTunnel.stopAsync();
+        tunnel = undefined;
+        updateStatusBar('stopped');
+        outputChannel.appendLine('Tunnel stopped.');
+        void vscode.window.showInformationMessage('Playwright tunnel stopped.');
+      } catch (error) {
+        const errorMessage: string = getNormalizedErrorString(error);
+        outputChannel.appendLine(`Failed to stop tunnel: ${errorMessage}`);
+        void vscode.window.showErrorMessage(`Failed to stop Playwright tunnel: ${errorMessage}`);
+      } finally {
+        stopTunnelPromise = undefined;
+      }
+    })();
+
+    stopTunnelPromise = currentStopPromise;
+    await currentStopPromise;
   }
 
   async function handleShowMenu(): Promise<void> {

vscode-extensions/playwright-local-browser-server-vscode-extension/src/extension.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type * as vscode from 'vscode';
+
+type CommandHandler = (...args: unknown[]) => unknown;
+
+const commandHandlers: Map<string, CommandHandler> = new Map();
+
+let autoStart: boolean = false;
+
+const createOutputChannelMock = jest.fn(() => ({
+  appendLine: jest.fn(),
+  show: jest.fn(),
+  dispose: jest.fn()
+}));
+
+jest.mock(
+  'vscode',
+  () => ({
+    StatusBarAlignment: {
+      Right: 2
+    },
+    ThemeColor: jest.fn(),
+    Uri: {
+      file: jest.fn((filePath: string) => ({ fsPath: filePath }))
+    },
+    commands: {
+      executeCommand: jest.fn(),
+      registerCommand: jest.fn((command: string, handler: CommandHandler) => {
+        commandHandlers.set(command, handler);
+        return { dispose: jest.fn() };
+      })
+    },
+    env: {
+      remoteName: undefined
+    },
+    window: {
+      createOutputChannel: createOutputChannelMock,
+      createStatusBarItem: jest.fn(() => ({
+        show: jest.fn(),
+        dispose: jest.fn()
+      })),
+      showErrorMessage: jest.fn(),
+      showInformationMessage: jest.fn(async () => 'Just This Once'),
+      showQuickPick: jest.fn(),
+      showTextDocument: jest.fn(),
+      showWarningMessage: jest.fn()
+    },
+    workspace: {
+      fs: {
+        writeFile: jest.fn()
+      },
+      getConfiguration: jest.fn(() => ({
+        get: jest.fn((name: string, defaultValue: unknown) => {
+          switch (name) {
+            case 'autoStart':
+              return autoStart;
+            case 'tunnelPort':
+              return 56767;
+            default:
+              return defaultValue;
+          }
+        }),
+        update: jest.fn()
+      })),
+      workspaceFolders: undefined
+    },
+    ConfigurationTarget: {
+      Global: 1
+    }
+  }),
+  { virtual: true }
+);
+
+jest.mock('@rushstack/terminal', () => ({
+  Terminal: jest.fn()
+}));
+
+jest.mock('@rushstack/vscode-shared/lib/VScodeOutputChannelTerminalProvider', () => ({
+  VScodeOutputChannelTerminalProvider: jest.fn()
+}));
+
+jest.mock('@rushstack/vscode-shared/lib/runWorkspaceCommandAsync', () => ({
+  runWorkspaceCommandAsync: jest.fn()
+}));
+
+jest.mock('@rushstack/playwright-browser-tunnel/lib/LaunchOptionsValidator', () => ({
+  LaunchOptionsValidator: {
+    validateLaunchOptionsAsync: jest.fn(),
+    readAllowlistAsync: jest.fn(),
+    getAllowlistFilePath: jest.fn(),
+    addToAllowlistAsync: jest.fn(),
+    removeFromAllowlistAsync: jest.fn(),
+    clearAllowlistAsync: jest.fn()
+  }
+}));
+
+class MockPlaywrightTunnel {
+  public static readonly instances: MockPlaywrightTunnel[] = [];
+
+  private _resolveStop!: () => void;
+  private _stopPromise: Promise<void> = new Promise((resolve) => {
+    this._resolveStop = resolve;
+  });
+
+  public readonly startAsync: jest.Mock<Promise<void>, []> = jest.fn(async () => {
+    await new Promise(() => {
+      // The real tunnel runs continuously until it is stopped.
+    });
+  });
+
+  public readonly stopAsync: jest.Mock<Promise<void>, []> = jest.fn(async () => {
+    await this._stopPromise;
+  });
+
+  public constructor() {
+    MockPlaywrightTunnel.instances.push(this);
+  }
+
+  public resolveStop(): void {
+    this._resolveStop();
+  }
+}
+
+jest.mock('@rushstack/playwright-browser-tunnel/lib/PlaywrightBrowserTunnel', () => ({
+  PlaywrightTunnel: MockPlaywrightTunnel
+}));
+
+describe('playwright-local-browser-server extension lifecycle', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    commandHandlers.clear();
+    MockPlaywrightTunnel.instances.length = 0;
+    autoStart = false;
+  });
+
+  it('waits for an in-progress stop before starting a replacement tunnel', async () => {
+    const { activate } = await import('../extension');
+
+    await activate({ subscriptions: [] } as unknown as vscode.ExtensionContext);
+
+    const startTunnelAsync: CommandHandler = commandHandlers.get('playwright-local-browser-server.start')!;
+    const stopTunnelAsync: CommandHandler = commandHandlers.get('playwright-local-browser-server.stop')!;
+
+    await startTunnelAsync();
+    expect(MockPlaywrightTunnel.instances).toHaveLength(1);
+
+    const firstTunnel: MockPlaywrightTunnel = MockPlaywrightTunnel.instances[0];
+    const stopPromise: Promise<unknown> = Promise.resolve(stopTunnelAsync());
+    expect(firstTunnel.stopAsync).toHaveBeenCalledTimes(1);
+
+    const restartPromise: Promise<unknown> = Promise.resolve(startTunnelAsync());
+    await Promise.resolve();
+
+    expect(MockPlaywrightTunnel.instances).toHaveLength(1);
+
+    firstTunnel.resolveStop();
+    await stopPromise;
+    await restartPromise;
+
+    expect(MockPlaywrightTunnel.instances).toHaveLength(2);
+  });
+});

vscode-extensions/playwright-local-browser-server-vscode-extension/src/test/extension.test.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { runTests } from '@vscode/test-electron';
+
+async function main(): Promise<void> {
+  try {
+    const extensionDevelopmentPath: string = path.resolve(__dirname, '../../dist/vsix/unpacked');
+    const extensionTestsPath: string = path.resolve(__dirname, './suite/index');
+    const testDataPath: string = path.join(os.tmpdir(), 'playwright-local-browser-server-vscode-test');
+
+    await runTests({
+      vscodeExecutablePath: process.env.VSCODE_EXECUTABLE_PATH,
+      extensionDevelopmentPath,
+      extensionTestsPath,
+      launchArgs: [
+        path.join(testDataPath, 'workspace'),
+        '--user-data-dir',
+        path.join(testDataPath, 'user-data'),
+        '--extensions-dir',
+        path.join(testDataPath, 'extensions'),
+        '--disable-workspace-trust',
+        '--skip-welcome',
+        '--skip-release-notes'
+      ]
+    });
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error('Failed to run VS Code extension tests', error);
+    process.exit(1);
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+main();