<Feature> Test Plan

Application Overview

Test Scenarios

1.

Seed: tests/seed.spec.ts

1.1.

File: tests/<group>/<kebab-case-scenario-name>.spec.ts

Steps:

- expect: <observable outcome>
- expect: <another observable outcome>

- expect: <outcome>

1.2.

...

2.

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

编写规范：

- 每个场景相互独立，都从 seed 的干净状态出发 —— **绝不串联场景**；
- 场景名使用 kebab-case，且与测试文件名一致（`should-add-single-todo` → `should-add-single-todo.spec.ts`）；
- 覆盖 happy path、边界、校验、负向流程与持久化；
- 步骤写在**用户层面**（如 "Type 'Buy milk' into the input"），不要写 API 层面（如 "call `fill`"）；
- 可观测结果放进 `- expect:` 列表项 —— 生成阶段每条 expect 都会变成一条断言。

## 2. Generate：把 spec 变成测试

**目标**：读取 spec 文件，产出 Playwright 测试文件；若 spec 与实际应用已有漂移，可选择同步更新 spec。

### 2.1 输入

- **Spec 文件**，例如 `specs/basic-operations.plan.md`；
- **目标范围**：单条场景（如 `1.2`）、整个分组（`1`）或全部；
- **Seed 文件**：从场景所属分组的 `**Seed:**` 行读取。

### 2.2 生成单条场景

对每个目标场景**依序**逐个生成（**绝不并行** —— 场景共享同一个 seed 会话）：

```bash
PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli   # background
playwright-cli attach tw-XXXX
# resume

同样地，不要直接用 playwright-cli 打开应用 URL，始终经过测试以捕获自定义初始化。

接下来逐条走 spec 的 Steps:，把 spec 当作计划、把活的应用当作事实来源。如果某一步含糊（"click the button"——哪个 button？）、指向的元素已不存在、或与应用实际行为矛盾，应运用判断力：先把 spec 改成应用真实的样子，再继续走。在生成中途编辑 spec 是预期内行为。

每条动作都会打印等价的 Playwright TypeScript（机制见第 0 节）：

playwright-cli snapshot                         # find refs
playwright-cli fill e3 "John Doe"               # -> page.getByRole('textbox', {...}).fill(...)
playwright-cli press Enter
playwright-cli click e7

对 spec 里每条 - expect: 列表项，都要添加显式断言。随后把生成的代码收集起来，写到 spec 指定路径的测试文件：

// spec: specs/basic-operations.plan.md
// seed: tests/seed.spec.ts
import { test, expect } from './fixtures';   // or '@playwright/test' if no fixtures file

test.describe('Signing in and out', () => {
  test('should sign in', async ({ page }) => {
    // 1. Navigate to the application
    // (handled by the seed fixture)

    // 2. Type 'John Doe' into the username field
    await page.getByRole('textbox', { name: 'username' }).fill('John Doe');

    // 3. Type password
    await page.getByRole('textbox', { name: 'password' }).fill('TestPassword');

    // 4. Press Enter to submit
    await page.getByRole('textbox', { name: 'password' }).press('Enter');

    await expect(page.getByRole('heading')).toContainText('Welcome, John Doe!');
  });
});

生成规则：

• 一个测试一个文件。文件路径、describe 名与 test 名均照抄 spec（去掉序号前缀）；
• 每个带编号的步骤，在其动作前加一行 // N. <step text> 注释；
• describe 分组名照抄 spec 中的分组名（不加 1. 序号）；
• 项目有 fixtures 文件就 import ... from './fixtures'，否则从 '@playwright/test' 导入；
• 重要：进入下一个场景前，先关闭 CLI 会话并停止后台测试。

2.3 生成多条场景

循环执行 2.2，一次处理一个目标场景，并在每个场景之间重启 seed，保证每个测试都从干净的页面开始。由于每次生成的会话名唯一（tw-XXXX），这条流程可以安全并行——但务必保证每个测试运行都被停止。

2.4 运行生成的测试

生成完毕后，把新测试跑一遍：

PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts

任何失败都会进入第 3 节处理。

3. Heal：诊断、修复、对账

目标：修复失败的测试；如果应用的预期行为本身发生了变化，同步更新 spec。

3.1 找出失败用例

PLAYWRIGHT_HTML_OPEN=never npx playwright test

记录失败的 <file>:<line> 清单，一次只处理一个。不要尝试并行修复——共享状态与单一 CLI 会话使并行非常脆弱。

3.2 调试单个失败

在后台以 debug 模式运行单个失败测试，再 attach：

PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts:<line> --debug=cli
# wait for "Debugging Instructions" and the tw-XXXX session name
playwright-cli attach tw-XXXX

测试在起点暂停。逐步执行或运行到失败动作 / 断言的前一刻，然后开始诊断：

playwright-cli snapshot                # did the element change / move / rename?
playwright-cli console                 # app-side errors?
playwright-cli requests                # failed request? wrong payload?
playwright-cli show --annotate         # ask the user to point somewhere