e2e

E2E 测试

失败分类

每个 E2E 失败都恰好属于以下一种：

A. 不稳定（测试基础设施问题）

• 竞态条件、依赖时序的断言、过时的选择器、缺少等待
• 症状：重试后通过，间歇性失败

B. 过时（测试与实现不再匹配）

• 测试断言的是已被有意更改的旧行为；选择器引用了已移除的元素
• 症状：持续失败，应用运行正常

C. Bug（实现与规范不符）

• 测试正确断言了规范中定义的行为，但代码有误
• 只有存在可供验证的规范时，才能归类为 Bug
• 如果不存在规范，则归类为“未验证的失败”，并报告给用户

按类别修复的规则

不稳定问题的修复：

• 将 waitForTimeout 替换为自动等待的定位器
• 将脆弱的 CSS 选择器替换为 getByRole/getByLabel/getByTestId
• 使用 expect() 的 Web 优先断言修复竞态条件
• 修正 mock/route 的设置顺序（在导航之前）
• 绝不添加任意延迟——应修复底层的等待问题
• 绝不在断言外添加重试循环——使用框架内置的重试机制

过时问题的修复：

• 更新测试断言，使其符合当前（正确的）行为
• 更新选择器，使其匹配当前 DOM/API
• 绝不更改源代码——实现是正确的，过时的是测试

Bug 修复：

• 引用定义预期行为的规范章节
• 修复源代码，使其符合规范
• 修复完成前必须存在单元测试——如果缺少测试，应先编写测试（TDD）
• 绝不更改 E2E 断言来迎合有 Bug 的代码
• 没有规范依据时，绝不更改 API 契约或接口
• 如果不存在规范，请询问用户：是 Bug 还是过时的测试？

源代码边界

E2E 测试修复不得更改应用逻辑、API 契约、数据库架构或配置默认值。唯一例外：规范明确规定了正确行为，且单元测试覆盖了该修复的 Bug 修复。

工作流

步骤 1：了解测试基础设施

1. 查找 E2E 配置：playwright.config.ts、vitest.config.ts 或项目特定的设置
2. 阅读 package.json，找到规范的 E2E 命令
3. 检查是否需要并已运行开发服务器或 Tilt 环境
4. 查找规范文件：*.spec.md、docs/*.spec.md——这是判断 Bug 的事实来源

步骤 2：运行测试

# Playwright
yarn playwright test --reporter=line

# Or project-specific
yarn test:e2e

将失败整理为：

测试	文件	错误	类别
login flow	auth.spec.ts:42	等待选择器时超时	待定

步骤 3：分类

对于每个失败：阅读测试文件，阅读测试所涉及的源代码，检查是否有对应的规范文件，并指定类别（不稳定 / 过时 / Bug / 未验证）。

步骤 4：按类别修复

按以下顺序应用修复：先处理不稳定问题（解除对其他测试的阻塞），然后处理过时问题，最后处理 Bug。

步骤 5：重新运行并报告

## E2E Results

**Run**: `yarn test:e2e` on <date>
**Result**: X/Y passed

### Fixed
- FLAKY: `auth.spec.ts:42` - replaced waitForTimeout with getByRole wait
- OUTDATED: `profile.spec.ts:88` - updated selector after header redesign
- BUG: `transfer.spec.ts:120` - fixed amount validation per SPEC.md#transfers

### Remaining Failures
- UNVERIFIED: `settings.spec.ts:55` - no spec, needs user decision

### Unit Tests Added
- `src/transfer.test.ts` - amount validation edge cases (covers BUG fix)

参见 testing-best-practices，了解异步处理、不稳定问题分类和预检模式。