playwright 1.56.0-alpha-2025-09-02 → 1.56.0-alpha-1756945786000

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

@@ -0,0 +1,162 @@
+"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 snapshot_exports = {};
+__export(snapshot_exports, {
+  default: () => snapshot_default,
+  elementSchema: () => elementSchema
+});
+module.exports = __toCommonJS(snapshot_exports);
+var import_bundle = require("../../sdk/bundle");
+var import_tool = require("./tool");
+var javascript = __toESM(require("../codegen"));
+var import_utils = require("./utils");
+const snapshot = (0, import_tool.defineTool)({
+  capability: "core",
+  schema: {
+    name: "browser_snapshot",
+    title: "Page snapshot",
+    description: "Capture accessibility snapshot of the current page, this is better than screenshot",
+    inputSchema: import_bundle.z.object({}),
+    type: "readOnly"
+  },
+  handle: async (context, params, response) => {
+    await context.ensureTab();
+    response.setIncludeSnapshot();
+  }
+});
+const elementSchema = import_bundle.z.object({
+  element: import_bundle.z.string().describe("Human-readable element description used to obtain permission to interact with the element"),
+  ref: import_bundle.z.string().describe("Exact target element reference from the page snapshot")
+});
+const clickSchema = elementSchema.extend({
+  doubleClick: import_bundle.z.boolean().optional().describe("Whether to perform a double click instead of a single click"),
+  button: import_bundle.z.enum(["left", "right", "middle"]).optional().describe("Button to click, defaults to left")
+});
+const click = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_click",
+    title: "Click",
+    description: "Perform click on a web page",
+    inputSchema: clickSchema,
+    type: "destructive"
+  },
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+    const locator = await tab.refLocator(params);
+    const button = params.button;
+    const buttonAttr = button ? `{ button: '${button}' }` : "";
+    if (params.doubleClick)
+      response.addCode(`await page.${await (0, import_utils.generateLocator)(locator)}.dblclick(${buttonAttr});`);
+    else
+      response.addCode(`await page.${await (0, import_utils.generateLocator)(locator)}.click(${buttonAttr});`);
+    await tab.waitForCompletion(async () => {
+      if (params.doubleClick)
+        await locator.dblclick({ button });
+      else
+        await locator.click({ button });
+    });
+  }
+});
+const drag = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_drag",
+    title: "Drag mouse",
+    description: "Perform drag and drop between two elements",
+    inputSchema: import_bundle.z.object({
+      startElement: import_bundle.z.string().describe("Human-readable source element description used to obtain the permission to interact with the element"),
+      startRef: import_bundle.z.string().describe("Exact source element reference from the page snapshot"),
+      endElement: import_bundle.z.string().describe("Human-readable target element description used to obtain the permission to interact with the element"),
+      endRef: import_bundle.z.string().describe("Exact target element reference from the page snapshot")
+    }),
+    type: "destructive"
+  },
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+    const [startLocator, endLocator] = await tab.refLocators([
+      { ref: params.startRef, element: params.startElement },
+      { ref: params.endRef, element: params.endElement }
+    ]);
+    await tab.waitForCompletion(async () => {
+      await startLocator.dragTo(endLocator);
+    });
+    response.addCode(`await page.${await (0, import_utils.generateLocator)(startLocator)}.dragTo(page.${await (0, import_utils.generateLocator)(endLocator)});`);
+  }
+});
+const hover = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_hover",
+    title: "Hover mouse",
+    description: "Hover over element on page",
+    inputSchema: elementSchema,
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+    const locator = await tab.refLocator(params);
+    response.addCode(`await page.${await (0, import_utils.generateLocator)(locator)}.hover();`);
+    await tab.waitForCompletion(async () => {
+      await locator.hover();
+    });
+  }
+});
+const selectOptionSchema = elementSchema.extend({
+  values: import_bundle.z.array(import_bundle.z.string()).describe("Array of values to select in the dropdown. This can be a single value or multiple values.")
+});
+const selectOption = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_select_option",
+    title: "Select option",
+    description: "Select an option in a dropdown",
+    inputSchema: selectOptionSchema,
+    type: "destructive"
+  },
+  handle: async (tab, params, response) => {
+    response.setIncludeSnapshot();
+    const locator = await tab.refLocator(params);
+    response.addCode(`await page.${await (0, import_utils.generateLocator)(locator)}.selectOption(${javascript.formatObject(params.values)});`);
+    await tab.waitForCompletion(async () => {
+      await locator.selectOption(params.values);
+    });
+  }
+});
+var snapshot_default = [
+  snapshot,
+  click,
+  drag,
+  hover,
+  selectOption
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  elementSchema
+});

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

@@ -0,0 +1,67 @@
+"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 tabs_exports = {};
+__export(tabs_exports, {
+  default: () => tabs_default
+});
+module.exports = __toCommonJS(tabs_exports);
+var import_bundle = require("../../sdk/bundle");
+var import_tool = require("./tool");
+const browserTabs = (0, import_tool.defineTool)({
+  capability: "core-tabs",
+  schema: {
+    name: "browser_tabs",
+    title: "Manage tabs",
+    description: "List, create, close, or select a browser tab.",
+    inputSchema: import_bundle.z.object({
+      action: import_bundle.z.enum(["list", "new", "close", "select"]).describe("Operation to perform"),
+      index: import_bundle.z.number().optional().describe("Tab index, used for close/select. If omitted for close, current tab is closed.")
+    }),
+    type: "destructive"
+  },
+  handle: async (context, params, response) => {
+    switch (params.action) {
+      case "list": {
+        await context.ensureTab();
+        response.setIncludeTabs();
+        return;
+      }
+      case "new": {
+        await context.newTab();
+        response.setIncludeTabs();
+        return;
+      }
+      case "close": {
+        await context.closeTab(params.index);
+        response.setIncludeSnapshot();
+        return;
+      }
+      case "select": {
+        if (params.index === void 0)
+          throw new Error("Tab index is required");
+        await context.selectTab(params.index);
+        response.setIncludeSnapshot();
+        return;
+      }
+    }
+  }
+});
+var tabs_default = [
+  browserTabs
+];

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

@@ -0,0 +1,49 @@
+"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 tool_exports = {};
+__export(tool_exports, {
+  defineTabTool: () => defineTabTool,
+  defineTool: () => defineTool
+});
+module.exports = __toCommonJS(tool_exports);
+function defineTool(tool) {
+  return tool;
+}
+function defineTabTool(tool) {
+  return {
+    ...tool,
+    handle: async (context, params, response) => {
+      const tab = context.currentTabOrDie();
+      const modalStates = tab.modalStates().map((state) => state.type);
+      if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
+        response.addError(`Error: The tool "${tool.schema.name}" can only be used when there is related modal state present.
+` + tab.modalStatesMarkdown().join("\n"));
+      else if (!tool.clearsModalState && modalStates.length)
+        response.addError(`Error: Tool "${tool.schema.name}" does not handle the modal state.
+` + tab.modalStatesMarkdown().join("\n"));
+      else
+        return tool.handle(tab, params, response);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineTabTool,
+  defineTool
+});

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

@@ -0,0 +1,90 @@
+"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 utils_exports = {};
+__export(utils_exports, {
+  callOnPageNoTrace: () => callOnPageNoTrace,
+  generateLocator: () => generateLocator,
+  waitForCompletion: () => waitForCompletion
+});
+module.exports = __toCommonJS(utils_exports);
+var import_utils = require("playwright-core/lib/utils");
+async function waitForCompletion(tab, callback) {
+  const requests = /* @__PURE__ */ new Set();
+  let frameNavigated = false;
+  let waitCallback = () => {
+  };
+  const waitBarrier = new Promise((f) => {
+    waitCallback = f;
+  });
+  const requestListener = (request) => requests.add(request);
+  const requestFinishedListener = (request) => {
+    requests.delete(request);
+    if (!requests.size)
+      waitCallback();
+  };
+  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("requestfinished", requestFinishedListener);
+  tab.page.on("framenavigated", frameNavigateListener);
+  const timeout = setTimeout(onTimeout, 1e4);
+  const dispose = () => {
+    tab.page.off("request", requestListener);
+    tab.page.off("requestfinished", requestFinishedListener);
+    tab.page.off("framenavigated", frameNavigateListener);
+    clearTimeout(timeout);
+  };
+  try {
+    const result = await callback();
+    if (!requests.size && !frameNavigated)
+      waitCallback();
+    await waitBarrier;
+    await tab.waitForTimeout(1e3);
+    return result;
+  } finally {
+    dispose();
+  }
+}
+async function generateLocator(locator) {
+  try {
+    const { resolvedSelector } = await locator._resolveSelector();
+    return (0, import_utils.asLocator)("javascript", resolvedSelector);
+  } catch (e) {
+    throw new Error("Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.");
+  }
+}
+async function callOnPageNoTrace(page, callback) {
+  return await page._wrapApiCall(() => callback(page), { internal: true });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  callOnPageNoTrace,
+  generateLocator,
+  waitForCompletion
+});

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

@@ -0,0 +1,154 @@
+"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 verify_exports = {};
+__export(verify_exports, {
+  default: () => verify_default
+});
+module.exports = __toCommonJS(verify_exports);
+var import_bundle = require("../../sdk/bundle");
+var import_tool = require("./tool");
+var javascript = __toESM(require("../codegen"));
+var import_utils = require("./utils");
+const verifyElement = (0, import_tool.defineTabTool)({
+  capability: "verify",
+  schema: {
+    name: "browser_verify_element_visible",
+    title: "Verify element visible",
+    description: "Verify element is visible on the page",
+    inputSchema: import_bundle.z.object({
+      role: import_bundle.z.string().describe('ROLE of the element. Can be found in the snapshot like this: `- {ROLE} "Accessible Name":`'),
+      accessibleName: import_bundle.z.string().describe('ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: `- role "{ACCESSIBLE_NAME}"`')
+    }),
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    const locator = tab.page.getByRole(params.role, { name: params.accessibleName });
+    if (await locator.count() === 0) {
+      response.addError(`Element with role "${params.role}" and accessible name "${params.accessibleName}" not found`);
+      return;
+    }
+    response.addCode(`await expect(page.getByRole(${javascript.escapeWithQuotes(params.role)}, { name: ${javascript.escapeWithQuotes(params.accessibleName)} })).toBeVisible();`);
+    response.addResult("Done");
+  }
+});
+const verifyText = (0, import_tool.defineTabTool)({
+  capability: "verify",
+  schema: {
+    name: "browser_verify_text_visible",
+    title: "Verify text visible",
+    description: `Verify text is visible on the page. Prefer ${verifyElement.schema.name} if possible.`,
+    inputSchema: import_bundle.z.object({
+      text: import_bundle.z.string().describe('TEXT to verify. Can be found in the snapshot like this: `- role "Accessible Name": {TEXT}` or like this: `- text: {TEXT}`')
+    }),
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    const locator = tab.page.getByText(params.text).filter({ visible: true });
+    if (await locator.count() === 0) {
+      response.addError("Text not found");
+      return;
+    }
+    response.addCode(`await expect(page.getByText(${javascript.escapeWithQuotes(params.text)})).toBeVisible();`);
+    response.addResult("Done");
+  }
+});
+const verifyList = (0, import_tool.defineTabTool)({
+  capability: "verify",
+  schema: {
+    name: "browser_verify_list_visible",
+    title: "Verify list visible",
+    description: "Verify list is visible on the page",
+    inputSchema: import_bundle.z.object({
+      element: import_bundle.z.string().describe("Human-readable list description"),
+      ref: import_bundle.z.string().describe("Exact target element reference that points to the list"),
+      items: import_bundle.z.array(import_bundle.z.string()).describe("Items to verify")
+    }),
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+    const itemTexts = [];
+    for (const item of params.items) {
+      const itemLocator = locator.getByText(item);
+      if (await itemLocator.count() === 0) {
+        response.addError(`Item "${item}" not found`);
+        return;
+      }
+      itemTexts.push(await itemLocator.textContent());
+    }
+    const ariaSnapshot = `\`
+- list:
+${itemTexts.map((t) => `  - listitem: ${javascript.escapeWithQuotes(t, '"')}`).join("\n")}
+\``;
+    response.addCode(`await expect(page.locator('body')).toMatchAriaSnapshot(${ariaSnapshot});`);
+    response.addResult("Done");
+  }
+});
+const verifyValue = (0, import_tool.defineTabTool)({
+  capability: "verify",
+  schema: {
+    name: "browser_verify_value",
+    title: "Verify value",
+    description: "Verify element value",
+    inputSchema: import_bundle.z.object({
+      type: import_bundle.z.enum(["textbox", "checkbox", "radio", "combobox", "slider"]).describe("Type of the element"),
+      element: import_bundle.z.string().describe("Human-readable element description"),
+      ref: import_bundle.z.string().describe("Exact target element reference that points to the element"),
+      value: import_bundle.z.string().describe('Value to verify. For checkbox, use "true" or "false".')
+    }),
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+    const locatorSource = `page.${await (0, import_utils.generateLocator)(locator)}`;
+    if (params.type === "textbox" || params.type === "slider" || params.type === "combobox") {
+      const value = await locator.inputValue();
+      if (value !== params.value) {
+        response.addError(`Expected value "${params.value}", but got "${value}"`);
+        return;
+      }
+      response.addCode(`await expect(${locatorSource}).toHaveValue(${javascript.quote(params.value)});`);
+    } else if (params.type === "checkbox" || params.type === "radio") {
+      const value = await locator.isChecked();
+      if (value !== (params.value === "true")) {
+        response.addError(`Expected value "${params.value}", but got "${value}"`);
+        return;
+      }
+      const matcher = value ? "toBeChecked" : "not.toBeChecked";
+      response.addCode(`await expect(${locatorSource}).${matcher}();`);
+    }
+    response.addResult("Done");
+  }
+});
+var verify_default = [
+  verifyElement,
+  verifyText,
+  verifyList,
+  verifyValue
+];

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

@@ -0,0 +1,63 @@
+"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 wait_exports = {};
+__export(wait_exports, {
+  default: () => wait_default
+});
+module.exports = __toCommonJS(wait_exports);
+var import_bundle = require("../../sdk/bundle");
+var import_tool = require("./tool");
+const wait = (0, import_tool.defineTool)({
+  capability: "core",
+  schema: {
+    name: "browser_wait_for",
+    title: "Wait for",
+    description: "Wait for text to appear or disappear or a specified time to pass",
+    inputSchema: import_bundle.z.object({
+      time: import_bundle.z.number().optional().describe("The time to wait in seconds"),
+      text: import_bundle.z.string().optional().describe("The text to wait for"),
+      textGone: import_bundle.z.string().optional().describe("The text to wait for to disappear")
+    }),
+    type: "readOnly"
+  },
+  handle: async (context, params, response) => {
+    if (!params.text && !params.textGone && !params.time)
+      throw new Error("Either time, text or textGone must be provided");
+    if (params.time) {
+      response.addCode(`await new Promise(f => setTimeout(f, ${params.time} * 1000));`);
+      await new Promise((f) => setTimeout(f, Math.min(3e4, params.time * 1e3)));
+    }
+    const tab = context.currentTabOrDie();
+    const locator = params.text ? tab.page.getByText(params.text).first() : void 0;
+    const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : void 0;
+    if (goneLocator) {
+      response.addCode(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+      await goneLocator.waitFor({ state: "hidden" });
+    }
+    if (locator) {
+      response.addCode(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+      await locator.waitFor({ state: "visible" });
+    }
+    response.addResult(`Waited for ${params.text || params.textGone || params.time}`);
+    response.setIncludeSnapshot();
+  }
+});
+var wait_default = [
+  wait
+];