Playwright 代理

¥Playwright Agents

介绍

¥Introduction

Playwright 内置三个 Playwright 代理：🎭 规划器、🎭 生成器和🎭 修复器。

¥Playwright comes with three Playwright Agents out of the box: 🎭 planner, 🎭 generator and 🎭 healer.

这些代理可以独立使用、顺序使用，或作为代理循环中的链式调用。按顺序使用它们将为您的产品提供测试覆盖率。

¥These agents can be used independently, sequentially, or as the chained calls in the agentic loop. Using them sequentially will produce test coverage for your product.

• 🎭 规划器探索应用程序并生成 Markdown 测试计划

  ¥🎭 planner explores the app and produces a Markdown test plan

• 🎭 生成器将 Markdown 计划转换为 Playwright 测试文件

  ¥🎭 generator transforms the Markdown plan into the Playwright Test files

• 🎭 修复器执行测试套件并自动修复失败的测试

  ¥🎭 healer executes the test suite and automatically repairs failing tests

入门

¥Getting Started

首先使用 init-agents 命令将 Playwright 代理定义添加到您的项目中。每当 Playwright 更新以使用新的工具和说明时，都应重新生成这些定义。

¥Start with adding Playwright Agent definitions to your project using the init-agents command. These definitions should be regenerated whenever Playwright is updated to pick up new tools and instructions.

VS Code

npx playwright init-agents --loop=vscode

Claude Code

npx playwright init-agents --loop=claude

OpenCode

npx playwright init-agents --loop=opencode

注意

VS Code 中的代理体验需要 VS Code v1.105（目前在 VS Code Insiders 频道​​ 上）。它很快就会稳定下来，我们在这方面的功能领先一步！

¥VS Code v1.105 (currently on the VS Code Insiders channel) is needed for the agentic experience in VS Code. It will become stable shortly, we are a bit ahead of the curve with this functionality!

生成代理后，您可以使用您选择的 AI 工具命令这些代理构建 Playwright 测试。

¥Once the agents have been generated, you can use your AI tool of choice to command these agents to build Playwright Tests.

🎭 规划器

¥🎭 Planner

Planner 代理会探索您的应用，并针对一个或多个场景和用户流程生成测试计划。

¥Planner agent explores your app and produces a test plan for one or many scenarios and user flows.

输入

¥Input

• 对计划人员的明确请求（例如，“生成一个访客结账计划。”）

  ¥A clear request to the planner (e.g., “Generate a plan for guest checkout.”)

• 用于设置与应用交互所需环境的 seed test

  ¥A seed test that sets up the environment necessary to interact with your app

• （可选）用于上下文的产品需求文档 (PRD)

  ¥(optional) A Product Requirement Document (PRD) for context

提示

¥Prompt

• 请注意 seed.spec.ts 是如何包含在规划器上下文中的。

  ¥Notice how the seed.spec.ts is included in the context of the planner.

• Planner 将运行此测试来执行测试所需的所有初始化操作，包括全局设置、项目依赖项以及所有必要的 Fixture 和 Hook。

  ¥Planner will run this test to execute all the initialization necessary for your test including the global setup, project dependencies and all the necessary fixtures and hooks.

• Planner 还会将此种子测试作为所有生成测试的样例。或者，您可以在提示符中提及文件名。

  ¥Planner will also use this seed test as an example of all the generated tests. Alternatively, you can mention the file name in the prompt.

Example: seed.spec.ts

import { test, expect } from './fixtures';

test('seed', async ({ page }) => {
  // this test uses custom fixtures from ./fixtures
});

输出

¥Output

• 保存为 specs/basic-operations.md 的 Markdown 测试计划。

  ¥A Markdown test plan saved as specs/basic-operations.md.

• 该计划易于理解，但足够精确，可以用于测试生成。

  ¥The plan is human-readable but precise enough for test generation.

Example: specs/basic-operations.md

# TodoMVC Application - Basic Operations Test Plan

## Application Overview

The TodoMVC application is a React-based todo list manager that demonstrates standard todo application functionality. The application provides comprehensive task management capabilities with a clean, intuitive interface. Key features include:

- **Task Management**: Add, edit, complete, and delete individual todos
- **Bulk Operations**: Mark all todos as complete/incomplete and clear all completed todos  
- **Filtering System**: View todos by All, Active, or Completed status with URL routing support
- **Real-time Counter**: Display of active (incomplete) todo count
- **Interactive UI**: Hover states, edit-in-place functionality, and responsive design
- **State Persistence**: Maintains state during session navigation

## Test Scenarios

### 1. Adding New Todos

**Seed:** `tests/seed.spec.ts`

#### 1.1 Add Valid Todo

**Steps:**
1. Click in the "What needs to be done?" input field
2. Type "Buy groceries"
3. Press Enter key

**Expected Results:**
- Todo appears in the list with unchecked checkbox
- Counter shows "1 item left"
- Input field is cleared and ready for next entry
- Todo list controls become visible (Mark all as complete checkbox)

#### 1.2 Add Multiple Todos
...

🎭 生成器

¥🎭 Generator

生成器代理使用 Markdown 计划生成可执行的 Playwright 测试。它会在执行场景时实时验证选择器和断言。Playwright 支持生成提示，并提供断言目录，以实现高效的结构和行为验证。

¥Generator agent uses the Markdown plan to produce executable Playwright Tests. It verifies selectors and assertions live as it performs the scenarios. Playwright supports generation hints and provides a catalog of assertions for efficient structural and behavioral validation.

输入

¥Input

• 来自 specs/ 的 Markdown 计划

  ¥Markdown plan from specs/

提示

¥Prompt

• 请注意 basic-operations.md 是如何包含在生成器上下文中的。

  ¥Notice how the basic-operations.md is included in the context of the generator.

• 这就是生成器知道从哪里获取测试计划的方式。或者，您可以在提示符中提及文件名。

  ¥This is how generator knows where to get the test plan from. Alternatively, you can mention the file name in the prompt.

输出

¥Output

• tests/ 下的测试套件

  ¥A test suite under tests/

• 生成的测试可能包含初始错误，这些错误可以由修复代理自动修复。

  ¥Generated tests may include initial errors that can be healed automatically by the healer agent

Example: tests/add-valid-todo.spec.ts

// spec: specs/basic-operations.md
// seed: tests/seed.spec.ts

import { test, expect } from '../fixtures';

test.describe('Adding New Todos', () => {
  test('Add Valid Todo', async ({ page }) => {
    // 1. Click in the "What needs to be done?" input field
    const todoInput = page.getByRole('textbox', { name: 'What needs to be done?' });
    await todoInput.click();

    // 2. Type "Buy groceries"
    await todoInput.fill('Buy groceries');

    // 3. Press Enter key
    await todoInput.press('Enter');

    // Expected Results:
    // - Todo appears in the list with unchecked checkbox
    await expect(page.getByText('Buy groceries')).toBeVisible();
    const todoCheckbox = page.getByRole('checkbox', { name: 'Toggle Todo' });
    await expect(todoCheckbox).toBeVisible();
    await expect(todoCheckbox).not.toBeChecked();

    // - Counter shows "1 item left"
    await expect(page.getByText('1 item left')).toBeVisible();

    // - Input field is cleared and ready for next entry
    await expect(todoInput).toHaveValue('');
    await expect(todoInput).toBeFocused();

    // - Todo list controls become visible (Mark all as complete checkbox)
    await expect(page.getByRole('checkbox', { name: '❯Mark all as complete' })).toBeVisible();
  });
});

🎭 修复器

¥🎭 Healer

当测试失败时，修复器代理：

¥When the test fails, the healer agent:

• 重放失败的步骤

  ¥Replays the failing steps

• 检查当前 UI 以定位等效元素或流程

  ¥Inspects the current UI to locate equivalent elements or flows

• 建议补丁（例如，定位器更新、等待时间调整、数据修复）

  ¥Suggests a patch (e.g., locator update, wait adjustment, data fix)

• 重新运行测试，直到测试通过或直到护栏停止循环

  ¥Re-runs the test until it passes or until guardrails stop the loop

输入

¥Input

• 失败测试名称

  ¥Failing test name

提示

¥Prompt

输出

¥Output

• 通过测试，或者如果修复人员认为该功能存在问题，则跳过测试。

  ¥A passing test, or a skipped test if the healer believes the that functionality is broken.

工件和约定

¥Artifacts and Conventions

静态代理定义和生成的文件遵循简单、可审计的结构：

¥The static agent definitions and generated files follow a simple, auditable structure:

repo/
  .github/                    # agent definitions
  specs/                      # human-readable test plans
    basic-operations.md
  tests/                      # generated Playwright tests
    seed.spec.ts              # seed test for environment
    tests/create/add-valid-todo.spec.ts
  playwright.config.ts

代理定义

¥Agent Definitions

在底层，代理定义是说明和 MCP 工具的集合。它们由 Playwright 提供，并且每次更新时都应重新生成。

¥Under the hood, agent definitions are collections of instructions and MCP tools. They are provided by Playwright and should be regenerated whenever Playwright is updated.

Claude Code 子代理示例：

¥Example for Claude Code subagents:

npx playwright init-agents --loop=vscode

specs/ 中的规范

¥Specs in specs/

规范是用人类可读的术语描述场景的结构化计划。它们包含步骤、预期结果和数据。规范可以从头开始，也可以扩展种子测试。​​

¥Specs are structured plans describing scenarios in human-readable terms. They include steps, expected outcomes, and data. Specs can start from scratch or extend a seed test.

tests/ 中的测试

¥Tests in tests/

生成的 Playwright 测试，尽可能与规范一一对应。

¥Generated Playwright tests, aligned one-to-one with specs wherever feasible.

种子测试 seed.spec.ts

¥Seed tests seed.spec.ts

种子测试提供了一个随时可用的 page 上下文来引导执行。

¥Seed tests provide a ready-to-use page context to bootstrap execution.