patchright-bun-core 1.58.0 → 1.59.0

package/lib/{server/trace/viewer/traceParser.js → tools/mcp/extensionContextFactory.js}

@@ -1,72 +1,55 @@
-"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 traceParser_exports = {};
-__export(traceParser_exports, {
-  ZipTraceLoaderBackend: () => ZipTraceLoaderBackend
-});
-module.exports = __toCommonJS(traceParser_exports);
-var import_url = __toESM(require("url"));
-var import_zipFile = require("../../utils/zipFile");
-class ZipTraceLoaderBackend {
-  constructor(traceFile) {
-    this._traceFile = traceFile;
-    this._zipFile = new import_zipFile.ZipFile(traceFile);
-  }
-  isLive() {
-    return false;
-  }
-  traceURL() {
-    return import_url.default.pathToFileURL(this._traceFile).toString();
-  }
-  async entryNames() {
-    return await this._zipFile.entries();
-  }
-  async hasEntry(entryName) {
-    const entries = await this.entryNames();
-    return entries.includes(entryName);
-  }
-  async readText(entryName) {
-    try {
-      const buffer = await this._zipFile.read(entryName);
-      return buffer.toString("utf-8");
-    } catch {
-    }
-  }
-  async readBlob(entryName) {
-    try {
-      const buffer = await this._zipFile.read(entryName);
-      return new Blob([new Uint8Array(buffer)]);
-    } catch {
-    }
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ZipTraceLoaderBackend
-});
+"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 extensionContextFactory_exports = {};
+__export(extensionContextFactory_exports, {
+  createExtensionBrowser: () => createExtensionBrowser
+});
+module.exports = __toCommonJS(extensionContextFactory_exports);
+var playwright = __toESM(require("../../.."));
+var import_utilsBundle = require("../../utilsBundle");
+var import_network = require("../../server/utils/network");
+var import_cdpRelay = require("./cdpRelay");
+const debugLogger = (0, import_utilsBundle.debug)("pw:mcp:relay");
+async function createExtensionBrowser(config, clientInfo) {
+  const httpServer = (0, import_network.createHttpServer)();
+  await (0, import_network.startHttpServer)(httpServer, {});
+  const relay = new import_cdpRelay.CDPRelayServer(
+    httpServer,
+    config.browser.launchOptions.channel || "chrome",
+    config.browser.userDataDir,
+    config.browser.launchOptions.executablePath
+  );
+  debugLogger(`CDP relay server started, extension endpoint: ${relay.extensionEndpoint()}.`);
+  await relay.ensureExtensionConnectionForMCPContext(clientInfo);
+  return await playwright.chromium.connectOverCDP(relay.cdpEndpoint(), { isLocal: true });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createExtensionBrowser
+});

package/lib/tools/mcp/index.js

@@ -0,0 +1,62 @@
+"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 mcp_exports = {};
+__export(mcp_exports, {
+  createConnection: () => createConnection
+});
+module.exports = __toCommonJS(mcp_exports);
+var import_config = require("./config");
+var import_tools = require("../backend/tools");
+var import_browserFactory = require("./browserFactory");
+var import_browserBackend = require("../backend/browserBackend");
+var import_server = require("../utils/mcp/server");
+const packageJSON = require("../../../package.json");
+async function createConnection(userConfig = {}, contextGetter) {
+  const config = await (0, import_config.resolveConfig)(userConfig);
+  const tools = (0, import_tools.filteredTools)(config);
+  const backendFactory = {
+    name: "api",
+    nameInConfig: "api",
+    version: packageJSON.version,
+    toolSchemas: tools.map((tool) => tool.schema),
+    create: async (clientInfo) => {
+      const browser = contextGetter ? new SimpleBrowser(await contextGetter()) : await (0, import_browserFactory.createBrowser)(config, clientInfo);
+      const context = config.browser.isolated ? await browser.newContext(config.browser.contextOptions) : browser.contexts()[0];
+      return new import_browserBackend.BrowserBackend(config, context, tools);
+    },
+    disposed: async () => {
+    }
+  };
+  return (0, import_server.createServer)("api", packageJSON.version, backendFactory, false);
+}
+class SimpleBrowser {
+  constructor(context) {
+    this._context = context;
+  }
+  contexts() {
+    return [this._context];
+  }
+  async newContext() {
+    throw new Error("Creating a new context is not supported in SimpleBrowserContextFactory.");
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createConnection
+});

package/lib/tools/mcp/log.js

@@ -0,0 +1,35 @@
+"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 log_exports = {};
+__export(log_exports, {
+  logUnhandledError: () => logUnhandledError,
+  testDebug: () => testDebug
+});
+module.exports = __toCommonJS(log_exports);
+var import_utilsBundle = require("../../utilsBundle");
+const errorDebug = (0, import_utilsBundle.debug)("pw:mcp:error");
+function logUnhandledError(error) {
+  errorDebug(error);
+}
+const testDebug = (0, import_utilsBundle.debug)("pw:mcp:test");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  logUnhandledError,
+  testDebug
+});

package/lib/tools/mcp/program.js

@@ -0,0 +1,107 @@
+"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 program_exports = {};
+__export(program_exports, {
+  decorateMCPCommand: () => decorateMCPCommand
+});
+module.exports = __toCommonJS(program_exports);
+var import_utilsBundle = require("../../utilsBundle");
+var mcpServer = __toESM(require("../utils/mcp/server"));
+var import_config = require("./config");
+var import_watchdog = require("./watchdog");
+var import_browserFactory = require("./browserFactory");
+var import_browserBackend = require("../backend/browserBackend");
+var import_tools = require("../backend/tools");
+var import_log = require("./log");
+const version = require("../../../package.json").version;
+function decorateMCPCommand(command) {
+  command.option("--allowed-hosts <hosts...>", "comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass '*' to disable the host check.", import_config.commaSeparatedList).option("--allowed-origins <origins>", "semicolon-separated list of TRUSTED origins to allow the browser to request. Default is to allow all.\nImportant: *does not* serve as a security boundary and *does not* affect redirects. ", import_config.semicolonSeparatedList).option("--allow-unrestricted-file-access", "allow access to files outside of the workspace roots. Also allows unrestricted access to file:// URLs. By default access to file system is restricted to workspace root directories (or cwd if no roots are configured) only, and navigation to file:// URLs is blocked.").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.\nImportant: *does not* serve as a security boundary and *does not* affect redirects.", 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, devtools.", 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("--cdp-timeout <timeout>", "timeout in milliseconds for connecting to CDP endpoint, defaults to 30000ms", import_config.numberParser).option("--codegen <lang>", 'specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript".', import_config.enumParser.bind(null, "--codegen", ["none", "typescript"])).option("--config <path>", "path to the configuration file.").option("--console-level <level>", 'level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.', import_config.enumParser.bind(null, "--console-level", ["error", "warning", "info", "debug"])).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("--endpoint <endpoint>", "Bound browser endpoint to connect to.").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-page <path...>", "path to TypeScript file to evaluate on Playwright page object").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".', import_config.enumParser.bind(null, "--image-responses", ["allow", "omit"])).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("--output-mode <mode>", 'whether to save snapshots, console messages, network logs to a file or to the standard output. Can be "file" or "stdout". Default is "stdout".', import_config.enumParser.bind(null, "--output-mode", ["file", "stdout"])).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("--sandbox", "enable the sandbox for all process types that are normally not sandboxed.").option("--save-session", "Whether to save the Playwright MCP 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("--snapshot-mode <mode>", 'when taking snapshots for responses, specifies the mode to use. Can be "full" or "none". Default is "full".').option("--storage-state <path>", "path to the storage state file for isolated sessions.").option("--test-id-attribute <attribute>", 'specify the attribute to use for test ids, defaults to "data-testid"').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 "1280x720"', import_config.resolutionParser.bind(null, "--viewport-size")).addOption(new import_utilsBundle.ProgramOption("--vision", "Legacy option, use --caps=vision instead").hideHelp()).action(async (options) => {
+    options.sandbox = options.sandbox === true ? void 0 : false;
+    (0, import_watchdog.setupExitWatchdog)();
+    if (options.vision) {
+      console.error("The --vision option is deprecated, use --caps=vision instead");
+      options.caps = "vision";
+    }
+    if (options.caps?.includes("tracing"))
+      options.caps.push("devtools");
+    const config = await (0, import_config.resolveCLIConfigForMCP)(options);
+    const tools = (0, import_tools.filteredTools)(config);
+    if (config.extension) {
+      const serverBackendFactory = {
+        name: "Playwright w/ extension",
+        nameInConfig: "playwright-extension",
+        version,
+        toolSchemas: tools.map((tool) => tool.schema),
+        create: async (clientInfo) => {
+          const browser = await (0, import_browserFactory.createBrowser)(config, clientInfo);
+          const browserContext = browser.contexts()[0];
+          return new import_browserBackend.BrowserBackend(config, browserContext, tools);
+        },
+        disposed: async () => {
+        }
+      };
+      await mcpServer.start(serverBackendFactory, config.server);
+      return;
+    }
+    const useSharedBrowser = config.sharedBrowserContext || config.browser.isolated;
+    let sharedBrowser;
+    let clientCount = 0;
+    const factory = {
+      name: "Playwright",
+      nameInConfig: "playwright",
+      version,
+      toolSchemas: tools.map((tool) => tool.schema),
+      create: async (clientInfo) => {
+        if (useSharedBrowser && clientCount === 0)
+          sharedBrowser = await (0, import_browserFactory.createBrowser)(config, clientInfo);
+        clientCount++;
+        const browser = sharedBrowser || await (0, import_browserFactory.createBrowser)(config, clientInfo);
+        const browserContext = config.browser.isolated ? await browser.newContext(config.browser.contextOptions) : browser.contexts()[0];
+        return new import_browserBackend.BrowserBackend(config, browserContext, tools);
+      },
+      disposed: async (backend) => {
+        clientCount--;
+        if (sharedBrowser && clientCount > 0)
+          return;
+        (0, import_log.testDebug)("close browser");
+        sharedBrowser = void 0;
+        const browserContext = backend.browserContext;
+        await browserContext.close().catch(() => {
+        });
+        await browserContext.browser().close().catch(() => {
+        });
+      }
+    };
+    await mcpServer.start(factory, config.server);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  decorateMCPCommand
+});

package/lib/tools/mcp/protocol.js

@@ -0,0 +1,28 @@
+"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 protocol_exports = {};
+__export(protocol_exports, {
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(protocol_exports);
+const VERSION = 1;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VERSION
+});

package/lib/tools/mcp/watchdog.js

@@ -0,0 +1,44 @@
+"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_utils = require("../../utils");
+var import_log = require("./log");
+function setupExitWatchdog() {
+  let isExiting = false;
+  const handleExit = async (signal) => {
+    if (isExiting)
+      return;
+    isExiting = true;
+    setTimeout(() => process.exit(0), 15e3);
+    (0, import_log.testDebug)("gracefully closing " + import_utils.gracefullyCloseSet.size);
+    await (0, import_utils.gracefullyCloseAll)();
+    process.exit(0);
+  };
+  process.stdin.on("close", () => handleExit("close"));
+  process.on("SIGINT", () => handleExit("SIGINT"));
+  process.on("SIGTERM", () => handleExit("SIGTERM"));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  setupExitWatchdog
+});

package/lib/tools/trace/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: playwright-trace
+description: Inspect Playwright trace files from the command line — list actions, view requests, console, errors, snapshots and screenshots.
+allowed-tools: Bash(npx:*)
+---
+
+# Playwright Trace CLI
+
+Inspect `.zip` trace files produced by Playwright tests without opening a browser.
+
+## Workflow
+
+1. Start with `trace open <trace.zip>` to extract the trace and see its metadata.
+2. Use `trace actions` to see all actions with their action IDs.
+3. Use `trace action <action-id>` to drill into a specific action — see parameters, logs, source location, and available snapshots.
+4. Use `trace requests`, `trace console`, or `trace errors` for cross-cutting views.
+5. Use `trace snapshot <action-id>` to get the DOM snapshot, or run a browser command against it.
+6. Use `trace close` to remove the extracted trace data when done.
+
+All commands after `open` operate on the currently opened trace — no need to pass the trace file again. Opening a new trace replaces the previous one.
+
+## Commands
+
+### Open a trace
+
+```bash
+# Extract trace and show metadata: browser, viewport, duration, action/error counts
+npx playwright trace open <trace.zip>
+```
+
+### Close a trace
+
+```bash
+# Remove extracted trace data
+npx playwright trace close
+```
+
+### Actions
+
+```bash
+# List all actions as a tree with action IDs and timing
+npx playwright trace actions
+
+# Filter by action title (regex, case-insensitive)
+npx playwright trace actions --grep "click"
+
+# Only failed actions
+npx playwright trace actions --errors-only
+```
+
+### Action details
+
+```bash
+# Show full details for one action: params, result, logs, source, snapshots
+npx playwright trace action <action-id>
+```
+
+The `action` command displays available snapshot phases (before, input, after) and the exact command to extract them.
+
+### Requests
+
+```bash
+# All network requests: method, status, URL, duration, size
+npx playwright trace requests
+
+# Filter by URL pattern
+npx playwright trace requests --grep "api"
+
+# Filter by HTTP method
+npx playwright trace requests --method POST
+
+# Only failed requests (status >= 400)
+npx playwright trace requests --failed
+```
+
+### Request details
+
+```bash
+# Show full details for one request: headers, body, security
+npx playwright trace request <request-id>
+```
+
+### Console
+
+```bash
+# All console messages and stdout/stderr
+npx playwright trace console
+
+# Only errors
+npx playwright trace console --errors-only
+
+# Only browser console (no stdout/stderr)
+npx playwright trace console --browser
+
+# Only stdout/stderr (no browser console)
+npx playwright trace console --stdio
+```
+
+### Errors
+
+```bash
+# All errors with stack traces and associated actions
+npx playwright trace errors
+```
+
+### Snapshots
+
+The `snapshot` command loads the DOM snapshot for an action into a headless browser and runs a single browser command against it. Without a browser command, it returns the accessibility snapshot.
+
+```bash
+# Get the accessibility snapshot (default)
+npx playwright trace snapshot <action-id>
+
+# Use a specific phase
+npx playwright trace snapshot <action-id> --name before
+
+# Run eval to query the DOM
+npx playwright trace snapshot <action-id> -- eval "document.title"
+npx playwright trace snapshot <action-id> -- eval "document.querySelector('#error').textContent"
+
+# Eval on a specific element ref (from the snapshot)
+npx playwright trace snapshot <action-id> -- eval "el => el.getAttribute('data-testid')" e5
+
+# Take a screenshot of the snapshot
+npx playwright trace snapshot <action-id> -- screenshot
+
+# Redirect output to a file
+npx playwright trace snapshot <action-id> -- eval "document.body.outerHTML" --filename=page.html
+npx playwright trace snapshot <action-id> -- screenshot --filename=screenshot.png
+```
+
+Only three browser commands are useful on a frozen snapshot: `snapshot`, `eval`, and `screenshot`.
+
+### Attachments
+
+```bash
+# List all trace attachments
+npx playwright trace attachments
+
+# Extract an attachment by its number
+npx playwright trace attachment 1
+npx playwright trace attachment 1 -o out.png
+```
+
+## Typical investigation
+
+```bash
+# 1. Open the trace and see what's inside
+npx playwright trace open test-results/my-test/trace.zip
+
+# 2. What actions ran?
+npx playwright trace actions
+
+# 3. Which action failed?
+npx playwright trace actions --errors-only
+
+# 4. What went wrong?
+npx playwright trace action 12
+
+# 5. What did the page look like at that moment?
+npx playwright trace snapshot 12
+
+# 6. Query the DOM for more detail
+npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent"
+
+# 7. Any relevant network failures?
+npx playwright trace requests --failed
+
+# 8. Any console errors?
+npx playwright trace console --errors-only
+```

package/lib/tools/trace/installSkill.js

@@ -0,0 +1,48 @@
+"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 installSkill_exports = {};
+__export(installSkill_exports, {
+  installSkill: () => installSkill
+});
+module.exports = __toCommonJS(installSkill_exports);
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+async function installSkill() {
+  const cwd = process.cwd();
+  const skillSource = import_path.default.join(__dirname, "SKILL.md");
+  const destDir = import_path.default.join(cwd, ".claude", "skills", "playwright-trace");
+  await import_fs.default.promises.mkdir(destDir, { recursive: true });
+  const destFile = import_path.default.join(destDir, "SKILL.md");
+  await import_fs.default.promises.copyFile(skillSource, destFile);
+  console.log(`\u2705 Skill installed to \`${import_path.default.relative(cwd, destFile)}\`.`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  installSkill
+});