E2E测试完整指南：分类、修复原则与工作流程 | 端到端测试最佳实践 | SkillsMDE2E测试完整指南：分类、修复原则与工作流程 | 端到端测试最佳实践
e2e by 0xbigboss/claude-code
npx skills add https://github.com/0xbigboss/claude-code --skill e2e🇨🇳中文介绍
E2E 测试
基本原则（始终有效）
这些原则适用于处理 e2e 测试、测试失败或测试不稳定性时：
失败分类
每个 e2e 失败都属于以下情况之一：
A. 不稳定的（测试基础设施问题）
- 竞态条件、依赖于时间的断言
- UI 更改后选择器过时
- 缺少等待、等待目标不正确
- 网络时序、模拟设置顺序
- 症状：重试时通过，间歇性失败
B. 过时的（测试不再匹配实现）
- 测试断言了已故意更改的旧行为
- 选择器引用了已移除/重命名的元素
- API 契约已更改，测试未更新
- 症状：持续失败，应用程序工作正常
C. 缺陷（实现不匹配规范）
- 测试正确断言了规范定义的行为，但代码有误
- 仅当存在用于验证的规范时，才归类为缺陷
- 如果不存在规范，则归类为“未验证的失败”并向用户报告
按类别修复规则
不稳定的修复：
- 用自动等待定位器替换
waitForTimeout
- 用
getByRole/getByLabel/getByTestId 替换脆弱的 CSS 选择器
🇺🇸English
E2E Testing
Principles (Always Active)
These apply whenever working with e2e tests, test failures, or test flakiness:
Failure Taxonomy
Every e2e failure is exactly one of:
A. Flaky (test infrastructure issue)
- Race conditions, timing-dependent assertions
- Stale selectors after UI changes
- Missing waits, incorrect wait targets
- Network timing, mock setup ordering
- Symptom: passes on retry, fails intermittently
B. Outdated (test no longer matches implementation)
- Test asserts old behavior that was intentionally changed
- Selectors reference removed/renamed elements
- API contract changed, test wasn't updated
- Symptom: consistent failure, app works correctly
C. Bug (implementation doesn't match spec)
- Test correctly asserts spec'd behavior, code is wrong
- Only classify as bug when a spec exists to validate against
- If no spec exists, classify as "unverified failure" and report to the user
Fix Rules by Category
Flaky fixes:
- Replace
waitForTimeout with auto-waiting locators
- Replace brittle CSS selectors with //
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
expect() 的 web-first 断言修复竞态条件修复模拟/路由设置顺序（在导航之前）切勿添加任意延迟 - 修复底层的等待问题切勿削弱断言以使不稳定的测试通过切勿在断言周围添加重试循环 - 使用框架内置的重试机制
- 更新测试断言以匹配当前（正确的）行为
- 更新选择器以匹配当前的 DOM/API
- 切勿更改源代码 - 实现是正确的，测试是过时的
- 引用定义预期行为的规范章节
- 修复源代码以匹配规范
- 修复完成前必须存在单元测试
- 如果存在单元测试，运行它们以确认
- 如果不存在单元测试，首先编写它们（TDD）
- 切勿更改 e2e 断言以匹配有缺陷的代码
- 切勿在没有规范支持的情况下更改 API 契约或接口
- 如果不存在规范，询问用户：是缺陷还是过时的测试？
源代码边界
- 应用程序逻辑或业务规则
- API 契约、请求/响应结构
- 数据库模式或迁移
- 配置默认值
唯一的例外：缺陷修复，其中规范明确定义了正确行为，并且单元测试覆盖了该修复。
工作流程（当明确运行 E2E 时）
步骤 1：发现测试基础设施
- 找到 e2e 配置：
playwright.config.ts、vitest.config.ts 或项目特定的设置
- 阅读
package.json 以找到规范的 e2e 命令
- 检查是否需要以及是否正在运行开发服务器或 Tilt 环境
- 找到规范文件：
*.spec.md、docs/*.spec.md - 用于缺陷决策的真相来源
步骤 2：运行测试
# Playwright
yarn playwright test --reporter=line
# 或项目特定的
yarn test:e2e
yarn playwright test --reporter=line -g "transfer"
yarn test:e2e -- --grep "transfer"
| 测试 | 文件 | 错误 | 类别 |
|---|
login flow | auth.spec.ts:42 | 等待选择器超时 | 待定 |
步骤 3：分类
- 阅读测试文件
- 阅读它执行的源代码
- 检查相应的规范文件
- 分配类别：不稳定的、过时的、缺陷或未验证的
步骤 4：按类别修复
- 不稳定的 - 首先修复测试基础设施问题（解除其他测试的阻塞）
- 过时的 - 更新过时的断言
- 缺陷 - 通过规范 + 单元测试门控进行修复
步骤 5：重新运行并报告
## E2E 结果
**运行**：`yarn test:e2e` 于 <日期>
**结果**：X/Y 通过
### 已修复
- 不稳定的：`auth.spec.ts:42` - 将 waitForTimeout 替换为 getByRole 等待
- 过时的：`profile.spec.ts:88` - 在标题重新设计后更新了选择器
- 缺陷：`transfer.spec.ts:120` - 根据 SPEC.md#transfers 修复了金额验证
### 剩余失败
- 未验证的：`settings.spec.ts:55` - 无规范，需要用户决定
### 添加的单元测试
- `src/transfer.test.ts` - 金额验证边界情况（覆盖缺陷修复）
getByRole
getByLabel
getByTestId
Fix race conditions with expect() web-first assertionsFix mock/route setup ordering (before navigation)Never add arbitrary delays - fix the underlying waitNever weaken assertions to make flaky tests passNever add retry loops around assertions - use the framework's built-in retry
- Update test assertions to match current (correct) behavior
- Update selectors to match current DOM/API
- Never change source code - the implementation is correct, the test is stale
- Quote the spec section that defines expected behavior
- Fix the source code to match the spec
- Unit tests MUST exist before the fix is complete
- If unit tests exist, run them to confirm
- If unit tests don't exist, write them first (TDD)
- Never change e2e assertions to match buggy code
- Never change API contracts or interfaces without spec backing
- If no spec exists, ask the user: bug or outdated test?
Source Code Boundary
E2e test fixes must not change:
- Application logic or business rules
- API contracts, request/response shapes
- Database schemas or migrations
- Configuration defaults
The only exception: bug fixes where a spec explicitly defines the correct behavior and unit tests cover the fix.
Workflow (When Explicitly Running E2E)
Step 1: Discover Test Infrastructure
- Find e2e config:
playwright.config.ts, vitest.config.ts, or project-specific setup
- Read
package.json for the canonical e2e command
- Check if dev server or Tilt environment is required and running
- Find spec files:
*.spec.md, docs/*.spec.md - source of truth for bug decisions
Step 2: Run Tests
Run with minimal reporter to avoid context overflow:
# Playwright
yarn playwright test --reporter=line
# Or project-specific
yarn test:e2e
If a filter is specified, apply it:
yarn playwright test --reporter=line -g "transfer"
yarn test:e2e -- --grep "transfer"
| Test | File | Error | Category |
|---|
login flow | auth.spec.ts:42 | timeout waiting for selector | TBD |
Step 3: Categorize
- Read the test file
- Read the source code it exercises
- Check for a corresponding spec file
- Assign category: flaky, outdated, bug, or unverified
Step 4: Fix by Category
Apply fixes following the Principles above, in order:
- Flaky - fix test infrastructure issues first (unblocks other tests)
- Outdated - update stale assertions
- Bug - fix with spec + unit test gate
Step 5: Re-run and Report
After all fixes, re-run the suite:
## 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)
AI新闻播客制作技能：实时新闻转对话式播客脚本与音频生成
