playwright 1.56.0-alpha-2025-09-21 → 1.56.0-alpha-2025-09-23

package/lib/mcp/browser/browserContextFactory.js

@@ -79,6 +79,7 @@ class BaseContextFactory {
     (0, import_log.testDebug)(`create browser context (${this._logName})`);
     const browser = await this._obtainBrowser(clientInfo);
     const browserContext = await this._doCreateContext(browser);
+    await addInitScript(browserContext, this.config.browser.initScript);
     return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
   }
   async _doCreateContext(browser) {
@@ -177,6 +178,7 @@ class PersistentContextFactory {
       };
       try {
         const browserContext = await browserType.launchPersistentContext(userDataDir, launchOptions);
+        await addInitScript(browserContext, this.config.browser.initScript);
         const close = () => this._closeBrowserContext(browserContext, userDataDir);
         return { browserContext, close };
       } catch (error) {
@@ -234,6 +236,10 @@ async function startTraceServer(config, tracesDir) {
 function createHash(data) {
   return import_crypto.default.createHash("sha256").update(data).digest("hex").slice(0, 7);
 }
+async function addInitScript(browserContext, initScript) {
+  for (const scriptPath of initScript ?? [])
+    await browserContext.addInitScript({ path: import_path.default.resolve(scriptPath) });
+}
 class SharedContextFactory {
   static create(config) {
     if (SharedContextFactory._instance)

package/lib/mcp/browser/config.js

@@ -45,6 +45,7 @@ var import_os = __toESM(require("os"));
 var import_path = __toESM(require("path"));
 var import_playwright_core = require("playwright-core");
 var import_utilsBundle = require("playwright-core/lib/utilsBundle");
+var import_util = require("../../util");
 var import_server = require("../sdk/server");
 const defaultConfig = {
   browser: {
@@ -80,8 +81,17 @@ async function resolveCLIConfig(cliOptions) {
   result = mergeConfig(result, configInFile);
   result = mergeConfig(result, envOverrides);
   result = mergeConfig(result, cliOverrides);
+  await validateConfig(result);
   return result;
 }
+async function validateConfig(config) {
+  if (config.browser.initScript) {
+    for (const script of config.browser.initScript) {
+      if (!await (0, import_util.fileExistsAsync)(script))
+        throw new Error(`Init script file does not exist: ${script}`);
+    }
+  }
+}
 function configFromCLIOptions(cliOptions) {
   let browserName;
   let channel;
@@ -150,7 +160,8 @@ function configFromCLIOptions(cliOptions) {
       launchOptions,
       contextOptions,
       cdpEndpoint: cliOptions.cdpEndpoint,
-      cdpHeaders: cliOptions.cdpHeader
+      cdpHeaders: cliOptions.cdpHeader,
+      initScript: cliOptions.initScript
     },
     server: {
       port: cliOptions.port,
@@ -190,6 +201,9 @@ function configFromEnv() {
   options.headless = envToBoolean(process.env.PLAYWRIGHT_MCP_HEADLESS);
   options.host = envToString(process.env.PLAYWRIGHT_MCP_HOST);
   options.ignoreHttpsErrors = envToBoolean(process.env.PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS);
+  const initScript = envToString(process.env.PLAYWRIGHT_MCP_INIT_SCRIPT);
+  if (initScript)
+    options.initScript = [initScript];
   options.isolated = envToBoolean(process.env.PLAYWRIGHT_MCP_ISOLATED);
   if (process.env.PLAYWRIGHT_MCP_IMAGE_RESPONSES === "omit")
     options.imageResponses = "omit";

package/lib/mcp/browser/response.js

@@ -27,7 +27,7 @@ class Response {
     this._result = [];
     this._code = [];
     this._images = [];
-    this._includeSnapshot = false;
+    this._includeSnapshot = "none";
     this._includeTabs = false;
     this._context = context;
     this.toolName = toolName;
@@ -58,14 +58,14 @@ class Response {
   images() {
     return this._images;
   }
-  setIncludeSnapshot() {
-    this._includeSnapshot = true;
+  setIncludeSnapshot(full) {
+    this._includeSnapshot = full ?? "partial";
   }
   setIncludeTabs() {
     this._includeTabs = true;
   }
   async finish() {
-    if (this._includeSnapshot && this._context.currentTab())
+    if (this._includeSnapshot !== "none" && this._context.currentTab())
       this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
     for (const tab of this._context.tabs())
       await tab.updateTitle();
@@ -87,13 +87,13 @@ ${this._code.join("\n")}
 \`\`\``);
       response.push("");
     }
-    if (this._includeSnapshot || this._includeTabs)
+    if (this._includeSnapshot !== "none" || this._includeTabs)
       response.push(...renderTabsMarkdown(this._context.tabs(), this._includeTabs));
     if (this._tabSnapshot?.modalStates.length) {
       response.push(...(0, import_tab.renderModalStates)(this._context, this._tabSnapshot.modalStates));
       response.push("");
     } else if (this._tabSnapshot) {
-      response.push(renderTabSnapshot(this._tabSnapshot));
+      response.push(renderTabSnapshot(this._tabSnapshot, this._includeSnapshot === "full"));
       response.push("");
     }
     const content = [
@@ -117,7 +117,7 @@ ${this._code.join("\n")}
     }
   }
 }
-function renderTabSnapshot(tabSnapshot) {
+function renderTabSnapshot(tabSnapshot, fullSnapshot) {
   const lines = [];
   if (tabSnapshot.consoleMessages.length) {
     lines.push(`### New console messages`);
@@ -138,10 +138,15 @@ function renderTabSnapshot(tabSnapshot) {
   lines.push(`### Page state`);
   lines.push(`- Page URL: ${tabSnapshot.url}`);
   lines.push(`- Page Title: ${tabSnapshot.title}`);
-  lines.push(`- Page Snapshot:`);
-  lines.push("```yaml");
-  lines.push(tabSnapshot.ariaSnapshot);
-  lines.push("```");
+  if (!fullSnapshot && tabSnapshot.formattedAriaSnapshotDiff) {
+    lines.push(`- Page Snapshot Diff:`);
+    lines.push(tabSnapshot.formattedAriaSnapshotDiff);
+  } else {
+    lines.push(`- Page Snapshot:`);
+    lines.push("```yaml");
+    lines.push(tabSnapshot.ariaSnapshot);
+    lines.push("```");
+  }
   return lines.join("\n");
 }
 function renderTabsMarkdown(tabs, force = false) {

package/lib/mcp/browser/sessionLog.js

@@ -67,7 +67,7 @@ class SessionLog {
     code = code.trim();
     if (isUpdate) {
       const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
-      if (lastEntry.userAction?.name === action.name) {
+      if (lastEntry?.userAction?.name === action.name) {
         lastEntry.userAction = action;
         lastEntry.code = code;
         return;

package/lib/mcp/browser/tab.js

@@ -25,6 +25,7 @@ __export(tab_exports, {
 module.exports = __toCommonJS(tab_exports);
 var import_events = require("events");
 var import_utils = require("playwright-core/lib/utils");
+var import_utilsBundle = require("playwright-core/lib/utilsBundle");
 var import_utils2 = require("./tools/utils");
 var import_log = require("../log");
 const TabEvents = {
@@ -44,7 +45,11 @@ class Tab extends import_events.EventEmitter {
     this._onPageClose = onPageClose;
     page.on("console", (event) => this._handleConsoleMessage(messageToConsoleMessage(event)));
     page.on("pageerror", (error) => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
-    page.on("request", (request) => this._requests.set(request, null));
+    page.on("request", (request) => {
+      this._requests.set(request, null);
+      if (request.frame() === page.mainFrame() && request.isNavigationRequest())
+        this._willNavigateMainFrameToNewDocument();
+    });
     page.on("response", (response) => this._requests.set(response.request(), response));
     page.on("close", () => this._onClose());
     page.on("filechooser", (chooser) => {
@@ -62,10 +67,27 @@ class Tab extends import_events.EventEmitter {
     page.setDefaultNavigationTimeout(this.context.config.timeouts.navigation);
     page.setDefaultTimeout(this.context.config.timeouts.action);
     page[tabSymbol] = this;
+    void this._initialize();
   }
   static forPage(page) {
     return page[tabSymbol];
   }
+  async _initialize() {
+    const messages = await this.page.consoleMessages().catch(() => []);
+    for (const message of messages)
+      this._handleConsoleMessage(messageToConsoleMessage(message));
+    const errors = await this.page.pageErrors().catch(() => []);
+    for (const error of errors)
+      this._handleConsoleMessage(pageErrorToConsoleMessage(error));
+    const requests = await this.page.requests().catch(() => []);
+    for (const request of requests) {
+      this._requests.set(request, null);
+      void request.response().catch(() => null).then((response) => {
+        if (response)
+          this._requests.set(request, response);
+      });
+    }
+  }
   modalStates() {
     return this._modalStates;
   }
@@ -110,6 +132,9 @@ class Tab extends import_events.EventEmitter {
     this._clearCollectedArtifacts();
     this._onPageClose(this);
   }
+  _willNavigateMainFrameToNewDocument() {
+    this._lastAriaSnapshot = void 0;
+  }
   async updateTitle() {
     await this._raceAgainstModalStates(async () => {
       this._lastTitle = await (0, import_utils2.callOnPageNoTrace)(this.page, (page) => page.title());
@@ -126,6 +151,7 @@ class Tab extends import_events.EventEmitter {
   }
   async navigate(url) {
     this._clearCollectedArtifacts();
+    this._willNavigateMainFrameToNewDocument();
     const downloadEvent = (0, import_utils2.callOnPageNoTrace)(this.page, (page) => page.waitForEvent("download").catch(import_log.logUnhandledError));
     try {
       await this.page.goto(url, { waitUntil: "domcontentloaded" });
@@ -159,6 +185,7 @@ class Tab extends import_events.EventEmitter {
         url: this.page.url(),
         title: await this.page.title(),
         ariaSnapshot: snapshot,
+        formattedAriaSnapshotDiff: this._lastAriaSnapshot ? generateAriaSnapshotDiff(this._lastAriaSnapshot, snapshot) : void 0,
         modalStates: [],
         consoleMessages: [],
         downloads: this._downloads
@@ -167,6 +194,7 @@ class Tab extends import_events.EventEmitter {
     if (tabSnapshot) {
       tabSnapshot.consoleMessages = this._recentConsoleMessages;
       this._recentConsoleMessages = [];
+      this._lastAriaSnapshot = tabSnapshot.ariaSnapshot;
     }
     return tabSnapshot ?? {
       url: this.page.url(),
@@ -248,6 +276,23 @@ function renderModalStates(context, modalStates) {
   return result;
 }
 const tabSymbol = Symbol("tabSymbol");
+function generateAriaSnapshotDiff(oldSnapshot, newSnapshot) {
+  const diffs = (0, import_utils.diffAriaSnapshots)(import_utilsBundle.yaml, oldSnapshot, newSnapshot);
+  if (diffs === "equal")
+    return "<no changes>";
+  if (diffs === "different")
+    return;
+  if (diffs.length > 3 || diffs.some((diff) => diff.newSource.split("\n").length > 100)) {
+    return;
+  }
+  const lines = [`The following refs have changed`];
+  for (const diff of diffs)
+    lines.push("", "```yaml", diff.newSource.trimEnd(), "```");
+  const combined = lines.join("\n");
+  if (combined.length >= newSnapshot.length)
+    return;
+  return combined;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Tab,

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

@@ -47,7 +47,7 @@ const snapshot = (0, import_tool.defineTool)({
   },
   handle: async (context, params, response) => {
     await context.ensureTab();
-    response.setIncludeSnapshot();
+    response.setIncludeSnapshot("full");
   }
 });
 const elementSchema = import_bundle.z.object({

package/lib/mcp/program.js

@@ -41,7 +41,7 @@ var import_browserServerBackend = require("./browser/browserServerBackend");
 var import_extensionContextFactory = require("./extension/extensionContextFactory");
 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("--grant-permissions <permissions...>", 'List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write".', import_config.commaSeparatedList).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("--shared-browser-context", "reuse the same browser context between all connected HTTP clients.").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) => {
+  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("--grant-permissions <permissions...>", 'List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write".', import_config.commaSeparatedList).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("--init-script <path...>", "path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page's scripts. Can be specified multiple times.").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("--shared-browser-context", "reuse the same browser context between all connected HTTP clients.").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) => {
     (0, import_watchdog.setupExitWatchdog)();
     if (options.vision) {
       console.error("The --vision option is deprecated, use --caps=vision instead");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright",
-  "version": "1.56.0-alpha-2025-09-21",
+  "version": "1.56.0-alpha-2025-09-23",
   "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-21"
+    "playwright-core": "1.56.0-alpha-2025-09-23"
   },
   "optionalDependencies": {
     "fsevents": "2.3.2"