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

...

</details>

从源码结构看，planner 的行为由 [playwright-test-planner.agent.md](https://gitcode.com/GitHub_Trending/pl/playwright/blob/46cd5008d12d4e1297793d921e6cc3b595e388da/packages/playwright/src/agents/playwright-test-planner.agent.md?utm_source=gitcode_repo_files) 定义：frontmatter 声明了模型（sonnet）与工具清单（`search` 加一组 `playwright-test/browser_*` 浏览器工具，以及 `planner_setup_page`、`planner_save_plan` 两个专用工具），正文指令要求其先调用 `planner_setup_page` 设置页面，通过 `browser_*` 工具导航并发现界面，映射主要用户旅程，设计覆盖 happy path、边界条件、错误处理的场景，最后通过 `planner_save_plan` 提交计划。这些专用 MCP 工具在 [plannerTools.ts](https://gitcode.com/GitHub_Trending/pl/playwright/blob/46cd5008d12d4e1297793d921e6cc3b595e388da/packages/playwright/src/mcp/test/plannerTools.ts?utm_source=gitcode_repo_files) 中实现：`planner_setup_page` 负责启动 seed 测试并接管页面，`planner_save_plan` 负责把计划落盘为 Markdown 文件。

## 🎭 Generator：把计划变成可执行的测试

Generator 智能体依据 Markdown 计划产出可执行的 Playwright Test。它在执行场景的过程中实时验证选择器与断言。Playwright 支持生成提示（generation hints），并提供断言目录（assertion catalog）以高效完成结构性与行为性校验。

**输入**

- `specs/` 目录中的 Markdown 计划。

**Prompt**

[![generator 的提示词截图](https://raw.gitcode.com/GitHub_Trending/pl/playwright/raw/46cd5008d12d4e1297793d921e6cc3b595e388da/docs/src/images/test-agents/generator-prompt.png?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/pl/playwright?utm_source=gitcode_repo_files)

- 注意 `basic-operations.md` 被包含在了 generator 的上下文中，generator 由此知道从哪里取测试计划。也可以在 prompt 中直接提及文件名。

**输出**

- `tests/` 下的一套测试；
- 生成的测试可能包含初始错误，这些错误可以由 healer 智能体自动修复。

<details>
<summary>示例：tests/add-valid-todo.spec.ts</summary>

```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();
  });
});

对应的实现定义见 playwright-test-generator.agent.md。值得注意的是 generator 的工作方式是"先真实执行、再落盘代码"：它对计划中的每个步骤，先用 playwright-test/browser_* 工具在浏览器中实时手动执行一遍（把步骤描述作为每次工具调用的 intent），随后通过 generator_read_log 读取执行日志，紧接着调用 generator_write_test 写出源码。写出的文件遵循严格约定：一个文件只包含一个测试、文件名是文件系统友好的场景名、测试放在与计划顶层条目匹配的 test.describe 中、测试标题与场景名一致、每个步骤执行前带步骤注释。这些工具在 generatorTools.ts 中实现。

🎭 Healer：自动修复失败的测试

当测试失败时，healer 智能体会：

• 回放失败步骤；
• 检查当前 UI 以定位等价元素或流程；
• 给出补丁建议（例如更新 locator、调整等待、修正数据）；
• 重跑测试，直到通过或被护栏（guardrails）终止循环。

输入

• 失败的测试名。

Prompt

输出

• 一个通过的测试；或者当 healer 判断功能本身已损坏时，一个被跳过的测试。

playwright-test-healer.agent.md 给出了更细的系统化工作流：用 test_run 跑全部测试找出失败项 → 对每个失败测试用 test_debug 调试（该工具会让测试在出错处暂停）→ 利用 browser_* MCP 工具查看错误详情、页面快照，分析选择器、时序或断言问题 → 做根因分析（选择器变化、同步时序、数据依赖、应用变更）→ 修改代码（更新选择器、修正断言、对动态数据使用正则构造稳健 locator）→ 每次修复后重启验证，循环直至干净通过。其工具清单中包含 playwright-test/test_list、playwright-test/test_run、playwright-test/test_debug（实现于 testTools.ts）以及 edit 文件编辑工具。两个值得注意的兜底约定：如果高置信度确认测试本身正确但功能确实坏了，就把测试标记为 test.fixme() 跳过，并在失败步骤前加注释说明实际行为；全程不向用户提问，自行做出最合理的处理；且禁止使用 networkidle 等被不推荐或已废弃的 API。

产物结构与目录约定

静态的智能体定义和生成的文件遵循一套简单、可审计的结构：

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 subagent 的生成：

npx playwright init-agents --loop=vscode