playwright 1.56.0-alpha-2025-09-11 → 1.56.0-alpha-2025-09-12

package/README.md

@@ -1,6 +1,6 @@
 # 🎭 Playwright
 
-[![npm version](https://img.shields.io/npm/v/playwright.svg)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-141.0.7390.7-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-142.0.1-blue.svg?logo=firefoxbrowser)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> <!-- GEN:webkit-version-badge -->[![WebKit version](https://img.shields.io/badge/webkit-26.0-blue.svg?logo=safari)](https://webkit.org/)<!-- GEN:stop --> [![Join Discord](https://img.shields.io/badge/join-discord-informational)](https://aka.ms/playwright/discord)
+[![npm version](https://img.shields.io/npm/v/playwright.svg)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-141.0.7390.16-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-142.0.1-blue.svg?logo=firefoxbrowser)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> <!-- GEN:webkit-version-badge -->[![WebKit version](https://img.shields.io/badge/webkit-26.0-blue.svg?logo=safari)](https://webkit.org/)<!-- GEN:stop --> [![Join Discord](https://img.shields.io/badge/join-discord-informational)](https://aka.ms/playwright/discord)
 
 ## [Documentation](https://playwright.dev) | [API reference](https://playwright.dev/docs/api/class-playwright)
 
@@ -8,7 +8,7 @@ Playwright is a framework for Web Testing and Automation. It allows testing [Chr
 
 |          | Linux | macOS | Windows |
 |   :---   | :---: | :---: | :---:   |
-| Chromium <!-- GEN:chromium-version -->141.0.7390.7<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Chromium <!-- GEN:chromium-version -->141.0.7390.16<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | WebKit <!-- GEN:webkit-version -->26.0<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | Firefox <!-- GEN:firefox-version -->142.0.1<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 

package/lib/agents/fixer.md

@@ -9,18 +9,18 @@ tools:
   - read
   - write
   - edit
-  - playwright-test/browser_evaluate
-  - playwright-test/browser_generate_locator
-  - playwright-test/browser_snapshot
-  - playwright-test/playwright_test_debug_test
-  - playwright-test/playwright_test_list_tests
-  - playwright-test/playwright_test_run_tests
+  - playwright/browser_evaluate
+  - playwright/browser_generate_locator
+  - playwright/browser_snapshot
+  - playwright/test_debug
+  - playwright/test_list
+  - playwright/test_run
+  - playwright/test_setup_page
 mcp-servers:
-  playwright-test:
+  playwright:
     type: 'local'
     command: 'npx'
     args: ['playwright', 'run-test-mcp-server']
-    tools: ['*']
 ---
 
 You are the Playwright Test Fixer, an expert test automation engineer specializing in debugging and

package/lib/agents/generator.md

@@ -1,8 +1,8 @@
 ---
 name: playwright-test-generator
 description: Use this agent when you need to create automated browser tests using Playwright
-color: blue
 model: sonnet
+color: blue
 tools:
   - ls
   - grep
@@ -24,16 +24,12 @@ tools:
   - playwright/browser_verify_text_visible
   - playwright/browser_verify_value
   - playwright/browser_wait_for
+  - playwright/test_setup_page
 mcp-servers:
   playwright:
     type: 'local'
     command: 'npx'
-    args:
-    - 'playwright'
-    - 'run-mcp-server'
-    - '--isolated'
-    - '--viewport-size=1280,720'
-    - '--caps=testing'
+    args: ['playwright', 'run-test-mcp-server']
 ---
 
 You are a Playwright Test Generator, an expert in browser automation and end-to-end testing. Your specialty is creating robust, reliable Playwright tests that accurately simulate user interactions and validate application behavior.
@@ -42,7 +38,9 @@ Your process is methodical and thorough:
 
 1. **Scenario Analysis**: Carefully analyze the test scenario provided, identifying all user actions, expected outcomes, and validation points. Break down complex flows into discrete, testable steps.
 
-2. **Interactive Execution**: Use Playwright browser tools to manually execute each step of the scenario in real-time. This allows you to:
+2. **Interactive Execution**:
+   - For each test, start with the `test_setup_page` tool to set up page for the scenario
+   - Use Playwright tools to manually execute each step of the scenario in real-time
    - Verify that each action works as expected
    - Identify the correct locators and interaction patterns
    - Observe actual application behavior and responses

package/lib/agents/planner.md

@@ -25,22 +25,22 @@ tools:
   - playwright/browser_take_screenshot
   - playwright/browser_type
   - playwright/browser_wait_for
+  - playwright/test_setup_page
 mcp-servers:
   playwright:
     type: 'local'
     command: 'npx'
-    args:
-    - 'playwright'
-    - 'run-mcp-server'
-    - '--isolated'
-    - '--viewport-size=1280,720'
+    args: ['playwright', 'run-test-mcp-server']
 ---
 
 You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test scenario design. Your expertise includes functional testing, usability testing, edge case identification, and comprehensive test coverage planning.
 
 When given a target web page or application, you will:
 
-1. **Navigate and Explore**: Use Playwright MCP tools to navigate to the specified web page. Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality.
+1. **Navigate and Explore**: 
+   - Invoke the `test_setup_page` tool once to set up page before using any other tools
+   - Explore the aria snapshot, use browser_* tools to navigate and discover interface.
+   - Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality
 
 2. **Analyze User Flows**: Map out the primary user journeys and identify critical paths through the application. Consider different user types and their typical behaviors.
 

package/lib/index.js

@@ -399,6 +399,7 @@ const playwrightFixtures = {
     if (!_reuseContext) {
       const { context: context2, close } = await _contextFactory();
       await use(context2);
+      await (0, import_browserBackend.runBrowserBackendAtEnd)(context2);
       await close();
       return;
     }

package/lib/mcp/browser/browserContextFactory.js

@@ -38,6 +38,7 @@ var import_path = __toESM(require("path"));
 var playwright = __toESM(require("playwright-core"));
 var import_registry = require("playwright-core/lib/server/registry/index");
 var import_server = require("playwright-core/lib/server");
+var import_processUtils = require("./processUtils");
 var import_log = require("../log");
 var import_config = require("./config");
 function contextFactory(config) {
@@ -160,32 +161,32 @@ class PersistentContextFactory {
     (0, import_log.testDebug)("lock user data dir", userDataDir);
     const browserType = playwright[this.config.browser.browserName];
     for (let i = 0; i < 5; i++) {
-      const launchOptions = {
-        tracesDir,
-        ...this.config.browser.launchOptions,
-        ...this.config.browser.contextOptions,
-        handleSIGINT: false,
-        handleSIGTERM: false,
-        ignoreDefaultArgs: [
-          "--disable-extensions"
-        ],
-        assistantMode: true
-      };
-      try {
-        const browserContext = await browserType.launchPersistentContext(userDataDir, launchOptions);
-        const close = () => this._closeBrowserContext(browserContext, userDataDir);
-        return { browserContext, close };
-      } catch (error) {
-        if (error.message.includes("Executable doesn't exist"))
-          throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-        if (error.message.includes("ProcessSingleton") || error.message.includes("Invalid URL")) {
-          await new Promise((resolve) => setTimeout(resolve, 1e3));
-          continue;
-        }
-        throw error;
-      }
+      if (!await alreadyRunning(this.config, browserType, userDataDir))
+        break;
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    }
+    const launchOptions = {
+      tracesDir,
+      ...this.config.browser.launchOptions,
+      ...this.config.browser.contextOptions,
+      handleSIGINT: false,
+      handleSIGTERM: false,
+      ignoreDefaultArgs: [
+        "--disable-extensions"
+      ],
+      assistantMode: true
+    };
+    try {
+      const browserContext = await browserType.launchPersistentContext(userDataDir, launchOptions);
+      const close = () => this._closeBrowserContext(browserContext, userDataDir);
+      return { browserContext, close };
+    } catch (error) {
+      if (error.message.includes("Executable doesn't exist"))
+        throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+      if (error.message.includes("ProcessSingleton") || error.message.includes("Invalid URL"))
+        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+      throw error;
     }
-    throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
   }
   async _closeBrowserContext(browserContext, userDataDir) {
     (0, import_log.testDebug)("close browser context (persistent)");
@@ -204,6 +205,12 @@ class PersistentContextFactory {
     return result;
   }
 }
+async function alreadyRunning(config, browserType, userDataDir) {
+  const execPath = config.browser.launchOptions.executablePath ?? (0, import_processUtils.getBrowserExecPath)(config.browser.launchOptions.channel ?? browserType.name());
+  if (!execPath)
+    return false;
+  return !!(0, import_processUtils.findBrowserProcess)(execPath, userDataDir);
+}
 async function injectCdpPort(browserConfig) {
   if (browserConfig.browserName === "chromium")
     browserConfig.launchOptions.cdpPort = await findFreePort();

package/lib/mcp/browser/processUtils.js

@@ -0,0 +1,102 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var processUtils_exports = {};
+__export(processUtils_exports, {
+  findBrowserProcess: () => findBrowserProcess,
+  getBrowserExecPath: () => getBrowserExecPath
+});
+module.exports = __toCommonJS(processUtils_exports);
+var import_child_process = __toESM(require("child_process"));
+var import_fs = __toESM(require("fs"));
+var import_registry = require("playwright-core/lib/server/registry/index");
+function getBrowserExecPath(channelOrName) {
+  return import_registry.registry.findExecutable(channelOrName)?.executablePath("javascript");
+}
+function findBrowserProcess(execPath, arg) {
+  const predicate = (line) => line.includes(execPath) && line.includes(arg) && !line.includes("--type");
+  try {
+    switch (process.platform) {
+      case "darwin":
+        return findProcessMacos(predicate);
+      case "linux":
+        return findProcessLinux(predicate);
+      case "win32":
+        return findProcessWindows(execPath, arg, predicate);
+      default:
+        return void 0;
+    }
+  } catch {
+    return void 0;
+  }
+}
+function findProcessLinux(predicate) {
+  const procDirs = import_fs.default.readdirSync("/proc").filter((name) => /^\d+$/.test(name));
+  for (const pid of procDirs) {
+    try {
+      const cmdlineBuffer = import_fs.default.readFileSync(`/proc/${pid}/cmdline`);
+      const cmdline = cmdlineBuffer.toString().replace(/\0/g, " ").trim();
+      if (predicate(cmdline))
+        return `${pid} ${cmdline}`;
+    } catch {
+      continue;
+    }
+  }
+  return void 0;
+}
+function findProcessMacos(predicate) {
+  const result = import_child_process.default.spawnSync("/bin/ps", ["-axo", "pid=,command="]);
+  if (result.status !== 0 || !result.stdout)
+    return void 0;
+  return findMatchingLine(result.stdout.toString(), predicate);
+}
+function findProcessWindows(execPath, arg, predicate) {
+  const psEscape = (path) => `'${path.replaceAll("'", "''")}'`;
+  const filter = `$_.ExecutablePath -eq ${psEscape(execPath)} -and $_.CommandLine.Contains(${psEscape(arg)}) -and $_.CommandLine -notmatch '--type'`;
+  const ps = import_child_process.default.spawnSync(
+    "powershell.exe",
+    [
+      "-NoProfile",
+      "-Command",
+      `Get-CimInstance Win32_Process | Where-Object { ${filter} } | Select-Object -Property ProcessId,CommandLine | ForEach-Object { "$($_.ProcessId) $($_.CommandLine)" }`
+    ],
+    { encoding: "utf8" }
+  );
+  if (ps.status !== 0 || !ps.stdout)
+    return void 0;
+  return findMatchingLine(ps.stdout.toString(), predicate);
+}
+function findMatchingLine(psOutput, predicate) {
+  const lines = psOutput.split("\n").map((l) => l.trim()).filter(Boolean);
+  return lines.find(predicate);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findBrowserProcess,
+  getBrowserExecPath
+});

package/lib/mcp/browser/watchdog.js

@@ -0,0 +1,42 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var watchdog_exports = {};
+__export(watchdog_exports, {
+  setupExitWatchdog: () => setupExitWatchdog
+});
+module.exports = __toCommonJS(watchdog_exports);
+var import_context = require("./context");
+function setupExitWatchdog() {
+  let isExiting = false;
+  const handleExit = async () => {
+    if (isExiting)
+      return;
+    isExiting = true;
+    setTimeout(() => process.exit(0), 15e3);
+    await import_context.Context.disposeAll();
+    process.exit(0);
+  };
+  process.stdin.on("close", handleExit);
+  process.on("SIGINT", handleExit);
+  process.on("SIGTERM", handleExit);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  setupExitWatchdog
+});

package/lib/mcp/program.js

@@ -34,7 +34,7 @@ module.exports = __toCommonJS(program_exports);
 var import_utilsBundle = require("playwright-core/lib/utilsBundle");
 var mcpServer = __toESM(require("./sdk/server"));
 var import_config = require("./browser/config");
-var import_context = require("./browser/context");
+var import_watchdog = require("./browser/watchdog");
 var import_browserContextFactory = require("./browser/browserContextFactory");
 var import_proxyBackend = require("./sdk/proxyBackend");
 var import_browserServerBackend = require("./browser/browserServerBackend");
@@ -42,7 +42,7 @@ var import_extensionContextFactory = require("./extension/extensionContextFactor
 var import_host = require("./vscode/host");
 function decorateCommand(command, version) {
   command.option("--allowed-origins <origins>", "semicolon-separated list of origins to allow the browser to request. Default is to allow all.", import_config.semicolonSeparatedList).option("--blocked-origins <origins>", "semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.", import_config.semicolonSeparatedList).option("--block-service-workers", "block service workers").option("--browser <browser>", "browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.").option("--caps <caps>", "comma-separated list of additional capabilities to enable, possible values: vision, pdf.", import_config.commaSeparatedList).option("--cdp-endpoint <endpoint>", "CDP endpoint to connect to.").option("--cdp-header <headers...>", "CDP headers to send with the connect request, multiple can be specified.", import_config.headerParser).option("--config <path>", "path to the configuration file.").option("--device <device>", 'device to emulate, for example: "iPhone 15"').option("--executable-path <path>", "path to the browser executable.").option("--extension", 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').option("--headless", "run browser in headless mode, headed by default").option("--host <host>", "host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.").option("--ignore-https-errors", "ignore https errors").option("--isolated", "keep the browser profile in memory, do not save it to disk.").option("--image-responses <mode>", 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".').option("--no-sandbox", "disable the sandbox for all process types that are normally sandboxed.").option("--output-dir <path>", "path to the directory for output files.").option("--port <port>", "port to listen on for SSE transport.").option("--proxy-bypass <bypass>", 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"').option("--proxy-server <proxy>", 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"').option("--save-session", "Whether to save the Playwright MCP session into the output directory.").option("--save-trace", "Whether to save the Playwright Trace of the session into the output directory.").option("--secrets <path>", "path to a file containing secrets in the dotenv format", import_config.dotenvFileLoader).option("--storage-state <path>", "path to the storage state file for isolated sessions.").option("--timeout-action <timeout>", "specify action timeout in milliseconds, defaults to 5000ms", import_config.numberParser).option("--timeout-navigation <timeout>", "specify navigation timeout in milliseconds, defaults to 60000ms", import_config.numberParser).option("--user-agent <ua string>", "specify user agent string").option("--user-data-dir <path>", "path to the user data directory. If not specified, a temporary directory will be created.").option("--viewport-size <size>", 'specify browser viewport size in pixels, for example "1280, 720"').addOption(new import_utilsBundle.ProgramOption("--connect-tool", "Allow to switch between different browser connection methods.").hideHelp()).addOption(new import_utilsBundle.ProgramOption("--vscode", "VS Code tools.").hideHelp()).addOption(new import_utilsBundle.ProgramOption("--vision", "Legacy option, use --caps=vision instead").hideHelp()).action(async (options) => {
-    setupExitWatchdog();
+    (0, import_watchdog.setupExitWatchdog)();
     if (options.vision) {
       console.error("The --vision option is deprecated, use --caps=vision instead");
       options.caps = "vision";
@@ -95,20 +95,6 @@ function decorateCommand(command, version) {
     await mcpServer.start(factory, config.server);
   });
 }
-function setupExitWatchdog() {
-  let isExiting = false;
-  const handleExit = async () => {
-    if (isExiting)
-      return;
-    isExiting = true;
-    setTimeout(() => process.exit(0), 15e3);
-    await import_context.Context.disposeAll();
-    process.exit(0);
-  };
-  process.stdin.on("close", handleExit);
-  process.on("SIGINT", handleExit);
-  process.on("SIGTERM", handleExit);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   decorateCommand

package/lib/mcp/sdk/mdb.js

@@ -46,21 +46,19 @@ const z = mcpBundle.z;
 class MDBBackend {
   constructor(topLevelBackend) {
     this._stack = [];
-    this._initialized = false;
     this._topLevelBackend = topLevelBackend;
   }
-  async initialize(server) {
-    if (this._initialized)
-      return;
-    this._initialized = true;
-    const transport = await (0, import_server.wrapInProcess)(this._topLevelBackend);
-    await this._pushClient(transport);
+  async initialize(server, clientVersion, roots) {
+    if (!this._roots)
+      this._roots = roots;
   }
   async listTools() {
-    const response = await this._client().listTools();
+    const client = await this._client();
+    const response = await client.listTools();
     return response.tools;
   }
   async callTool(name, args) {
+    await this._client();
     if (name === pushToolsSchema.name)
       return await this._pushTools(pushToolsSchema.inputSchema.parse(args || {}));
     const interruptPromise = new import_utils.ManualPromise();
@@ -69,26 +67,20 @@ class MDBBackend {
     while (entry && !entry.toolNames.includes(name)) {
       mdbDebug("popping client from stack for ", name);
       this._stack.shift();
-      await entry.client.close();
+      await entry.client.close().catch(errorsDebug);
       entry = this._stack[0];
     }
     if (!entry)
       throw new Error(`Tool ${name} not found in the tool stack`);
+    const client = await this._client();
     const resultPromise = new import_utils.ManualPromise();
     entry.resultPromise = resultPromise;
-    this._client().callTool({
+    client.callTool({
       name,
       arguments: args
     }).then((result2) => {
       resultPromise.resolve(result2);
-    }).catch((e) => {
-      mdbDebug("error in client call", e);
-      if (this._stack.length < 2)
-        throw e;
-      this._stack.shift();
-      const prevEntry = this._stack[0];
-      void prevEntry.resultPromise.then((result2) => resultPromise.resolve(result2));
-    });
+    }).catch((e) => resultPromise.reject(e));
     const result = await Promise.race([interruptPromise, resultPromise]);
     if (interruptPromise.isDone())
       mdbDebug("client call intercepted", result);
@@ -96,11 +88,12 @@ class MDBBackend {
       mdbDebug("client call result", result);
     return result;
   }
-  _client() {
-    const [entry] = this._stack;
-    if (!entry)
-      throw new Error("No debugging backend available");
-    return entry.client;
+  async _client() {
+    if (!this._stack.length) {
+      const transport = await (0, import_server.wrapInProcess)(this._topLevelBackend);
+      await this._pushClient(transport);
+    }
+    return this._stack[0].client;
   }
   async _pushTools(params) {
     mdbDebug("pushing tools to the stack", params.mcpUrl);
@@ -110,7 +103,8 @@ class MDBBackend {
   }
   async _pushClient(transport, introMessage) {
     mdbDebug("pushing client to the stack");
-    const client = new mcpBundle.Client({ name: "Internal client", version: "0.0.0" });
+    const client = new mcpBundle.Client({ name: "Internal client", version: "0.0.0" }, { capabilities: { roots: {} } });
+    client.setRequestHandler(mcpBundle.ListRootsRequestSchema, () => ({ roots: this._roots || [] }));
     client.setRequestHandler(mcpBundle.PingRequestSchema, () => ({}));
     await client.connect(transport);
     mdbDebug("connected to the new client");
@@ -151,7 +145,7 @@ async function runMainBackend(backendFactory, options) {
   await mcpServer.connect(factory, new mcpBundle.StdioServerTransport(), false);
 }
 async function runOnPauseBackendLoop(backend, introMessage) {
-  const wrappedBackend = new OnceTimeServerBackendWrapper(backend);
+  const wrappedBackend = new ServerBackendWithCloseListener(backend);
   const factory = {
     name: "on-pause-backend",
     nameInConfig: "on-pause-backend",
@@ -184,11 +178,10 @@ async function startAsHttp(backendFactory, options) {
   await mcpHttp.installHttpTransport(httpServer, backendFactory);
   return mcpHttp.httpAddressToString(httpServer.address());
 }
-class OnceTimeServerBackendWrapper {
+class ServerBackendWithCloseListener {
   constructor(backend) {
-    this._selfDestructPromise = new import_utils.ManualPromise();
+    this._serverClosedPromise = new import_utils.ManualPromise();
     this._backend = backend;
-    this._backend.requestSelfDestruct = () => this._selfDestructPromise.resolve();
   }
   async initialize(server, clientVersion, roots) {
     await this._backend.initialize?.(server, clientVersion, roots);
@@ -201,10 +194,10 @@ class OnceTimeServerBackendWrapper {
   }
   serverClosed(server) {
     this._backend.serverClosed?.(server);
-    this._selfDestructPromise.resolve();
+    this._serverClosedPromise.resolve();
   }
   async waitForClosed() {
-    await this._selfDestructPromise;
+    await this._serverClosedPromise;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/lib/mcp/sdk/proxyBackend.js

@@ -43,10 +43,10 @@ class ProxyBackend {
   }
   async initialize(server, clientVersion, roots) {
     this._roots = roots;
-    await this._setCurrentClient(this._mcpProviders[0]);
   }
   async listTools() {
-    const response = await this._currentClient.listTools();
+    const currentClient = await this._ensureCurrentClient();
+    const response = await currentClient.listTools();
     if (this._mcpProviders.length === 1)
       return response.tools;
     return [
@@ -57,7 +57,8 @@ class ProxyBackend {
   async callTool(name, args) {
     if (name === this._contextSwitchTool.name)
       return this._callContextSwitchTool(args);
-    return await this._currentClient.callTool({
+    const currentClient = await this._ensureCurrentClient();
+    return await currentClient.callTool({
       name,
       arguments: args
     });
@@ -100,6 +101,11 @@ Error: ${error}
       }
     };
   }
+  async _ensureCurrentClient() {
+    if (this._currentClient)
+      return this._currentClient;
+    return await this._setCurrentClient(this._mcpProviders[0]);
+  }
   async _setCurrentClient(factory) {
     await this._currentClient?.close();
     this._currentClient = void 0;
@@ -114,6 +120,7 @@ Error: ${error}
     const transport = await factory.connect();
     await client.connect(transport);
     this._currentClient = client;
+    return client;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/lib/mcp/sdk/server.js

@@ -39,7 +39,6 @@ var mcpBundle = __toESM(require("./bundle"));
 var import_http = require("./http");
 var import_inProcessTransport = require("./inProcessTransport");
 const serverDebug = (0, import_utilsBundle.debug)("pw:mcp:server");
-const errorsDebug = (0, import_utilsBundle.debug)("pw:mcp:errors");
 async function connect(factory, transport, runHeartbeat) {
   const server = createServer(factory.name, factory.version, factory.create(), runHeartbeat);
   await server.connect(transport);
@@ -49,9 +48,6 @@ async function wrapInProcess(backend) {
   return new import_inProcessTransport.InProcessTransport(server);
 }
 function createServer(name, version, backend, runHeartbeat) {
-  let initializedPromiseResolve = () => {
-  };
-  const initializedPromise = new Promise((resolve) => initializedPromiseResolve = resolve);
   const server = new mcpBundle.Server({ name, version }, {
     capabilities: {
       tools: {}
@@ -59,19 +55,16 @@ function createServer(name, version, backend, runHeartbeat) {
   });
   server.setRequestHandler(mcpBundle.ListToolsRequestSchema, async () => {
     serverDebug("listTools");
-    await initializedPromise;
     const tools = await backend.listTools();
     return { tools };
   });
-  let heartbeatRunning = false;
+  let initializePromise;
   server.setRequestHandler(mcpBundle.CallToolRequestSchema, async (request) => {
     serverDebug("callTool", request);
-    await initializedPromise;
-    if (runHeartbeat && !heartbeatRunning) {
-      heartbeatRunning = true;
-      startHeartbeat(server);
-    }
     try {
+      if (!initializePromise)
+        initializePromise = initializeServer(server, backend, runHeartbeat);
+      await initializePromise;
       return await backend.callTool(request.params.name, request.params.arguments || {});
     } catch (error) {
       return {
@@ -80,30 +73,21 @@ function createServer(name, version, backend, runHeartbeat) {
       };
     }
   });
-  addServerListener(server, "initialized", async () => {
-    try {
-      const capabilities = server.getClientCapabilities();
-      let clientRoots = [];
-      if (capabilities?.roots) {
-        for (let i = 0; i < 2; i++) {
-          try {
-            const { roots } = await server.listRoots(void 0, { timeout: 2e3 });
-            clientRoots = roots;
-          } catch (e) {
-            continue;
-          }
-        }
-      }
-      const clientVersion = server.getClientVersion() ?? { name: "unknown", version: "unknown" };
-      await backend.initialize?.(server, clientVersion, clientRoots);
-      initializedPromiseResolve();
-    } catch (e) {
-      errorsDebug(e);
-    }
-  });
   addServerListener(server, "close", () => backend.serverClosed?.(server));
   return server;
 }
+const initializeServer = async (server, backend, runHeartbeat) => {
+  const capabilities = server.getClientCapabilities();
+  let clientRoots = [];
+  if (capabilities?.roots) {
+    const { roots } = await server.listRoots();
+    clientRoots = roots;
+  }
+  const clientVersion = server.getClientVersion() ?? { name: "unknown", version: "unknown" };
+  await backend.initialize?.(server, clientVersion, clientRoots);
+  if (runHeartbeat)
+    startHeartbeat(server);
+};
 const startHeartbeat = (server) => {
   const beat = () => {
     Promise.race([

package/lib/mcp/test/browserBackend.js

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var browserBackend_exports = {};
 __export(browserBackend_exports, {
+  runBrowserBackendAtEnd: () => runBrowserBackendAtEnd,
   runBrowserBackendOnError: () => runBrowserBackendOnError
 });
 module.exports = __toCommonJS(browserBackend_exports);
@@ -40,15 +41,6 @@ async function runBrowserBackendOnError(page, message) {
   const testInfo = (0, import_globals.currentTestInfo)();
   if (!testInfo || !testInfo._pauseOnError())
     return;
-  const browserContextFactory = {
-    createContext: async (clientInfo, abortSignal, toolName) => {
-      return {
-        browserContext: page.context(),
-        close: async () => {
-        }
-      };
-    }
-  };
   const config = {
     ...import_config.defaultConfig,
     capabilities: ["testing"]
@@ -62,9 +54,39 @@ ${snapshot}
 
 ### Task
 Try recovering from the error prior to continuing`;
-  await mcp.runOnPauseBackendLoop(new import_browserServerBackend.BrowserServerBackend(config, browserContextFactory), introMessage);
+  await mcp.runOnPauseBackendLoop(new import_browserServerBackend.BrowserServerBackend(config, identityFactory(page.context())), introMessage);
+}
+async function runBrowserBackendAtEnd(context) {
+  const testInfo = (0, import_globals.currentTestInfo)();
+  if (!testInfo || !testInfo._pauseAtEnd())
+    return;
+  const page = context.pages()[0];
+  if (!page)
+    return;
+  const snapshot = await page._snapshotForAI();
+  const introMessage = `### Paused at end of test. ready for interaction
+
+### Current page snapshot:
+${snapshot}`;
+  const config = {
+    ...import_config.defaultConfig,
+    capabilities: ["testing"]
+  };
+  await mcp.runOnPauseBackendLoop(new import_browserServerBackend.BrowserServerBackend(config, identityFactory(context)), introMessage);
+}
+function identityFactory(browserContext) {
+  return {
+    createContext: async (clientInfo, abortSignal, toolName) => {
+      return {
+        browserContext,
+        close: async () => {
+        }
+      };
+    }
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  runBrowserBackendAtEnd,
   runBrowserBackendOnError
 });

package/lib/mcp/test/testBackend.js

@@ -31,16 +31,35 @@ __export(testBackend_exports, {
   TestServerBackend: () => TestServerBackend
 });
 module.exports = __toCommonJS(testBackend_exports);
+var import_url = require("url");
 var mcp = __toESM(require("../sdk/exports"));
 var import_testContext = require("./testContext");
 var import_testTools = require("./testTools.js");
 var import_tools = require("../browser/tools");
+var import_configLoader = require("../../common/configLoader");
 class TestServerBackend {
-  constructor(resolvedLocation, options) {
+  constructor(configOption, options) {
     this.name = "Playwright";
     this.version = "0.0.1";
-    this._tools = [import_testTools.listTests, import_testTools.runTests, import_testTools.debugTest];
-    this._context = new import_testContext.TestContext(resolvedLocation, options);
+    this._tools = [import_testTools.listTests, import_testTools.runTests, import_testTools.debugTest, import_testTools.setupPage];
+    this._context = new import_testContext.TestContext(options);
+    this._configOption = configOption;
+  }
+  async initialize(server, clientVersion, roots) {
+    if (this._configOption) {
+      this._context.setConfigLocation((0, import_configLoader.resolveConfigLocation)(this._configOption));
+      return;
+    }
+    if (roots.length > 0) {
+      const firstRootUri = roots[0]?.uri;
+      const url = firstRootUri ? new URL(firstRootUri) : void 0;
+      const folder = url ? (0, import_url.fileURLToPath)(url) : void 0;
+      if (folder) {
+        this._context.setConfigLocation((0, import_configLoader.resolveConfigLocation)(folder));
+        return;
+      }
+    }
+    throw new Error("No config option or MCP root path provided");
   }
   async listTools() {
     return [

package/lib/mcp/test/testContext.js

@@ -23,10 +23,12 @@ __export(testContext_exports, {
 module.exports = __toCommonJS(testContext_exports);
 var import_testRunner = require("../../runner/testRunner");
 class TestContext {
-  constructor(configLocation, options) {
-    this.configLocation = configLocation;
+  constructor(options) {
     this.options = options;
   }
+  setConfigLocation(configLocation) {
+    this.configLocation = configLocation;
+  }
   async createTestRunner() {
     if (this._testRunner)
       await this._testRunner.stopTests();

package/lib/mcp/test/testTools.js

@@ -30,7 +30,8 @@ var testTools_exports = {};
 __export(testTools_exports, {
   debugTest: () => debugTest,
   listTests: () => listTests,
-  runTests: () => runTests
+  runTests: () => runTests,
+  setupPage: () => setupPage
 });
 module.exports = __toCommonJS(testTools_exports);
 var import_utils = require("playwright-core/lib/utils");
@@ -42,7 +43,7 @@ var import_testTool = require("./testTool");
 var import_streams = require("./streams");
 const listTests = (0, import_testTool.defineTestTool)({
   schema: {
-    name: "playwright_test_list_tests",
+    name: "test_list",
     title: "List tests",
     description: "List tests",
     inputSchema: import_bundle.z.object({}),
@@ -60,7 +61,7 @@ const listTests = (0, import_testTool.defineTestTool)({
 });
 const runTests = (0, import_testTool.defineTestTool)({
   schema: {
-    name: "playwright_test_run_tests",
+    name: "test_run",
     title: "Run tests",
     description: "Run tests",
     inputSchema: import_bundle.z.object({
@@ -89,7 +90,7 @@ const runTests = (0, import_testTool.defineTestTool)({
 });
 const debugTest = (0, import_testTool.defineTestTool)({
   schema: {
-    name: "playwright_test_debug_test",
+    name: "test_debug",
     title: "Debug single test",
     description: "Debug single test",
     inputSchema: import_bundle.z.object({
@@ -101,14 +102,7 @@ const debugTest = (0, import_testTool.defineTestTool)({
     type: "readOnly"
   },
   handle: async (context, params) => {
-    const stream = new import_streams.StringWriteStream();
-    const screen = {
-      ...import_base.terminalScreen,
-      isTTY: false,
-      colors: import_utils.noColors,
-      stdout: stream,
-      stderr: stream
-    };
+    const { screen, stream } = createScreen();
     const configDir = context.configLocation.configDir;
     const reporter = new import_list.default({ configDir, screen });
     const testRunner = await context.createTestRunner();
@@ -129,6 +123,35 @@ const debugTest = (0, import_testTool.defineTestTool)({
     };
   }
 });
+const setupPage = (0, import_testTool.defineTestTool)({
+  schema: {
+    name: "test_setup_page",
+    title: "Setup page",
+    description: "Runs a blank test to setup the page for interaction",
+    inputSchema: import_bundle.z.object({
+      testLocation: import_bundle.z.string().describe('Location of the blank test to use for setup. For example: "test/e2e/file.spec.ts:20"')
+    }),
+    type: "readOnly"
+  },
+  handle: async (context, params) => {
+    const { screen, stream } = createScreen();
+    const configDir = context.configLocation.configDir;
+    const reporter = new import_list.default({ configDir, screen });
+    const testRunner = await context.createTestRunner();
+    const result = await testRunner.runTests(reporter, {
+      headed: !context.options?.headless,
+      locations: [params.testLocation],
+      timeout: 0,
+      workers: 1,
+      pauseAtEnd: true
+    });
+    const text = stream.content();
+    return {
+      content: [{ type: "text", text }],
+      isError: result.status !== "passed"
+    };
+  }
+});
 function createScreen() {
   const stream = new import_streams.StringWriteStream();
   const screen = {
@@ -144,5 +167,6 @@ function createScreen() {
 0 && (module.exports = {
   debugTest,
   listTests,
-  runTests
+  runTests,
+  setupPage
 });

package/lib/program.js

@@ -49,6 +49,7 @@ var import_reporters = require("./runner/reporters");
 var import_exports = require("./mcp/sdk/exports");
 var import_testBackend = require("./mcp/test/testBackend");
 var import_program3 = require("./mcp/program");
+var import_watchdog = require("./mcp/browser/watchdog");
 var import_generateAgents = require("./agents/generateAgents");
 const packageJSON = require("../package.json");
 function addTestCommand(program3) {
@@ -157,12 +158,12 @@ function addTestMCPServerCommand(program3) {
   command.option("--host <host>", "host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.");
   command.option("--port <port>", "port to listen on for SSE transport.");
   command.action(async (options) => {
-    const resolvedLocation = (0, import_configLoader.resolveConfigLocation)(options.config);
+    (0, import_watchdog.setupExitWatchdog)();
     const backendFactory = {
       name: "Playwright Test Runner",
       nameInConfig: "playwright-test-runner",
       version: packageJSON.version,
-      create: () => new import_testBackend.TestServerBackend(resolvedLocation, { muteConsole: options.port === void 0, headless: options.headless })
+      create: () => new import_testBackend.TestServerBackend(options.config, { muteConsole: options.port === void 0, headless: options.headless })
     };
     const mdbUrl = await (0, import_exports.runMainBackend)(backendFactory, { port: options.port === void 0 ? void 0 : +options.port });
     if (mdbUrl)

package/lib/runner/dispatcher.js

@@ -158,7 +158,14 @@ class Dispatcher {
   _createWorker(testGroup, parallelIndex, loaderData) {
     const projectConfig = this._config.projects.find((p) => p.id === testGroup.projectId);
     const outputDir = projectConfig.project.outputDir;
-    const worker = new import_workerHost.WorkerHost(testGroup, parallelIndex, loaderData, this._extraEnvByProjectId.get(testGroup.projectId) || {}, outputDir, this._failureTracker.pauseOnError());
+    const worker = new import_workerHost.WorkerHost(testGroup, {
+      parallelIndex,
+      config: loaderData,
+      extraEnv: this._extraEnvByProjectId.get(testGroup.projectId) || {},
+      outputDir,
+      pauseOnError: this._failureTracker.pauseOnError(),
+      pauseAtEnd: this._failureTracker.pauseAtEnd()
+    });
     const handleOutput = (params) => {
       const chunk = chunkFromParams(params);
       if (worker.didFail()) {

package/lib/runner/failureTracker.js

@@ -27,6 +27,7 @@ class FailureTracker {
     this._failureCount = 0;
     this._hasWorkerErrors = false;
     this._pauseOnError = options?.pauseOnError ?? false;
+    this._pauseAtEnd = options?.pauseAtEnd ?? false;
   }
   onRootSuite(rootSuite) {
     this._rootSuite = rootSuite;
@@ -41,6 +42,9 @@ class FailureTracker {
   pauseOnError() {
     return this._pauseOnError;
   }
+  pauseAtEnd() {
+    return this._pauseAtEnd;
+  }
   hasReachedMaxFailures() {
     return this.maxFailures() > 0 && this._failureCount >= this.maxFailures();
   }

package/lib/runner/testRunner.js

@@ -71,6 +71,7 @@ class TestRunner extends import_events.default {
     });
   }
   async initialize(params) {
+    (0, import_utils.setPlaywrightTestProcessEnv)();
     this._watchTestDirs = !!params.watchTestDirs;
     this._populateDependenciesOnList = !!params.populateDependenciesOnList;
   }
@@ -270,7 +271,7 @@ class TestRunner extends import_events.default {
       (0, import_tasks.createLoadTask)("out-of-process", { filterOnly: true, failOnLoadErrors: false, doNotRunDepsOutsideProjectFilter: true }),
       ...(0, import_tasks.createRunTestsTasks)(config)
     ];
-    const testRun = new import_tasks.TestRun(config, reporter, { pauseOnError: params.pauseOnError });
+    const testRun = new import_tasks.TestRun(config, reporter, { pauseOnError: params.pauseOnError, pauseAtEnd: params.pauseAtEnd });
     const run = (0, import_tasks.runTasks)(testRun, tasks, 0, stop).then(async (status) => {
       this._testRun = void 0;
       return status;
@@ -352,6 +353,7 @@ async function resolveCtDirs(config) {
   };
 }
 async function runAllTestsWithConfig(config) {
+  (0, import_utils.setPlaywrightTestProcessEnv)();
   const listOnly = config.cliListOnly;
   (0, import_gitCommitInfoPlugin.addGitCommitInfoPlugin)(config);
   (0, import_webServerPlugin.webServerPluginsForConfig)(config).forEach((p) => config.plugins.push({ factory: p }));

package/lib/runner/workerHost.js

@@ -39,25 +39,26 @@ var import_ipc = require("../common/ipc");
 var import_folders = require("../isomorphic/folders");
 let lastWorkerIndex = 0;
 class WorkerHost extends import_processHost.ProcessHost {
-  constructor(testGroup, parallelIndex, config, extraEnv, outputDir, pauseOnError) {
+  constructor(testGroup, options) {
     const workerIndex = lastWorkerIndex++;
     super(require.resolve("../worker/workerMain.js"), `worker-${workerIndex}`, {
-      ...extraEnv,
+      ...options.extraEnv,
       FORCE_COLOR: "1",
       DEBUG_COLORS: process.env.DEBUG_COLORS === void 0 ? "1" : process.env.DEBUG_COLORS
     });
     this._didFail = false;
     this.workerIndex = workerIndex;
-    this.parallelIndex = parallelIndex;
+    this.parallelIndex = options.parallelIndex;
     this._hash = testGroup.workerHash;
     this._params = {
       workerIndex: this.workerIndex,
-      parallelIndex,
+      parallelIndex: options.parallelIndex,
       repeatEachIndex: testGroup.repeatEachIndex,
       projectId: testGroup.projectId,
-      config,
-      artifactsDir: import_path.default.join(outputDir, (0, import_folders.artifactsFolderName)(workerIndex)),
-      pauseOnError
+      config: options.config,
+      artifactsDir: import_path.default.join(options.outputDir, (0, import_folders.artifactsFolderName)(workerIndex)),
+      pauseOnError: options.pauseOnError,
+      pauseAtEnd: options.pauseAtEnd
     };
   }
   async start() {

package/lib/worker/testInfo.js

@@ -447,6 +447,9 @@ ${(0, import_utils.stringifyStackFrames)(step.boxedStack).join("\n")}`;
   _pauseOnError() {
     return this._workerParams.pauseOnError;
   }
+  _pauseAtEnd() {
+    return this._workerParams.pauseAtEnd;
+  }
 }
 class TestStepInfoImpl {
   constructor(testInfo, stepId, title, parentStep) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright",
-  "version": "1.56.0-alpha-2025-09-11",
+  "version": "1.56.0-alpha-2025-09-12",
   "description": "A high-level API to automate web browsers",
   "repository": {
     "type": "git",
@@ -64,7 +64,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "playwright-core": "1.56.0-alpha-2025-09-11"
+    "playwright-core": "1.56.0-alpha-2025-09-12"
   },
   "optionalDependencies": {
     "fsevents": "2.3.2"