Playwright 测试代理

🌐 Playwright Test Agents

介绍

🌐 Introduction

Playwright 自带三个 Playwright Test 代理：🎭 planner、🎭 generator 和 🎭 healer。

🌐 Playwright comes with three Playwright Test 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.

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

入门

🌐 Getting Started

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

🌐 Start with adding Playwright Test 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

note

VS Code v1.105（发布于2025年10月9日）是代理体验在 VS Code 中正常运行所需的版本。

🌐 VS Code v1.105 (released October 9, 2025) is needed for the agentic experience to function properly in VS Code.

生成代理后，你可以使用你选择的 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.

输入

• 对计划人员的明确请求（例如，“生成一个访客结账计划。”）
• 一个 seed test，用于设置与你的应用交互所需的环境
• (可选) 用于参考的产品需求文档 (PRD)

提示

• 注意 seed.spec.ts 是如何包含在计划的上下文中的。
• 计划将运行此测试，以执行你的测试所需的所有初始化，包括全局设置、项目依赖以及所有必要的夹具和钩子。
• 计划还将使用此种子测试作为生成的所有测试的示例。或者，你可以在提示中提及文件名。

Example: seed.spec.ts

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

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

输出

• 一个以 specs/basic-operations.md 保存的 Markdown 测试计划。
• 该计划易于理解，但足够精确，可以用于测试生成。

示例: 规范/基本操作.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.

输入

• specs/ 的 Markdown 计划

提示

• 注意 basic-operations.md 是如何被包含在生成器的上下文中的。
• 这就是生成器知道从哪里获取测试计划的方法。或者，你也可以在提示中提到文件名。

输出

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

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

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

输入

• 失败测试名称

提示

输出

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

工件和约定

🌐 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 提供，并且每当 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.