e2e

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

E2E Testing

E2E 测试

Principles (Always Active)

核心原则（始终适用）

These apply whenever working with e2e tests, test failures, or test flakiness:

以下原则适用于所有与e2e测试、测试失败或测试不稳定相关的工作场景：

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

每一次e2e测试失败都属于以下类型之一：

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

竞态条件、依赖时序的断言
UI变更后失效的选择器
缺失等待逻辑、错误的等待目标
网络时序问题、Mock设置顺序错误
症状：重试后通过，间歇性失败

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

测试断言的是已被有意修改的旧行为
选择器引用了已移除/重命名的元素
API契约已变更，但测试未更新
症状：持续失败，但应用本身运行正常

C. Bug（实现与规格说明不符）

测试正确断言了规格说明中定义的行为，但代码存在错误
只有在存在可对照的规格说明时，才能归类为Bug
如果没有规格说明，则归类为“未验证失败”并告知用户

Fix Rules by Category

按类型分类的修复规则

Flaky fixes:

Replace
```
waitForTimeout
```
with auto-waiting locators
Replace brittle CSS selectors with
```
getByRole
```
/
```
getByLabel
```
/
```
getByTestId
```
Fix race conditions with
```
expect()
```
web-first assertions
Fix mock/route setup ordering (before navigation)
Never add arbitrary delays - fix the underlying wait
Never weaken assertions to make flaky tests pass
Never add retry loops around assertions - use the framework's built-in retry

Outdated fixes:

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

Bug fixes:

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?

不稳定测试修复：

用自动等待定位器替换
```
waitForTimeout
```
用
```
getByRole
```
/
```
getByLabel
```
/
```
getByTestId
```
替换脆弱的CSS选择器
使用基于Web的
```
expect()
```
断言修复竞态条件
修复Mock/路由设置顺序（需在导航前完成）
绝不要添加任意延迟 - 修复底层的等待逻辑问题
绝不要弱化断言来让不稳定测试通过
绝不要在断言周围添加重试循环 - 使用框架内置的重试机制

过时测试修复：

更新测试断言以匹配当前（正确的）行为
更新选择器以匹配当前DOM/API
绝不要修改源代码 - 实现是正确的，测试已过时

Bug修复：

引用定义了预期行为的规格说明章节
修改源代码以匹配规格说明
修复完成前必须存在单元测试
- 如果已有单元测试，运行它们以确认修复效果
- 如果没有单元测试，先编写单元测试（测试驱动开发，TDD）
绝不要修改e2e断言以适配有Bug的代码
绝不要修改API契约或接口，除非有规格说明支持
如果没有规格说明，询问用户：这是Bug还是过时测试？

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.

E2E测试修复不得修改以下内容：

应用逻辑或业务规则
API契约、请求/响应格式
数据库 schema 或迁移脚本
配置默认值

唯一例外：当有规格说明明确定义了正确行为，且单元测试覆盖了修复内容时，可修改源代码以修复Bug。

Workflow (When Explicitly Running E2E)

工作流程（当明确运行E2E测试时）

Step 1: Discover Test Infrastructure

步骤1：探索测试基础设施

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

找到e2e配置文件：
```
playwright.config.ts
```
、
```
vitest.config.ts
```
或项目特定的设置文件
查看
```
package.json
```
获取标准的e2e测试命令
检查是否需要并已启动开发服务器或Tilt环境
找到规格文件：
```
*.spec.md
```
、
```
docs/*.spec.md
```
- 这是判断是否为Bug的唯一依据

Step 2: Run Tests

步骤2：运行测试

Run with minimal reporter to avoid context overflow:

bash

undefined

使用轻量级报告器运行测试，避免上下文溢出：

bash

undefined

Playwright

yarn playwright test --reporter=line

Or project-specific

或项目特定命令

yarn test:e2e


If a filter is specified, apply it:
```bash
yarn playwright test --reporter=line -g "transfer"
yarn test:e2e -- --grep "transfer"

Parse failures into:

Test	File	Error	Category
`login flow`	`auth.spec.ts:42`	timeout waiting for selector	TBD

yarn test:e2e


如果指定了过滤条件，应用该条件：
```bash
yarn playwright test --reporter=line -g "transfer"
yarn test:e2e -- --grep "transfer"

将失败情况整理为如下表格：

测试用例	文件	错误信息	分类
`login flow`	`auth.spec.ts:42`	等待选择器超时	待确定

Step 3: Categorize

步骤3：分类

For each failure:

Read the test file
Read the source code it exercises
Check for a corresponding spec file
Assign category: flaky, outdated, bug, or unverified

针对每一次失败：

阅读测试文件
阅读测试所涉及的源代码
检查是否存在对应的规格文件
分类为：不稳定测试、过时测试、Bug或未验证

Step 4: Fix by Category

步骤4：按类型修复

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

按照上述核心原则依次应用修复：

不稳定测试 - 优先修复测试基础设施问题（可解锁其他测试）
过时测试 - 更新过时的断言
Bug - 在规格说明和单元测试的约束下进行修复

Step 5: Re-run and Report

步骤5：重新运行并报告

After all fixes, re-run the suite:

undefined

完成所有修复后，重新运行测试套件：

undefined

E2E Results

E2E 测试结果

Run:

yarn test:e2e

on <date> Result: X/Y passed

运行命令：<日期> 执行

yarn test:e2e

结果：X/Y 测试通过

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

FLAKY:
```
auth.spec.ts:42
```
- 用getByRole等待替换waitForTimeout
OUTDATED:
```
profile.spec.ts:88
```
- 头部重构后更新选择器
BUG:
```
transfer.spec.ts:120
```
- 根据SPEC.md#transfers修复金额验证逻辑

Remaining Failures

剩余失败

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

UNVERIFIED:
```
settings.spec.ts:55
```
- 无对应规格说明，需用户确认

Unit Tests Added

新增单元测试

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

undefined

```
src/transfer.test.ts
```
- 金额验证边界用例（覆盖Bug修复）

undefined