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

@@ -34,6 +34,7 @@
     "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": ""
   },
@@ -108,7 +109,8 @@
     "@rushstack/heft": "workspace:*",
     "@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"
   },
   "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,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();

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

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as assert from 'node:assert';
+
+import * as vscode from 'vscode';
+
+const EXTENSION_ID: string = 'ms-RushStack.playwright-local-browser-server';
+const COMMAND_START_TUNNEL: string = 'playwright-local-browser-server.start';
+const COMMAND_STOP_TUNNEL: string = 'playwright-local-browser-server.stop';
+
+function sleepAsync(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function promiseSettledWithinAsync(promise: Thenable<unknown>, milliseconds: number): Promise<boolean> {
+  let settled: boolean = false;
+  promise.then(
+    () => {
+      settled = true;
+    },
+    () => {
+      settled = true;
+    }
+  );
+  await sleepAsync(milliseconds);
+  return settled;
+}
+
+export async function run(): Promise<void> {
+  const extension: vscode.Extension<unknown> | undefined = vscode.extensions.getExtension(EXTENSION_ID);
+  assert.ok(extension, `Expected ${EXTENSION_ID} to be installed in the VS Code test host.`);
+
+  await extension.activate();
+
+  const commands: string[] = await vscode.commands.getCommands(true);
+  assert.ok(commands.includes(COMMAND_START_TUNNEL), `Missing command: ${COMMAND_START_TUNNEL}`);
+  assert.ok(commands.includes(COMMAND_STOP_TUNNEL), `Missing command: ${COMMAND_STOP_TUNNEL}`);
+
+  await vscode.workspace
+    .getConfiguration('playwright-local-browser-server')
+    .update('autoStart', true, vscode.ConfigurationTarget.Global);
+
+  await vscode.commands.executeCommand(COMMAND_START_TUNNEL, true);
+  await sleepAsync(250);
+
+  const stopPromise: Thenable<unknown> = vscode.commands.executeCommand(COMMAND_STOP_TUNNEL);
+  await sleepAsync(250);
+
+  const restartPromise: Thenable<unknown> = vscode.commands.executeCommand(COMMAND_START_TUNNEL, true);
+
+  assert.strictEqual(
+    await promiseSettledWithinAsync(restartPromise, 1000),
+    false,
+    'Start resolved while the previous Stop command was still pending.'
+  );
+
+  assert.strictEqual(
+    await promiseSettledWithinAsync(stopPromise, 1),
+    false,
+    'Stop unexpectedly settled before the restart guard could be observed.'
+  );
+
+  // eslint-disable-next-line no-console
+  console.log('Playwright tunnel restart remained pending behind the in-progress stop.');
+}