playwright 1.58.0-alpha-2025-12-10 → 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

@@ -212,37 +212,26 @@ const playwrightFixtures = {
       options.baseURL = baseURL;
     if (serviceWorkers !== void 0)
       options.serviceWorkers = serviceWorkers;
-    const workerFile = agent?.cacheFile && agent.cacheMode !== "ignore" ? await testInfo._cloneStorage(agent.cacheFile) : void 0;
-    if (agent && workerFile) {
-      options.agent = {
-        ...agent,
-        cacheFile: workerFile
-      };
-    }
     await use({
       ...contextOptions,
       ...options
     });
-    if (workerFile)
-      await testInfo._upstreamStorage(workerFile);
   }, { 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 = {
@@ -288,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;
@@ -560,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) => {
@@ -582,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)
@@ -604,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/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/worker/testInfo.js

@@ -445,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") {
@@ -459,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) {
@@ -482,7 +481,8 @@ ${(0, import_utils.stringifyStackFrames)(step.boxedStack).join("\n")}`;
   setTimeout(timeout) {
     this._timeoutManager.setTimeout(timeout);
   }
-  async _cloneStorage(storageFile) {
+  async _cloneStorage(cacheFileTemplate) {
+    const storageFile = this._applyPathTemplate(cacheFileTemplate, "cache", ".json");
     return await this._callbacks.onCloneStorage?.({ storageFile });
   }
   async _upstreamStorage(workerFile) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright",
-  "version": "1.58.0-alpha-2025-12-10",
+  "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-10"
+    "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>;