Playwright 测试代理

简介

Playwright 自带三个开箱即用的 Playwright 测试代理：🎭 planner、🎭 generator 和 🎭 healer。

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

• 🎭 planner 探索应用并生成 Markdown 测试计划
• 🎭 generator 将 Markdown 计划转换为 Playwright 测试文件
• 🎭 healer 执行测试套件并自动修复失败的测试

入门

首先使用 init-agents 命令将 Playwright 测试代理定义添加到您的项目中。Playwright 更新时应重新生成这些定义，以获取新的工具和指令。

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 v1.105（发布于 2025 年 10 月 9 日）是代理体验在 VS Code 中正常运行所必需的。

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

🎭 Planner

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

输入

• 给 planner 的清晰请求（例如，“为访客结账生成计划。”）
• 一个 seed test，用于设置与您的应用交互所需的坏境
• （可选）产品需求文档 (PRD) 作为上下文

Prompt

• 注意 seed.spec.ts 已包含在 planner 的上下文中。
• Planner 将运行此测试以执行您的测试所需的所有初始化，包括全局设置、项目依赖项以及所有必需的 fixtures 和 hooks。
• Planner 还会将此 seed test 用作所有生成测试的示例。或者，您可以在 prompt 中提及文件名。

示例：seed.spec.ts

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

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

输出

• 一个 Markdown 测试计划，保存为 specs/basic-operations.md。
• 该计划是人类可读的，但对于测试生成来说足够精确。

示例：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

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

输入

• 来自 specs/ 的 Markdown 计划

Prompt

• 注意 basic-operations.md 已包含在 generator 的上下文中。
• 这就是 generator 如何知道从哪里获取测试计划。或者，您可以在 prompt 中提及文件名。

输出

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

示例：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

当测试失败时，healer 代理会：

• 重放失败的步骤
• 检查当前 UI 以定位等效的元素或流程
• 建议一个补丁（例如，更新选择器、调整等待时间、修复数据）
• 重新运行测试，直到它通过，或者直到 guardrails 停止循环

输入

• 失败的测试名称

Prompt

输出

• 通过的测试，或者如果 healer 认为功能已损坏，则跳过的测试。

构件和约定

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

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

代理定义

在幕后，代理定义是指令和 MCP 工具的集合。它们由 Playwright 提供，并在 Playwright 更新时应重新生成。

Claude Code 子代理的示例

npx playwright init-agents --loop=vscode

specs/ 中的规范

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

tests/ 中的测试

生成的 Playwright 测试， wherever feasible，与规范一对一对应。

Seed tests seed.spec.ts

Seed tests 提供了一个即用型的 page 上下文来引导执行。