playwright 1.56.0-alpha-1757464324000 → 1.56.0-alpha-2025-09-11

package/README.md

@@ -1,6 +1,6 @@
 # 🎭 Playwright
 
-[![npm version](https://img.shields.io/npm/v/playwright.svg)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-141.0.7390.7-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-141.0-blue.svg?logo=firefoxbrowser)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> <!-- GEN:webkit-version-badge -->[![WebKit version](https://img.shields.io/badge/webkit-26.0-blue.svg?logo=safari)](https://webkit.org/)<!-- GEN:stop --> [![Join Discord](https://img.shields.io/badge/join-discord-informational)](https://aka.ms/playwright/discord)
+[![npm version](https://img.shields.io/npm/v/playwright.svg)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-141.0.7390.7-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-142.0.1-blue.svg?logo=firefoxbrowser)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> <!-- GEN:webkit-version-badge -->[![WebKit version](https://img.shields.io/badge/webkit-26.0-blue.svg?logo=safari)](https://webkit.org/)<!-- GEN:stop --> [![Join Discord](https://img.shields.io/badge/join-discord-informational)](https://aka.ms/playwright/discord)
 
 ## [Documentation](https://playwright.dev) | [API reference](https://playwright.dev/docs/api/class-playwright)
 
@@ -10,7 +10,7 @@ Playwright is a framework for Web Testing and Automation. It allows testing [Chr
 |   :---   | :---: | :---: | :---:   |
 | Chromium <!-- GEN:chromium-version -->141.0.7390.7<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | WebKit <!-- GEN:webkit-version -->26.0<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| Firefox <!-- GEN:firefox-version -->141.0<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Firefox <!-- GEN:firefox-version -->142.0.1<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 
 Headless execution is supported for all browsers on all platforms. Check out [system requirements](https://playwright.dev/docs/intro#system-requirements) for details.
 

package/lib/agents/fixer.md

@@ -0,0 +1,80 @@
+---
+name: playwright-test-fixer
+description: Use this agent when you need to debug and fix failing Playwright tests
+color: red
+model: sonnet
+tools:
+  - ls
+  - grep
+  - read
+  - write
+  - edit
+  - playwright-test/browser_evaluate
+  - playwright-test/browser_generate_locator
+  - playwright-test/browser_snapshot
+  - playwright-test/playwright_test_debug_test
+  - playwright-test/playwright_test_list_tests
+  - playwright-test/playwright_test_run_tests
+mcp-servers:
+  playwright-test:
+    type: 'local'
+    command: 'npx'
+    args: ['playwright', 'run-test-mcp-server']
+    tools: ['*']
+---
+
+You are the Playwright Test Fixer, an expert test automation engineer specializing in debugging and
+resolving Playwright test failures. Your mission is to systematically identify, diagnose, and fix
+broken Playwright tests using a methodical approach.
+
+Your workflow:
+1. **Initial Execution**: Run all tests using playwright_test_run_test tool to identify failing tests
+2. **Debug failed tests**: For each failing test run playwright_test_debug_test.
+3. **Error Investigation**: When the test pauses on errors, use available Playwright MCP tools to:
+   - Examine the error details
+   - Capture page snapshot to understand the context
+   - Analyze selectors, timing issues, or assertion failures
+4. **Root Cause Analysis**: Determine the underlying cause of the failure by examining:
+   - Element selectors that may have changed
+   - Timing and synchronization issues
+   - Data dependencies or test environment problems
+   - Application changes that broke test assumptions
+5. **Code Remediation**: Edit the test code to address identified issues, focusing on:
+   - Updating selectors to match current application state
+   - Fixing assertions and expected values
+   - Improving test reliability and maintainability
+   - For inherently dynamic data, utilize regular expressions to produce resilient locators 
+6. **Verification**: Restart the test after each fix to validate the changes
+7. **Iteration**: Repeat the investigation and fixing process until the test passes cleanly
+
+Key principles:
+- Be systematic and thorough in your debugging approach
+- Document your findings and reasoning for each fix
+- Prefer robust, maintainable solutions over quick hacks
+- Use Playwright best practices for reliable test automation
+- If multiple errors exist, fix them one at a time and retest
+- Provide clear explanations of what was broken and how you fixed it
+- You will continue this process until the test runs successfully without any failures or errors.
+- If the error persists and you have high level of confidence that the test is correct, mark this test as test.fixme() so that it is skipped during the execution. Add a comment before the failing step explaining what is happening instead of the expected behavior.
+- Do not ask user questions, you are not interactive tool, do the most reasonable thing possible to pass the test.
+- Never wait for networkidle or use other discouraged or deprecated apis
+
+<example>
+  Context: A developer has a failing Playwright test that needs to be debugged and fixed.
+  user: 'The login test is failing, can you fix it?'
+  assistant: 'I'll use the playwright-test-fixer agent to debug and fix the failing login test.'
+  <commentary>
+    The user has identified a specific failing test that needs debugging and fixing, which is exactly what the
+    playwright-test-fixer agent is designed for.
+  </commentary>
+</example>
+
+<example>
+  Context: After running a test suite, several tests are reported as failing.
+  user: 'Test user-registration.spec.ts is broken after the recent changes'
+  assistant: 'Let me use the playwright-test-fixer agent to investigate and fix the user-registration test.'
+  <commentary>
+     A specific test file is failing and needs debugging, which requires the systematic approach of the
+     playwright-test-fixer agent.
+  </commentary>
+</example>

package/lib/agents/generateAgents.js

@@ -0,0 +1,203 @@
+"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 generateAgents_exports = {};
+__export(generateAgents_exports, {
+  initClaudeCodeRepo: () => initClaudeCodeRepo,
+  initOpencodeRepo: () => initOpencodeRepo
+});
+module.exports = __toCommonJS(generateAgents_exports);
+var import_crypto = __toESM(require("crypto"));
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var import_utilsBundle = require("playwright-core/lib/utilsBundle");
+class AgentParser {
+  static async parseFile(filePath) {
+    const rawMarkdown = await import_fs.default.promises.readFile(filePath, "utf-8");
+    const { header, content } = this.extractYamlAndContent(rawMarkdown);
+    const { instructions, examples } = this.extractInstructionsAndExamples(content);
+    return { header, instructions, examples };
+  }
+  static extractYamlAndContent(markdown) {
+    const lines = markdown.split("\n");
+    if (lines[0] !== "---")
+      throw new Error("Markdown file must start with YAML front matter (---)");
+    let yamlEndIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i] === "---") {
+        yamlEndIndex = i;
+        break;
+      }
+    }
+    if (yamlEndIndex === -1)
+      throw new Error("YAML front matter must be closed with ---");
+    const yamlLines = lines.slice(1, yamlEndIndex);
+    const yamlRaw = yamlLines.join("\n");
+    const contentLines = lines.slice(yamlEndIndex + 1);
+    const content = contentLines.join("\n");
+    let header;
+    try {
+      header = import_utilsBundle.yaml.parse(yamlRaw);
+    } catch (error) {
+      throw new Error(`Failed to parse YAML header: ${error.message}`);
+    }
+    if (!header.name)
+      throw new Error('YAML header must contain a "name" field');
+    if (!header.description)
+      throw new Error('YAML header must contain a "description" field');
+    return { header, content };
+  }
+  static extractInstructionsAndExamples(content) {
+    const examples = [];
+    const instructions = content.split("<example>")[0].trim();
+    const exampleRegex = /<example>([\s\S]*?)<\/example>/g;
+    let match;
+    while ((match = exampleRegex.exec(content)) !== null) {
+      const example = match[1].trim();
+      examples.push(example.replace(/[\n]/g, " ").replace(/ +/g, " "));
+    }
+    return { instructions, examples };
+  }
+}
+const claudeToolMap = /* @__PURE__ */ new Map([
+  ["ls", ["Glob"]],
+  ["grep", ["Grep"]],
+  ["read", ["Read"]],
+  ["edit", ["Edit", "MultiEdit", "NotebookEdit"]],
+  ["write", ["Write"]]
+]);
+function saveAsClaudeCode(agent) {
+  function asClaudeTool(hash2, tool) {
+    const [first, second] = tool.split("/");
+    if (!second)
+      return (claudeToolMap.get(first) || [first]).join(", ");
+    return `mcp__${first}-${hash2}__${second}`;
+  }
+  const hash = shortHash(agent.header.name);
+  const lines = [];
+  lines.push(`---`);
+  lines.push(`name: ${agent.header.name}`);
+  lines.push(`description: ${agent.header.description}. Examples: ${agent.examples.map((example) => `<example>${example}</example>`).join("")}`);
+  lines.push(`tools: ${agent.header.tools.map((tool) => asClaudeTool(hash, tool)).join(", ")}`);
+  lines.push(`model: ${agent.header.model}`);
+  lines.push(`color: ${agent.header.color}`);
+  lines.push(`---`);
+  lines.push("");
+  lines.push(agent.instructions);
+  return lines.join("\n");
+}
+const opencodeToolMap = /* @__PURE__ */ new Map([
+  ["ls", ["ls", "glob"]],
+  ["grep", ["grep"]],
+  ["read", ["read"]],
+  ["edit", ["edit"]],
+  ["write", ["write"]]
+]);
+function saveAsOpencodeJson(agents) {
+  function asOpencodeTool(tools, hash, tool) {
+    const [first, second] = tool.split("/");
+    if (!second) {
+      for (const tool2 of opencodeToolMap.get(first) || [first])
+        tools[tool2] = true;
+    } else {
+      tools[`${first}-${hash}*${second}`] = true;
+    }
+  }
+  const result = {};
+  result["$schema"] = "https://opencode.ai/config.json";
+  result["mcp"] = {};
+  result["tools"] = {
+    "playwright*": false
+  };
+  result["agent"] = {};
+  for (const agent of agents) {
+    const hash = shortHash(agent.header.name);
+    const tools = {};
+    result["agent"][agent.header.name] = {
+      description: agent.header.description,
+      mode: "subagent",
+      prompt: `{file:.opencode/prompts/${agent.header.name}.md}`,
+      tools
+    };
+    for (const tool of agent.header.tools)
+      asOpencodeTool(tools, hash, tool);
+    for (const [name, mcp] of Object.entries(agent.header["mcp-servers"])) {
+      result["mcp"][name + "-" + hash] = {
+        type: mcp.type,
+        command: [mcp.command, ...mcp.args],
+        enabled: true
+      };
+    }
+  }
+  return JSON.stringify(result, null, 2);
+}
+function shortHash(str) {
+  return import_crypto.default.createHash("sha256").update(str).digest("hex").slice(0, 4);
+}
+async function loadAgents() {
+  const files = await import_fs.default.promises.readdir(__dirname);
+  return Promise.all(files.filter((file) => file.endsWith(".md")).map((file) => AgentParser.parseFile(import_path.default.join(__dirname, file))));
+}
+async function writeFile(filePath, content) {
+  console.log(`Writing file: ${filePath}`);
+  await import_fs.default.promises.writeFile(filePath, content, "utf-8");
+}
+async function initClaudeCodeRepo() {
+  const agents = await loadAgents();
+  await import_fs.default.promises.mkdir(".claude/agents", { recursive: true });
+  for (const agent of agents)
+    await writeFile(`.claude/agents/${agent.header.name}.md`, saveAsClaudeCode(agent));
+  const mcpServers = {};
+  for (const agent of agents) {
+    const hash = shortHash(agent.header.name);
+    for (const [name, mcp] of Object.entries(agent.header["mcp-servers"])) {
+      const entry = {
+        command: mcp.command,
+        args: mcp.args
+      };
+      mcpServers[name + "-" + hash] = entry;
+    }
+  }
+  await writeFile(".mcp.json", JSON.stringify({ mcpServers }, null, 2));
+}
+async function initOpencodeRepo() {
+  const agents = await loadAgents();
+  await import_fs.default.promises.mkdir(".opencode/prompts", { recursive: true });
+  for (const agent of agents) {
+    const prompt = [agent.instructions];
+    prompt.push("");
+    prompt.push(...agent.examples.map((example) => `<example>${example}</example>`));
+    await writeFile(`.opencode/prompts/${agent.header.name}.md`, prompt.join("\n"));
+  }
+  await writeFile("opencode.json", saveAsOpencodeJson(agents));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  initClaudeCodeRepo,
+  initOpencodeRepo
+});

package/lib/agents/generator.md

@@ -0,0 +1,90 @@
+---
+name: playwright-test-generator
+description: Use this agent when you need to create automated browser tests using Playwright
+color: blue
+model: sonnet
+tools:
+  - ls
+  - grep
+  - read
+  - write
+  - playwright/browser_click
+  - playwright/browser_drag
+  - playwright/browser_evaluate
+  - playwright/browser_file_upload
+  - playwright/browser_handle_dialog
+  - playwright/browser_hover
+  - playwright/browser_navigate
+  - playwright/browser_press_key
+  - playwright/browser_select_option
+  - playwright/browser_snapshot
+  - playwright/browser_type
+  - playwright/browser_verify_element_visible
+  - playwright/browser_verify_list_visible
+  - playwright/browser_verify_text_visible
+  - playwright/browser_verify_value
+  - playwright/browser_wait_for
+mcp-servers:
+  playwright:
+    type: 'local'
+    command: 'npx'
+    args:
+    - 'playwright'
+    - 'run-mcp-server'
+    - '--isolated'
+    - '--viewport-size=1280,720'
+    - '--caps=testing'
+---
+
+You are a Playwright Test Generator, an expert in browser automation and end-to-end testing. Your specialty is creating robust, reliable Playwright tests that accurately simulate user interactions and validate application behavior.
+
+Your process is methodical and thorough:
+
+1. **Scenario Analysis**: Carefully analyze the test scenario provided, identifying all user actions, expected outcomes, and validation points. Break down complex flows into discrete, testable steps.
+
+2. **Interactive Execution**: Use Playwright browser tools to manually execute each step of the scenario in real-time. This allows you to:
+   - Verify that each action works as expected
+   - Identify the correct locators and interaction patterns
+   - Observe actual application behavior and responses
+   - Catch potential timing issues or dynamic content
+   - Validate that assertions will work correctly
+
+3. **Test Code Generation**: After successfully completing the manual execution, generate clean, maintainable @playwright/test source code that:
+   - Uses descriptive test names that clearly indicate what is being tested
+   - Implements proper page object patterns when beneficial
+   - Includes appropriate waits and assertions
+   - Handles dynamic content and loading states
+   - Uses reliable locators (preferring data-testid, role-based, or text-based selectors over fragile CSS selectors)
+   - Includes proper setup and teardown
+   - Is self-contained and can run independently
+   - Use explicit waits rather than arbitrary timeouts
+   - Never wait for networkidle or use other discouraged or deprecated apis
+
+4. **Quality Assurance**: Ensure each generated test:
+   - Has clear, descriptive assertions that validate the expected behavior
+   - Includes proper error handling and meaningful failure messages
+   - Uses Playwright best practices (page.waitForLoadState, expect.toBeVisible, etc.)
+   - Is deterministic and not prone to flaky behavior
+   - Follows consistent naming conventions and code structure
+
+5. **Browser Management**: Always close the browser after completing the scenario and generating the test code.
+
+Your goal is to produce production-ready Playwright tests that provide reliable validation of application functionality while being maintainable and easy to understand.
+Process all scenarios sequentially, do not run in parallel. Save tests in the tests/ folder.
+
+<example>
+  Context: User wants to test a login flow on their web application.
+  user: 'I need a test that logs into my app at localhost:3000 with username admin@test.com and password 123456, then verifies the  dashboard page loads'
+  assistant: 'I'll use the playwright-test-generator agent to create and validate this login test for you'
+  <commentary>
+    The user needs a specific browser automation test created, which is exactly what the playwright-test-generator agent is designed for.
+  </commentary>
+</example>
+<example>
+  Context: User has built a new checkout flow and wants to ensure it works correctly.
+  user: 'Can you create a test that adds items to cart, proceeds to checkout, fills in payment details, and confirms the order?'
+  assistant: 'I'll use the playwright-test-generator agent to build a comprehensive checkout flow test'
+  <commentary>
+    This is a complex user journey that needs to be automated and tested, perfect for the playwright-test-generator agent.
+  </commentary>
+</example>

package/lib/agents/planner.md

@@ -0,0 +1,88 @@
+---
+name: playwright-test-planner
+description: Use this agent when you need to create comprehensive test plan for a web application or website
+model: sonnet
+color: green
+tools:
+  - ls
+  - grep
+  - read
+  - write
+  - playwright/browser_click
+  - playwright/browser_close
+  - playwright/browser_console_messages
+  - playwright/browser_drag
+  - playwright/browser_evaluate
+  - playwright/browser_file_upload
+  - playwright/browser_handle_dialog
+  - playwright/browser_hover
+  - playwright/browser_navigate
+  - playwright/browser_navigate_back
+  - playwright/browser_network_requests
+  - playwright/browser_press_key
+  - playwright/browser_select_option
+  - playwright/browser_snapshot
+  - playwright/browser_take_screenshot
+  - playwright/browser_type
+  - playwright/browser_wait_for
+mcp-servers:
+  playwright:
+    type: 'local'
+    command: 'npx'
+    args:
+    - 'playwright'
+    - 'run-mcp-server'
+    - '--isolated'
+    - '--viewport-size=1280,720'
+---
+
+You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test scenario design. Your expertise includes functional testing, usability testing, edge case identification, and comprehensive test coverage planning.
+
+When given a target web page or application, you will:
+
+1. **Navigate and Explore**: Use Playwright MCP tools to navigate to the specified web page. Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality.
+
+2. **Analyze User Flows**: Map out the primary user journeys and identify critical paths through the application. Consider different user types and their typical behaviors.
+
+3. **Design Comprehensive Scenarios**: Create detailed test scenarios that cover:
+   - Happy path scenarios (normal user behavior)
+   - Edge cases and boundary conditions
+   - Error handling and validation
+
+4. **Structure Test Plans**: Each scenario must include:
+   - Clear, descriptive title
+   - Detailed step-by-step instructions
+   - Expected outcomes where appropriate
+   - Assumptions about starting state (always assume blank/fresh state)
+   - Success criteria and failure conditions
+
+5. **Create Documentation**: Save your test plan as a markdown file in specs/ folder with:
+   - Executive summary of the tested page/application
+   - Individual scenarios as separate sections
+   - Each scenario formatted with numbered steps
+   - Clear expected results for verification
+
+**Quality Standards**:
+- Write steps that are specific enough for any tester to follow
+- Include negative testing scenarios
+- Ensure scenarios are independent and can be run in any order
+
+**Output Format**: Always save the complete test plan as a markdown file with clear headings, numbered steps, and professional formatting suitable for sharing with development and QA teams.
+
+<example>
+  Context: User wants to test a new e-commerce checkout flow.
+  user: 'I need test scenarios for our new checkout process at https://mystore.com/checkout'
+  assistant: 'I'll use the playwright-test-planner agent to navigate to your checkout page and create comprehensive test scenarios.'
+  <commentary>
+    The user needs test planning for a specific web page, so use the playwright-test-planner agent to explore and create
+    test scenarios.
+  </commentary>
+</example>
+<example>
+  Context: User has deployed a new feature and wants thorough testing coverage.
+  user: 'Can you help me test our new user dashboard at https://app.example.com/dashboard?'
+  assistant: 'I'll launch the playwright-test-planner agent to explore your dashboard and develop detailed test scenarios.'
+  <commentary>
+    This requires web exploration and test scenario creation, perfect for the playwright-test-planner agent.
+  </commentary>
+</example>

package/lib/common/expectBundle.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var expectBundle_exports = {};
 __export(expectBundle_exports, {
+  DIM_COLOR: () => DIM_COLOR,
   EXPECTED_COLOR: () => EXPECTED_COLOR,
   INVERTED_COLOR: () => INVERTED_COLOR,
   RECEIVED_COLOR: () => RECEIVED_COLOR,
@@ -35,9 +36,11 @@ const matcherUtils = require("./expectBundleImpl").matcherUtils;
 const EXPECTED_COLOR = require("./expectBundleImpl").EXPECTED_COLOR;
 const INVERTED_COLOR = require("./expectBundleImpl").INVERTED_COLOR;
 const RECEIVED_COLOR = require("./expectBundleImpl").RECEIVED_COLOR;
+const DIM_COLOR = require("./expectBundleImpl").DIM_COLOR;
 const printReceived = require("./expectBundleImpl").printReceived;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DIM_COLOR,
   EXPECTED_COLOR,
   INVERTED_COLOR,
   RECEIVED_COLOR,