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

package/lib/agents/agent.js

@@ -33,7 +33,7 @@ class Agent {
     const { clients, tools, callTool } = await this._initClients();
     const prompt = this.spec.description;
     try {
-      return await this.loop.run(`${prompt}
+      const { result } = await this.loop.run(`${prompt}
 
 Task:
 ${task}
@@ -45,6 +45,7 @@ ${JSON.stringify(params, null, 2)}`, {
         callTool,
         resultSchema: this.resultSchema
       });
+      return result;
     } finally {
       await this._disconnectFromServers(clients);
     }

package/lib/agents/playwright-test-planner.agent.md

@@ -17,6 +17,7 @@ tools:
   - playwright-test/browser_navigate_back
   - playwright-test/browser_network_requests
   - playwright-test/browser_press_key
+  - playwright-test/browser_run_code
   - playwright-test/browser_select_option
   - playwright-test/browser_snapshot
   - playwright-test/browser_take_screenshot

package/lib/index.js

@@ -164,7 +164,7 @@ const playwrightFixtures = {
     baseURL,
     contextOptions,
     serviceWorkers
-  }, use) => {
+  }, use, testInfo) => {
     const options = {};
     if (acceptDownloads !== void 0)
       options.acceptDownloads = acceptDownloads;
@@ -217,23 +217,21 @@ const playwrightFixtures = {
       ...options
     });
   }, { box: true }],
-  _setupContextOptions: [async ({ playwright, _combinedContextOptions, actionTimeout, navigationTimeout, testIdAttribute }, use, testInfo) => {
+  _setupContextOptions: [async ({ playwright, actionTimeout, navigationTimeout, testIdAttribute }, use, testInfo) => {
     if (testIdAttribute)
       playwrightLibrary.selectors.setTestIdAttribute(testIdAttribute);
     testInfo.snapshotSuffix = process.platform;
     if ((0, import_utils.debugMode)() === "inspector")
       testInfo._setDebugMode();
-    playwright._defaultContextOptions = _combinedContextOptions;
     playwright._defaultContextTimeout = actionTimeout || 0;
     playwright._defaultContextNavigationTimeout = navigationTimeout || 0;
     await use();
-    playwright._defaultContextOptions = void 0;
     playwright._defaultContextTimeout = void 0;
     playwright._defaultContextNavigationTimeout = void 0;
   }, { auto: "all-hooks-included", title: "context configuration", box: true }],
-  _setupArtifacts: [async ({ playwright, screenshot }, use, testInfo) => {
+  _setupArtifacts: [async ({ playwright, screenshot, _combinedContextOptions, agent }, use, testInfo) => {
     testInfo.setTimeout(testInfo.project.timeout);
-    const artifactsRecorder = new ArtifactsRecorder(playwright, tracing().artifactsDir(), screenshot);
+    const artifactsRecorder = new ArtifactsRecorder(playwright, tracing().artifactsDir(), screenshot, agent);
     await artifactsRecorder.willStartTest(testInfo);
     const tracingGroupSteps = [];
     const csiListener = {
@@ -279,20 +277,33 @@ const playwrightFixtures = {
         if (!keepTestTimeout)
           (0, import_globals.currentTestInfo)()?._setDebugMode();
       },
+      runBeforeCreateBrowserContext: async (options) => {
+        for (const [key, value] of Object.entries(_combinedContextOptions)) {
+          if (!(key in options))
+            options[key] = value;
+        }
+        await artifactsRecorder.willCreateBrowserContext(options);
+      },
+      runBeforeCreateRequestContext: async (options) => {
+        for (const [key, value] of Object.entries(_combinedContextOptions)) {
+          if (!(key in options))
+            options[key] = value;
+        }
+      },
       runAfterCreateBrowserContext: async (context) => {
-        await artifactsRecorder?.didCreateBrowserContext(context);
+        await artifactsRecorder.didCreateBrowserContext(context);
         const testInfo2 = (0, import_globals.currentTestInfo)();
         if (testInfo2)
           attachConnectedHeaderIfNeeded(testInfo2, context.browser());
       },
       runAfterCreateRequestContext: async (context) => {
-        await artifactsRecorder?.didCreateRequestContext(context);
+        await artifactsRecorder.didCreateRequestContext(context);
       },
       runBeforeCloseBrowserContext: async (context) => {
-        await artifactsRecorder?.willCloseBrowserContext(context);
+        await artifactsRecorder.willCloseBrowserContext(context);
       },
       runBeforeCloseRequestContext: async (context) => {
-        await artifactsRecorder?.willCloseRequestContext(context);
+        await artifactsRecorder.willCloseRequestContext(context);
       }
     };
     const clientInstrumentation = playwright._instrumentation;
@@ -551,9 +562,10 @@ class SnapshotRecorder {
   }
 }
 class ArtifactsRecorder {
-  constructor(playwright, artifactsDir, screenshot) {
+  constructor(playwright, artifactsDir, screenshot, agent) {
     this._playwright = playwright;
     this._artifactsDir = artifactsDir;
+    this._agent = agent;
     const screenshotOptions = typeof screenshot === "string" ? void 0 : screenshot;
     this._startedCollectingArtifacts = Symbol("startedCollectingArtifacts");
     this._screenshotRecorder = new SnapshotRecorder(this, normalizeScreenshotMode(screenshot), "screenshot", "image/png", ".png", async (page, path2) => {
@@ -573,10 +585,14 @@ class ArtifactsRecorder {
   async didCreateBrowserContext(context) {
     await this._startTraceChunkOnContextCreation(context, context.tracing);
   }
+  async willCreateBrowserContext(options) {
+    await this._cloneAgentCache(options);
+  }
   async willCloseBrowserContext(context) {
     await this._stopTracing(context, context.tracing);
     await this._screenshotRecorder.captureTemporary(context);
     await this._takePageSnapshot(context);
+    await this._upstreamAgentCache(context);
   }
   async _takePageSnapshot(context) {
     if (process.env.PLAYWRIGHT_NO_COPY_PROMPT)
@@ -595,6 +611,21 @@ class ArtifactsRecorder {
     } catch {
     }
   }
+  async _cloneAgentCache(options) {
+    if (!this._agent || this._agent.cacheMode === "ignore")
+      return;
+    if (!this._agent.cacheFile && !this._agent.cachePathTemplate)
+      return;
+    const cacheFile = this._agent.cacheFile ?? this._testInfo._applyPathTemplate(this._agent.cachePathTemplate, "cache", ".json");
+    const workerFile = await this._testInfo._cloneStorage(cacheFile);
+    if (this._agent && workerFile)
+      options.agent = { ...this._agent, cacheFile: workerFile };
+  }
+  async _upstreamAgentCache(context) {
+    const agent = context._options.agent;
+    if (this._testInfo.status === "passed" && agent?.cacheFile)
+      await this._testInfo._upstreamStorage(agent.cacheFile);
+  }
   async didCreateRequestContext(context) {
     await this._startTraceChunkOnContextCreation(context, context._tracing);
   }

package/lib/isomorphic/teleReceiver.js

@@ -58,6 +58,10 @@ class TeleReporterReceiver {
       this._onTestBegin(params.testId, params.result);
       return;
     }
+    if (method === "onTestPaused") {
+      this._onTestPaused(params.testId, params.resultId, params.stepId, params.errors);
+      return;
+    }
     if (method === "onTestEnd") {
       this._onTestEnd(params.test, params.result);
       return;
@@ -116,6 +120,14 @@ class TeleReporterReceiver {
     testResult.setStartTimeNumber(payload.startTime);
     this._reporter.onTestBegin?.(test, testResult);
   }
+  _onTestPaused(testId, resultId, stepId, errors) {
+    const test = this._tests.get(testId);
+    const result = test.results.find((r) => r._id === resultId);
+    const step = result._stepMap.get(stepId);
+    result.errors.push(...errors);
+    result.error = result.errors[0];
+    void this._reporter.onTestPaused?.(test, result, step);
+  }
   _onTestEnd(testEndPayload, payload) {
     const test = this._tests.get(testEndPayload.testId);
     test.timeout = testEndPayload.timeout;
@@ -123,8 +135,8 @@ class TeleReporterReceiver {
     const result = test.results.find((r) => r._id === payload.id);
     result.duration = payload.duration;
     result.status = payload.status;
-    result.errors = payload.errors;
-    result.error = result.errors?.[0];
+    result.errors.push(...payload.errors ?? []);
+    result.error = result.errors[0];
     if (!!payload.attachments)
       result.attachments = this._parseAttachments(payload.attachments);
     if (payload.annotations) {

package/lib/mcp/browser/config.js

@@ -272,6 +272,7 @@ function outputDir(config, clientInfo) {
 }
 async function outputFile(config, clientInfo, fileName, options) {
   const file = await resolveFile(config, clientInfo, fileName, options);
+  await import_fs.default.promises.mkdir(import_path.default.dirname(file), { recursive: true });
   (0, import_utilsBundle.debug)("pw:mcp:file")(options.reason, file);
   return file;
 }

package/lib/mcp/browser/context.js

@@ -33,7 +33,6 @@ __export(context_exports, {
 });
 module.exports = __toCommonJS(context_exports);
 var import_fs = __toESM(require("fs"));
-var import_path = __toESM(require("path"));
 var import_utilsBundle = require("playwright-core/lib/utilsBundle");
 var import_playwright_core = require("playwright-core");
 var import_log = require("../log");
@@ -143,7 +142,6 @@ class Context {
       await close(async () => {
         for (const video of videos) {
           const name = await this.outputFile((0, import_utils.dateAsFileName)("webm"), { origin: "code", reason: "Saving video" });
-          await import_fs.default.promises.mkdir(import_path.default.dirname(name), { recursive: true });
           const p = await video.path();
           if (import_fs.default.existsSync(p)) {
             try {

package/lib/mcp/browser/response.js

@@ -32,8 +32,10 @@ class Response {
     this._result = [];
     this._code = [];
     this._images = [];
+    this._files = [];
     this._includeSnapshot = "none";
     this._includeTabs = false;
+    this._includeMetaOnly = false;
     this._context = context;
     this.toolName = toolName;
     this.toolArgs = toolArgs;
@@ -63,6 +65,11 @@ class Response {
   images() {
     return this._images;
   }
+  async addFile(fileName, options) {
+    const resolvedFile = await this._context.outputFile(fileName, options);
+    this._files.push({ fileName: resolvedFile, title: options.reason });
+    return resolvedFile;
+  }
   setIncludeSnapshot() {
     this._includeSnapshot = this._context.config.snapshot.mode;
   }
@@ -75,6 +82,9 @@ class Response {
   setIncludeModalStates(modalStates) {
     this._includeModalStates = modalStates;
   }
+  setIncludeMetaOnly() {
+    this._includeMetaOnly = true;
+  }
   async finish() {
     if (this._includeSnapshot !== "none" && this._context.currentTab())
       this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
@@ -90,9 +100,9 @@ class Response {
   }
   logEnd() {
     if (requestDebug.enabled)
-      requestDebug(this.serialize({ omitSnapshot: true, omitBlobs: true }));
+      requestDebug(this.serialize());
   }
-  serialize(options = {}) {
+  render() {
     const renderedResponse = new RenderedResponse();
     if (this._result.length)
       renderedResponse.results.push(...this._result);
@@ -107,21 +117,34 @@ class Response {
       const modalStatesMarkdown = (0, import_tab.renderModalStates)(this._tabSnapshot.modalStates);
       renderedResponse.states.modal = modalStatesMarkdown.join("\n");
     } else if (this._tabSnapshot) {
-      const includeSnapshot = options.omitSnapshot ? "none" : this._includeSnapshot;
-      renderTabSnapshot(this._tabSnapshot, includeSnapshot, renderedResponse);
+      renderTabSnapshot(this._tabSnapshot, this._includeSnapshot, renderedResponse);
     } else if (this._includeModalStates) {
       const modalStatesMarkdown = (0, import_tab.renderModalStates)(this._includeModalStates);
       renderedResponse.states.modal = modalStatesMarkdown.join("\n");
     }
-    const redactedResponse = this._context.config.secrets ? renderedResponse.redact(this._context.config.secrets) : renderedResponse;
+    if (this._files.length) {
+      const lines = [];
+      for (const file of this._files)
+        lines.push(`- [${file.title}](${file.fileName})`);
+      renderedResponse.updates.push({ category: "files", content: lines.join("\n") });
+    }
+    return this._context.config.secrets ? renderedResponse.redact(this._context.config.secrets) : renderedResponse;
+  }
+  serialize(options = {}) {
+    const renderedResponse = this.render();
     const includeMeta = options._meta && "dev.lowire/history" in options._meta && "dev.lowire/state" in options._meta;
-    const _meta = includeMeta ? redactedResponse.asMeta() : void 0;
+    const _meta = includeMeta ? renderedResponse.asMeta() : void 0;
     const content = [
-      { type: "text", text: redactedResponse.asText() }
+      {
+        type: "text",
+        text: renderedResponse.asText(this._includeMetaOnly ? { categories: ["files"] } : void 0)
+      }
     ];
+    if (this._includeMetaOnly)
+      return { _meta, content, isError: this._isError };
     if (this._context.config.imageResponses !== "omit") {
       for (const image of this._images)
-        content.push({ type: "image", data: options.omitBlobs ? "<blob>" : image.data.toString("base64"), mimeType: image.contentType });
+        content.push({ type: "image", data: image.data.toString("base64"), mimeType: image.contentType });
     }
     return {
       _meta,
@@ -195,7 +218,7 @@ class RenderedResponse {
       this.code = copy.code;
     }
   }
-  asText() {
+  asText(filter) {
     const text = [];
     if (this.results.length)
       text.push(`### Result
@@ -206,6 +229,8 @@ ${this.results.join("\n")}
 ${this.code.join("\n")}
 `);
     for (const { category, content } of this.updates) {
+      if (filter && !filter.categories.includes(category))
+        continue;
       if (!content.trim())
         continue;
       switch (category) {
@@ -217,11 +242,18 @@ ${content}
         case "downloads":
           text.push(`### Downloads
 ${content}
+`);
+          break;
+        case "files":
+          text.push(`### Files
+${content}
 `);
           break;
       }
     }
     for (const [category, value] of Object.entries(this.states)) {
+      if (filter && !filter.categories.includes(category))
+        continue;
       if (!value.trim())
         continue;
       switch (category) {
@@ -291,6 +323,7 @@ function parseResponse(response) {
   const consoleMessages = sections.get("New console messages");
   const modalState = sections.get("Modal state");
   const downloads = sections.get("Downloads");
+  const files = sections.get("Files");
   const codeNoFrame = code?.replace(/^```js\n/, "").replace(/\n```$/, "");
   const isError = response.isError;
   const attachments = response.content.slice(1);
@@ -302,6 +335,7 @@ function parseResponse(response) {
     consoleMessages,
     modalState,
     downloads,
+    files,
     isError,
     attachments,
     _meta: response._meta

package/lib/mcp/browser/tools/pdf.js

@@ -48,9 +48,8 @@ const pdf = (0, import_tool.defineTabTool)({
     type: "readOnly"
   },
   handle: async (tab, params, response) => {
-    const fileName = await tab.context.outputFile(params.filename ?? (0, import_utils.dateAsFileName)("pdf"), { origin: "llm", reason: "Saving PDF" });
+    const fileName = await response.addFile(params.filename ?? (0, import_utils.dateAsFileName)("pdf"), { origin: "llm", reason: "Page saved as PDF" });
     response.addCode(`await page.pdf(${javascript.formatObject({ path: fileName })});`);
-    response.addResult(`Saved page as ${fileName}`);
     await tab.page.pdf({ path: fileName });
   }
 });

package/lib/mcp/browser/tools/runCode.js

@@ -36,7 +36,7 @@ var import_utils = require("playwright-core/lib/utils");
 var import_mcpBundle = require("playwright-core/lib/mcpBundle");
 var import_tool = require("./tool");
 const codeSchema = import_mcpBundle.z.object({
-  code: import_mcpBundle.z.string().describe(`Playwright code snippet to run. The snippet should access the \`page\` object to interact with the page. Can make multiple statements. For example: \`await page.getByRole('button', { name: 'Submit' }).click();\``)
+  code: import_mcpBundle.z.string().describe(`A JavaScript function containing Playwright code to execute. It will be invoked with a single argument, page, which you can use for any page interaction. For example: \`async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }\``)
 });
 const runCode = (0, import_tool.defineTabTool)({
   capability: "core",
@@ -49,7 +49,7 @@ const runCode = (0, import_tool.defineTabTool)({
   },
   handle: async (tab, params, response) => {
     response.setIncludeSnapshot();
-    response.addCode(params.code);
+    response.addCode(`await (${params.code})(page);`);
     const __end__ = new import_utils.ManualPromise();
     const context = {
       page: tab.page,
@@ -59,14 +59,16 @@ const runCode = (0, import_tool.defineTabTool)({
     await tab.waitForCompletion(async () => {
       const snippet = `(async () => {
         try {
-          ${params.code};
-          __end__.resolve();
+          const result = await (${params.code})(page);
+          __end__.resolve(JSON.stringify(result));
         } catch (e) {
           __end__.reject(e);
         }
       })()`;
-      import_vm.default.runInContext(snippet, context);
-      await __end__;
+      await import_vm.default.runInContext(snippet, context);
+      const result = await __end__;
+      if (typeof result === "string")
+        response.addResult(result);
     });
   }
 });

package/lib/mcp/browser/tools/screenshot.js

@@ -61,7 +61,6 @@ const screenshot = (0, import_tool.defineTabTool)({
     if (params.fullPage && params.ref)
       throw new Error("fullPage cannot be used with element screenshots.");
     const fileType = params.type || "png";
-    const fileName = await tab.context.outputFile(params.filename || (0, import_utils2.dateAsFileName)(fileType), { origin: "llm", reason: "Saving screenshot" });
     const options = {
       type: fileType,
       quality: fileType === "png" ? void 0 : 90,
@@ -70,6 +69,7 @@ const screenshot = (0, import_tool.defineTabTool)({
     };
     const isElementScreenshot = params.element && params.ref;
     const screenshotTarget = isElementScreenshot ? params.element : params.fullPage ? "full page" : "viewport";
+    const fileName = await response.addFile(params.filename || (0, import_utils2.dateAsFileName)(fileType), { origin: "llm", reason: `Screenshot of ${screenshotTarget}` });
     response.addCode(`// Screenshot ${screenshotTarget} and save it as ${fileName}`);
     const ref = params.ref ? await tab.refLocator({ element: params.element || "", ref: params.ref }) : null;
     if (ref)
@@ -79,7 +79,6 @@ const screenshot = (0, import_tool.defineTabTool)({
     const buffer = ref ? await ref.locator.screenshot(options) : await tab.page.screenshot(options);
     await (0, import_utils.mkdirIfNeeded)(fileName);
     await import_fs.default.promises.writeFile(fileName, buffer);
-    response.addResult(`Took the ${screenshotTarget} screenshot and saved it as ${fileName}`);
     response.addImage({
       contentType: fileType === "png" ? "image/png" : "image/jpeg",
       data: scaleImageToFitMessage(buffer, fileType)

package/lib/mcp/browser/tools/snapshot.js

@@ -32,6 +32,7 @@ __export(snapshot_exports, {
   elementSchema: () => elementSchema
 });
 module.exports = __toCommonJS(snapshot_exports);
+var import_fs = __toESM(require("fs"));
 var import_mcpBundle = require("playwright-core/lib/mcpBundle");
 var import_tool = require("./tool");
 var javascript = __toESM(require("../codegen"));
@@ -41,12 +42,20 @@ const snapshot = (0, import_tool.defineTool)({
     name: "browser_snapshot",
     title: "Page snapshot",
     description: "Capture accessibility snapshot of the current page, this is better than screenshot",
-    inputSchema: import_mcpBundle.z.object({}),
+    inputSchema: import_mcpBundle.z.object({
+      filename: import_mcpBundle.z.string().optional().describe("Save snapshot to markdown file instead of returning it in the response.")
+    }),
     type: "readOnly"
   },
   handle: async (context, params, response) => {
     await context.ensureTab();
     response.setIncludeFullSnapshot();
+    if (params.filename) {
+      const renderedResponse = response.render();
+      const fileName = await response.addFile(params.filename, { origin: "llm", reason: "Saved snapshot" });
+      await import_fs.default.promises.writeFile(fileName, renderedResponse.asText());
+      response.setIncludeMetaOnly();
+    }
   }
 });
 const elementSchema = import_mcpBundle.z.object({

package/lib/mcp/browser/tools/utils.js

@@ -24,55 +24,39 @@ __export(utils_exports, {
 });
 module.exports = __toCommonJS(utils_exports);
 async function waitForCompletion(tab, callback) {
-  const requests = /* @__PURE__ */ new Set();
-  let frameNavigated = false;
-  let waitCallback = () => {
-  };
-  const waitBarrier = new Promise((f) => {
-    waitCallback = f;
-  });
-  const responseListener = (request) => {
-    requests.delete(request);
-    if (!requests.size)
-      waitCallback();
-  };
-  const requestListener = (request) => {
-    requests.add(request);
-    void request.response().then(() => responseListener(request)).catch(() => {
-    });
-  };
-  const frameNavigateListener = (frame) => {
-    if (frame.parentFrame())
-      return;
-    frameNavigated = true;
-    dispose();
-    clearTimeout(timeout);
-    void tab.waitForLoadState("load").then(waitCallback);
-  };
-  const onTimeout = () => {
-    dispose();
-    waitCallback();
-  };
-  tab.page.on("request", requestListener);
-  tab.page.on("requestfailed", responseListener);
-  tab.page.on("framenavigated", frameNavigateListener);
-  const timeout = setTimeout(onTimeout, 1e4);
-  const dispose = () => {
+  const requests = [];
+  const requestListener = (request) => requests.push(request);
+  const disposeListeners = () => {
     tab.page.off("request", requestListener);
-    tab.page.off("requestfailed", responseListener);
-    tab.page.off("framenavigated", frameNavigateListener);
-    clearTimeout(timeout);
   };
+  tab.page.on("request", requestListener);
+  let result;
   try {
-    const result = await callback();
-    if (!requests.size && !frameNavigated)
-      waitCallback();
-    await waitBarrier;
-    await tab.waitForTimeout(1e3);
-    return result;
+    result = await callback();
+    await tab.waitForTimeout(500);
   } finally {
-    dispose();
+    disposeListeners();
+  }
+  const requestedNavigation = requests.some((request) => request.isNavigationRequest());
+  if (requestedNavigation) {
+    await tab.page.mainFrame().waitForLoadState("load", { timeout: 1e4 }).catch(() => {
+    });
+    return result;
+  }
+  const promises = [];
+  for (const request of requests) {
+    if (["document", "stylesheet", "script", "xhr", "fetch"].includes(request.resourceType()))
+      promises.push(request.response().then((r) => r?.finished()).catch(() => {
+      }));
+    else
+      promises.push(request.response().catch(() => {
+      }));
   }
+  const timeout = new Promise((resolve) => setTimeout(resolve, 5e3));
+  await Promise.race([Promise.all(promises), timeout]);
+  if (requests.length)
+    await tab.waitForTimeout(500);
+  return result;
 }
 async function callOnPageNoTrace(page, callback) {
   return await page._wrapApiCall(() => callback(page), { internal: true });

package/lib/reporters/blob.js

@@ -68,6 +68,9 @@ class BlobReporter extends import_teleEmitter.TeleReporterEmitter {
     this._config = config;
     super.onConfigure(config);
   }
+  async onTestPaused(test, result, step) {
+    return { action: void 0 };
+  }
   async onEnd(result) {
     await super.onEnd(result);
     const zipFileName = await this._prepareOutputFile();

package/lib/reporters/internalReporter.js

@@ -66,6 +66,12 @@ class InternalReporter {
   onStdErr(chunk, test, result) {
     this._reporter.onStdErr?.(chunk, test, result);
   }
+  async onTestPaused(test, result, step) {
+    this._addSnippetToTestErrors(test, result);
+    if (step)
+      this._addSnippetToStepError(test, step);
+    return await this._reporter.onTestPaused?.(test, result, step) ?? { action: void 0 };
+  }
   onTestEnd(test, result) {
     this._addSnippetToTestErrors(test, result);
     this._reporter.onTestEnd?.(test, result);
@@ -112,6 +118,8 @@ function addLocationAndSnippetToError(config, error, file) {
   const location = error.location;
   if (!location)
     return;
+  if (!!error.snippet)
+    return;
   try {
     const tokens = [];
     const source = import_fs.default.readFileSync(location.file, "utf8");

package/lib/reporters/multiplexer.js

@@ -48,6 +48,14 @@ class Multiplexer {
     for (const reporter of this._reporters)
       wrap(() => reporter.onStdErr?.(chunk, test, result));
   }
+  async onTestPaused(test, result, step) {
+    for (const reporter of this._reporters) {
+      const disposition = await wrapAsync(() => reporter.onTestPaused?.(test, result, step));
+      if (disposition?.action)
+        return disposition;
+    }
+    return { action: void 0 };
+  }
   onTestEnd(test, result) {
     for (const reporter of this._reporters)
       wrap(() => reporter.onTestEnd?.(test, result));

package/lib/reporters/teleEmitter.js

@@ -37,7 +37,8 @@ var import_teleReceiver = require("../isomorphic/teleReceiver");
 class TeleReporterEmitter {
   constructor(messageSink, options = {}) {
     this._resultKnownAttachmentCounts = /* @__PURE__ */ new Map();
-    // In case there is blob reporter and UI mode, make sure one does override
+    this._resultKnownErrorCounts = /* @__PURE__ */ new Map();
+    // In case there is blob reporter and UI mode, make sure one doesn't override
     // the id assigned by the other.
     this._idSymbol = Symbol("id");
     this._messageSink = messageSink;
@@ -66,6 +67,21 @@ class TeleReporterEmitter {
       }
     });
   }
+  async onTestPaused(test, result, step) {
+    const resultId = result[this._idSymbol];
+    const stepId = step[this._idSymbol];
+    this._resultKnownErrorCounts.set(resultId, result.errors.length);
+    this._messageSink({
+      method: "onTestPaused",
+      params: {
+        testId: test.id,
+        resultId,
+        stepId,
+        errors: result.errors
+      }
+    });
+    return { action: void 0 };
+  }
   onTestEnd(test, result) {
     const testEnd = {
       testId: test.id,
@@ -81,7 +97,9 @@ class TeleReporterEmitter {
         result: this._serializeResultEnd(result)
       }
     });
-    this._resultKnownAttachmentCounts.delete(result[this._idSymbol]);
+    const resultId = result[this._idSymbol];
+    this._resultKnownAttachmentCounts.delete(resultId);
+    this._resultKnownErrorCounts.delete(resultId);
   }
   onStepBegin(test, result, step) {
     step[this._idSymbol] = (0, import_utils.createGuid)();
@@ -221,11 +239,12 @@ class TeleReporterEmitter {
     };
   }
   _serializeResultEnd(result) {
+    const id = result[this._idSymbol];
     return {
-      id: result[this._idSymbol],
+      id,
       duration: result.duration,
       status: result.status,
-      errors: result.errors,
+      errors: this._resultKnownErrorCounts.has(id) ? result.errors.slice(this._resultKnownAttachmentCounts.get(id)) : result.errors,
       annotations: result.annotations?.length ? this._relativeAnnotationLocations(result.annotations) : void 0
     };
   }

package/lib/runner/dispatcher.js

@@ -28,6 +28,7 @@ var import_workerHost = require("./workerHost");
 var import_ipc = require("../common/ipc");
 var import_internalReporter = require("../reporters/internalReporter");
 var import_util = require("../util");
+var import_storage = require("./storage");
 class Dispatcher {
   constructor(config, reporter, failureTracker) {
     this._workerSlots = [];
@@ -197,11 +198,11 @@ class Dispatcher {
       const producedEnv = this._producedEnvByProjectId.get(testGroup.projectId) || {};
       this._producedEnvByProjectId.set(testGroup.projectId, { ...producedEnv, ...worker.producedEnv() });
     });
-    worker.onRequest("setStorageValue", async (params) => {
-      this._setStorageValue(params.fileName, params.key, params.value);
+    worker.onRequest("cloneStorage", async (params) => {
+      return await import_storage.Storage.clone(params.storageFile, worker.artifactsDir());
     });
-    worker.onRequest("getStorageValue", async (params) => {
-      return this._getStorageValue(params.fileName, params.key);
+    worker.onRequest("upstreamStorage", async (params) => {
+      await import_storage.Storage.upstream(params.workerFile);
     });
     return worker;
   }
@@ -215,11 +216,6 @@ class Dispatcher {
     await Promise.all(this._workerSlots.map(({ worker }) => worker?.stop()));
     this._checkFinished();
   }
-  _setStorageValue(fileName, key, value) {
-  }
-  _getStorageValue(fileName, key) {
-    return {};
-  }
 }
 class JobDispatcher {
   constructor(job, config, reporter, failureTracker, stopCallback) {
@@ -469,11 +465,18 @@ class JobDispatcher {
     ];
   }
   _onTestPaused(worker, params) {
+    const data = this._dataByTestId.get(params.testId);
+    if (!data)
+      return;
+    const { result, test, steps } = data;
+    const step = steps.get(params.stepId);
+    if (!step)
+      return;
     const sendMessage = async (message) => {
       try {
         if (this.jobResult.isDone())
           throw new Error("Test has already stopped");
-        const response = await worker.sendCustomMessage({ testId: params.testId, request: message.request });
+        const response = await worker.sendCustomMessage({ testId: test.id, request: message.request });
         if (response.error)
           (0, import_internalReporter.addLocationAndSnippetToError)(this._config.config, response.error);
         return response;
@@ -483,8 +486,11 @@ class JobDispatcher {
         return { response: void 0, error };
       }
     };
-    for (const error of params.errors)
-      (0, import_internalReporter.addLocationAndSnippetToError)(this._config.config, error);
+    result.errors = params.errors;
+    result.error = result.errors[0];
+    void this._reporter.onTestPaused?.(test, result, step).then((params2) => {
+      worker.sendResume(params2);
+    });
     this._failureTracker.onTestPaused?.({ ...params, sendMessage });
   }
   skipWholeJob() {

package/lib/runner/storage.js

@@ -0,0 +1,105 @@
+"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 storage_exports = {};
+__export(storage_exports, {
+  Storage: () => Storage
+});
+module.exports = __toCommonJS(storage_exports);
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var import_utils = require("playwright-core/lib/utils");
+class Storage {
+  constructor(fileName) {
+    this._writeChain = Promise.resolve();
+    this._fileName = fileName;
+  }
+  static {
+    this._storages = /* @__PURE__ */ new Map();
+  }
+  static {
+    this._workerFiles = /* @__PURE__ */ new Map();
+  }
+  static async clone(storageFile, artifactsDir) {
+    const workerFile = await this._storage(storageFile)._clone(artifactsDir);
+    const stat = await import_fs.default.promises.stat(workerFile);
+    const lastModified = stat.mtime.getTime();
+    Storage._workerFiles.set(workerFile, { storageFile, lastModified });
+    return workerFile;
+  }
+  static async upstream(workerFile) {
+    const entry = Storage._workerFiles.get(workerFile);
+    if (!entry)
+      return;
+    const { storageFile, lastModified } = entry;
+    const stat = await import_fs.default.promises.stat(workerFile);
+    const newLastModified = stat.mtime.getTime();
+    if (lastModified !== newLastModified)
+      await this._storage(storageFile)._upstream(workerFile);
+    Storage._workerFiles.delete(workerFile);
+  }
+  static _storage(fileName) {
+    if (!Storage._storages.has(fileName))
+      Storage._storages.set(fileName, new Storage(fileName));
+    return Storage._storages.get(fileName);
+  }
+  async _clone(artifactsDir) {
+    const entries = await this._load();
+    const workerFile = import_path.default.join(artifactsDir, `pw-storage-${(0, import_utils.createGuid)()}.json`);
+    await import_fs.default.promises.writeFile(workerFile, JSON.stringify(entries, null, 2)).catch(() => {
+    });
+    return workerFile;
+  }
+  async _upstream(workerFile) {
+    const entries = await this._load();
+    const newEntries = await import_fs.default.promises.readFile(workerFile, "utf8").then(JSON.parse).catch(() => ({}));
+    for (const [key, newValue] of Object.entries(newEntries)) {
+      const existing = entries[key];
+      if (!existing || existing.timestamp < newValue.timestamp)
+        entries[key] = newValue;
+    }
+    await this._writeFile(entries);
+  }
+  async _load() {
+    if (!this._entriesPromise)
+      this._entriesPromise = import_fs.default.promises.readFile(this._fileName, "utf8").then(JSON.parse).catch(() => ({}));
+    return this._entriesPromise;
+  }
+  _writeFile(entries) {
+    this._writeChain = this._writeChain.then(() => import_fs.default.promises.writeFile(this._fileName, JSON.stringify(entries, null, 2))).catch(() => {
+    });
+    return this._writeChain;
+  }
+  async flush() {
+    await this._writeChain;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Storage
+});

package/lib/runner/testRunner.js

@@ -383,7 +383,8 @@ async function runAllTestsWithConfig(config) {
     (0, import_tasks.createLoadTask)("in-process", { filterOnly: true, failOnLoadErrors: true }),
     ...(0, import_tasks.createRunTestsTasks)(config)
   ];
-  const status = await (0, import_tasks.runTasks)(new import_tasks.TestRun(config, reporter), tasks, config.config.globalTimeout);
+  const testRun = new import_tasks.TestRun(config, reporter, { pauseAtEnd: config.configCLIOverrides.debug, pauseOnError: config.configCLIOverrides.debug });
+  const status = await (0, import_tasks.runTasks)(testRun, tasks, config.config.globalTimeout);
   await new Promise((resolve) => process.stdout.write("", () => resolve()));
   await new Promise((resolve) => process.stderr.write("", () => resolve()));
   return status;

package/lib/runner/workerHost.js

@@ -61,6 +61,9 @@ class WorkerHost extends import_processHost.ProcessHost {
       pauseAtEnd: options.pauseAtEnd
     };
   }
+  artifactsDir() {
+    return this._params.artifactsDir;
+  }
   async start() {
     await import_fs.default.promises.mkdir(this._params.artifactsDir, { recursive: true });
     return await this.startRunner(this._params, {
@@ -82,6 +85,9 @@ class WorkerHost extends import_processHost.ProcessHost {
   async sendCustomMessage(payload) {
     return await this.sendMessage({ method: "customMessage", params: payload });
   }
+  sendResume(payload) {
+    this.sendMessageNoReply({ method: "resume", params: payload });
+  }
   hash() {
     return this._hash;
   }

package/lib/transform/babelHighlightUtils.js

@@ -0,0 +1,63 @@
+"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 babelHighlightUtils_exports = {};
+__export(babelHighlightUtils_exports, {
+  findTestEndLocation: () => findTestEndLocation
+});
+module.exports = __toCommonJS(babelHighlightUtils_exports);
+var import_path = __toESM(require("path"));
+var import_babelBundle = require("./babelBundle");
+function containsLocation(range, location) {
+  if (location.line < range.start.line || location.line > range.end.line)
+    return false;
+  if (location.line === range.start.line && location.column < range.start.column)
+    return false;
+  if (location.line === range.end.line && location.column > range.end.column)
+    return false;
+  return true;
+}
+function findTestEndLocation(text, testStartLocation) {
+  const ast = (0, import_babelBundle.babelParse)(text, import_path.default.basename(testStartLocation.file), false);
+  let result;
+  (0, import_babelBundle.traverse)(ast, {
+    enter(path2) {
+      if (import_babelBundle.types.isCallExpression(path2.node) && path2.node.loc && containsLocation(path2.node.loc, testStartLocation)) {
+        const callNode = path2.node;
+        const funcNode = callNode.arguments[callNode.arguments.length - 1];
+        if (callNode.arguments.length >= 2 && import_babelBundle.types.isFunction(funcNode) && funcNode.body.loc)
+          result = { file: testStartLocation.file, ...funcNode.body.loc.end };
+      }
+    }
+  });
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findTestEndLocation
+});

package/lib/worker/testInfo.js

@@ -42,6 +42,7 @@ var import_util = require("../util");
 var import_testTracing = require("./testTracing");
 var import_util2 = require("./util");
 var import_transform = require("../transform/transform");
+var import_babelHighlightUtils = require("../transform/babelHighlightUtils");
 class TestInfoImpl {
   constructor(configInternal, projectInternal, workerParams, test, retry, callbacks) {
     this._snapshotNames = { lastAnonymousSnapshotIndex: 0, lastNamedSnapshotIndex: {} };
@@ -335,11 +336,33 @@ ${(0, import_utils.stringifyStackFrames)(step.boxedStack).join("\n")}`;
   async _didFinishTestFunction() {
     const shouldPause = this._workerParams.pauseAtEnd && !this._isFailure() || this._workerParams.pauseOnError && this._isFailure();
     if (shouldPause) {
-      this._callbacks.onTestPaused?.({ testId: this.testId, errors: this._isFailure() ? this.errors : [] });
-      await this._interruptedPromise;
+      const location = (this._isFailure() ? this._errorLocation() : await this._testEndLocation()) ?? { file: this.file, line: this.line, column: this.column };
+      const step = this._addStep({ category: "hook", title: "Paused", location });
+      const result = await Promise.race([
+        this._callbacks.onTestPaused({ testId: this.testId, stepId: step.stepId, errors: this._isFailure() ? this.errors : [] }),
+        this._interruptedPromise.then(() => "interrupted")
+      ]);
+      step.complete({});
+      if (result !== "interrupted") {
+        if (result.action === "abort")
+          this._interrupt();
+        if (result.action === void 0)
+          await this._interruptedPromise;
+      }
     }
     await this._onDidFinishTestFunctionCallback?.();
   }
+  _errorLocation() {
+    if (this.error?.stack)
+      return (0, import_util.filteredStackTrace)(this.error.stack.split("\n"))[0];
+  }
+  async _testEndLocation() {
+    try {
+      const source = await import_fs.default.promises.readFile(this.file, "utf-8");
+      return (0, import_babelHighlightUtils.findTestEndLocation)(source, { file: this.file, line: this.line, column: this.column });
+    } catch {
+    }
+  }
   // ------------ TestInfo methods ------------
   async attach(name, options = {}) {
     const step = this._addStep({
@@ -422,10 +445,6 @@ ${(0, import_utils.stringifyStackFrames)(step.boxedStack).join("\n")}`;
       if (index > 1)
         relativeOutputPath = (0, import_util.addSuffixToFilePath)(relativeOutputPath, `-${index - 1}`);
     }
-    const absoluteSnapshotPath = this._applyPathTemplate(kind, subPath, ext);
-    return { absoluteSnapshotPath, relativeOutputPath };
-  }
-  _applyPathTemplate(kind, relativePath, ext) {
     const legacyTemplate = "{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{-snapshotSuffix}{ext}";
     let template;
     if (kind === "screenshot") {
@@ -436,12 +455,15 @@ ${(0, import_utils.stringifyStackFrames)(step.boxedStack).join("\n")}`;
     } else {
       template = this._projectInternal.snapshotPathTemplate || legacyTemplate;
     }
-    const dir = import_path.default.dirname(relativePath);
-    const name = import_path.default.basename(relativePath, ext);
+    const nameArgument = import_path.default.join(import_path.default.dirname(subPath), import_path.default.basename(subPath, ext));
+    const absoluteSnapshotPath = this._applyPathTemplate(template, nameArgument, ext);
+    return { absoluteSnapshotPath, relativeOutputPath };
+  }
+  _applyPathTemplate(template, nameArgument, ext) {
     const relativeTestFilePath = import_path.default.relative(this.project.testDir, this._requireFile);
     const parsedRelativeTestFilePath = import_path.default.parse(relativeTestFilePath);
     const projectNamePathSegment = (0, import_utils.sanitizeForFilePath)(this.project.name);
-    const snapshotPath = template.replace(/\{(.)?testDir\}/g, "$1" + this.project.testDir).replace(/\{(.)?snapshotDir\}/g, "$1" + this.project.snapshotDir).replace(/\{(.)?snapshotSuffix\}/g, this.snapshotSuffix ? "$1" + this.snapshotSuffix : "").replace(/\{(.)?testFileDir\}/g, "$1" + parsedRelativeTestFilePath.dir).replace(/\{(.)?platform\}/g, "$1" + process.platform).replace(/\{(.)?projectName\}/g, projectNamePathSegment ? "$1" + projectNamePathSegment : "").replace(/\{(.)?testName\}/g, "$1" + this._fsSanitizedTestName()).replace(/\{(.)?testFileName\}/g, "$1" + parsedRelativeTestFilePath.base).replace(/\{(.)?testFilePath\}/g, "$1" + relativeTestFilePath).replace(/\{(.)?arg\}/g, "$1" + import_path.default.join(dir, name)).replace(/\{(.)?ext\}/g, ext ? "$1" + ext : "");
+    const snapshotPath = template.replace(/\{(.)?testDir\}/g, "$1" + this.project.testDir).replace(/\{(.)?snapshotDir\}/g, "$1" + this.project.snapshotDir).replace(/\{(.)?snapshotSuffix\}/g, this.snapshotSuffix ? "$1" + this.snapshotSuffix : "").replace(/\{(.)?testFileDir\}/g, "$1" + parsedRelativeTestFilePath.dir).replace(/\{(.)?platform\}/g, "$1" + process.platform).replace(/\{(.)?projectName\}/g, projectNamePathSegment ? "$1" + projectNamePathSegment : "").replace(/\{(.)?testName\}/g, "$1" + this._fsSanitizedTestName()).replace(/\{(.)?testFileName\}/g, "$1" + parsedRelativeTestFilePath.base).replace(/\{(.)?testFilePath\}/g, "$1" + relativeTestFilePath).replace(/\{(.)?arg\}/g, "$1" + nameArgument).replace(/\{(.)?ext\}/g, ext ? "$1" + ext : "");
     return import_path.default.normalize(import_path.default.resolve(this._configInternal.configDir, snapshotPath));
   }
   snapshotPath(...args) {
@@ -459,11 +481,12 @@ ${(0, import_utils.stringifyStackFrames)(step.boxedStack).join("\n")}`;
   setTimeout(timeout) {
     this._timeoutManager.setTimeout(timeout);
   }
-  async _getStorageValue(fileName, key) {
-    return await this._callbacks.onGetStorageValue?.({ fileName, key }) ?? Promise.resolve(void 0);
+  async _cloneStorage(cacheFileTemplate) {
+    const storageFile = this._applyPathTemplate(cacheFileTemplate, "cache", ".json");
+    return await this._callbacks.onCloneStorage?.({ storageFile });
   }
-  _setStorageValue(fileName, key, value) {
-    this._callbacks.onSetStorageValue?.({ fileName, key, value });
+  async _upstreamStorage(workerFile) {
+    await this._callbacks.onUpstreamStorage?.({ workerFile });
   }
 }
 class TestStepInfoImpl {

package/lib/worker/workerMain.js

@@ -229,14 +229,21 @@ class WorkerMain extends import_process.ProcessRunner {
       return { response: {}, error: (0, import_util2.testInfoError)(error) };
     }
   }
+  resume(payload) {
+    this._resumePromise?.resolve(payload);
+  }
   async _runTest(test, retry, nextTest) {
     const testInfo = new import_testInfo.TestInfoImpl(this._config, this._project, this._params, test, retry, {
       onStepBegin: (payload) => this.dispatchEvent("stepBegin", payload),
       onStepEnd: (payload) => this.dispatchEvent("stepEnd", payload),
       onAttach: (payload) => this.dispatchEvent("attach", payload),
-      onTestPaused: (payload) => this.dispatchEvent("testPaused", payload),
-      onGetStorageValue: (payload) => this.sendRequest("getStorageValue", payload),
-      onSetStorageValue: (payload) => this.sendMessageNoReply("setStorageValue", payload)
+      onTestPaused: (payload) => {
+        this._resumePromise = new import_utils.ManualPromise();
+        this.dispatchEvent("testPaused", payload);
+        return this._resumePromise;
+      },
+      onCloneStorage: async (payload) => this.sendRequest("cloneStorage", payload),
+      onUpstreamStorage: (payload) => this.sendRequest("upstreamStorage", payload)
     });
     const processAnnotation = (annotation) => {
       testInfo.annotations.push(annotation);

package/package.json

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

package/types/test.d.ts

@@ -6644,7 +6644,7 @@ export type Fixtures<T extends {} = {}, W extends {} = {}, PT extends {} = {}, P
   [K in Exclude<keyof T, keyof PW | keyof PT>]?: TestFixtureValue<T[K], T & W & PT & PW> | [TestFixtureValue<T[K], T & W & PT & PW>, { scope?: 'test', auto?: boolean, option?: boolean, timeout?: number | undefined, title?: string, box?: boolean | 'self' }];
 };
 
-type Agent = Exclude<BrowserContextOptions['agent'], undefined> | undefined;
+type Agent = Exclude<BrowserContextOptions['agent'], undefined> & { cachePathTemplate?: string } | undefined;
 type BrowserName = 'chromium' | 'firefox' | 'webkit';
 type BrowserChannel = Exclude<LaunchOptions['channel'], undefined>;
 type ColorScheme = Exclude<BrowserContextOptions['colorScheme'], undefined>;