frontend-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Testing

前端测试

Unlock reliable confidence fast: enable safe refactors by choosing the right test layer, making the app observable, and eliminating nondeterminism so failures are actionable.

快速获取可靠的测试信心：通过选择合适的测试层级、让应用可观测、消除不确定性，确保测试失败时能准确定位问题，从而安全地进行重构。

Philosophy: Confidence Per Minute

核心理念：高效获取测试信心

Frontend tests fail for two reasons: the product is broken, or the test is lying. Your job is to maximize signal and minimize “test is lying”.

Before writing a test, ask:

What user risk am I covering (money, progression, auth, data loss, “can’t start” crashes)?
What’s the narrowest layer that catches this bug class (pure logic vs UI vs full browser)?
What nondeterminism exists (time, RNG, async loading, network, animations, fonts, GPU)?
What “ready” signal can I wait on besides
```
setTimeout
```
?
What should a failure print/screenshot so it’s diagnosable in CI?

Core principles:

Test the contract, not the implementation: assert stable user-meaningful outcomes and public seams.
Prefer determinism over retries: make time/RNG/network controllable; remove flake at the source.
Observe like a debugger: console errors, network failures, screenshots, and state dumps on failure.
One critical flow first: a reliable smoke test beats 50 flaky tests.

前端测试失败有两种原因：产品本身存在问题，或者测试结果有误。你的工作是最大化有效信号，最小化“测试误报”。

编写测试前，请思考：

我要覆盖哪些用户风险（资金损失、流程中断、认证失败、数据丢失、“无法启动”崩溃等）？
能捕获这类问题的最精简测试层级是什么（纯逻辑层 vs UI层 vs 全浏览器层）？
存在哪些不确定性因素（时间、随机数生成、异步加载、网络、动画、字体、GPU渲染）？
除了
```
setTimeout
```
，我可以等待哪些“就绪”信号？
测试失败时，应该输出哪些日志/截图才能在CI环境中快速诊断问题？

核心原则：

测试契约而非实现细节：断言稳定的、对用户有意义的结果和公共接口。
优先确保确定性而非重试：让时间/随机数生成/网络可控制；从根源消除不稳定测试。
像调试器一样观测：测试失败时捕获控制台错误、网络请求失败、截图和状态快照。
先覆盖核心流程：一个可靠的冒烟测试胜过50个不稳定的测试。

Workflow Decision Tree

工作流决策树

Pick the test type by the cheapest layer that provides the needed confidence:

Unit tests (fastest): pure functions, reducers, validators, math, pathfinding, deterministic simulation steps.
Component/integration tests (medium): UI behavior with mocked IO (React Testing Library / Vue Testing Library / Testing Library DOM).
E2E tests (slowest, highest confidence): critical user flows across routing, storage, real bundling/runtime.
Visual regression (specialized): layout/pixel regressions; for canvas/WebGL, only after locking determinism.
A11y checks: great for DOM UIs; limited value for pure canvas unless you expose accessible DOM overlays.

选择能提供所需信心的最低成本测试类型：

单元测试（速度最快）：纯函数、reducer、验证器、数学计算、路径查找、确定性模拟步骤。
组件/集成测试（速度中等）：模拟IO的UI行为测试（使用React Testing Library / Vue Testing Library / Testing Library DOM）。
E2E测试（速度最慢，信心最高）：跨路由、存储、真实打包/运行时的关键用户流程。
视觉回归测试（专用测试）：布局/像素级回归；针对canvas/WebGL，需先确保确定性才能使用。
无障碍测试：对DOM类UI效果极佳；对纯canvas UI价值有限，除非暴露可访问的DOM覆盖层。

Quick Start (Any Project)

快速入门（适用于任何项目）

Define 1 smoke flow: “page loads → user can start → one key action works”.
Choose runner:
- Prefer Playwright for browser E2E + screenshots.
- Prefer Testing Library for DOM component behavior.
- Prefer unit tests for logic you can run without a browser.
Add a “ready” signal in the app (DOM marker, window flag, or game event) and wait on that.
Fail loudly: treat console errors and failed requests as test failures.
Stabilize: seed RNG, freeze time, fix viewport/DPR, disable animations, and remove network variability.

定义1个冒烟测试流程："页面加载 → 用户可启动应用 → 完成一个关键操作"。
选择测试运行器：
- 浏览器E2E测试+截图优先选用Playwright。
- DOM组件行为测试优先选用Testing Library。
- 无需浏览器运行的逻辑优先选用单元测试。
在应用中添加“就绪”信号（DOM标记、window全局变量或游戏事件），并在测试中等待该信号。
让测试失败时发出明确警报：将控制台错误和请求失败视为测试失败。
稳定测试环境：设置随机数生成种子、冻结时间、固定视口/设备像素比、禁用动画、消除网络差异。

Playwright Patterns (Especially Useful For Games)

Playwright使用模式（尤其适用于游戏）

Use Playwright when you need “real browser” confidence:

Drive input via mouse/keyboard/touch; treat the canvas like the user does.
Add a test seam: expose a small, stable test API on
```
window
```
(read-only state + a few commands).
Prefer
```
waitForFunction
```
-style readiness over sleep; gate on “scene ready” / “assets loaded” / “first frame rendered”.
For screenshots: lock viewport, device scale factor, fonts, and animation timing.
For 9-slice / canvas UI regressions: add a dedicated UI harness scene/page and assert via targeted screenshots (see
```
references/phaser-canvas-testing.md
```
).

If using the Playwright MCP tools (browser automation inside Codex), follow the same mindset:

Use

browser_console_messages

and

browser_network_requests

to catch silent failures.

Use
```
browser_evaluate
```
to assert
```
window.__TEST__
```
state and to set up deterministic mode.
Use
```
browser_take_screenshot
```
for visual assertions after determinism is enforced.

当需要“真实浏览器”级别的测试信心时，使用Playwright：

通过鼠标/键盘/触摸模拟用户输入；将canvas视为用户操作的界面。
添加测试接口：在
```
window
```
对象上暴露一个小型、稳定的测试API（只读状态+少量命令）。
优先使用
```
waitForFunction
```
方式等待就绪，而非休眠；等待“场景就绪”/“资源加载完成”/“第一帧渲染完成”。
截图时：固定视口、设备缩放因子、字体和动画时长。
针对9-slice/canvas UI回归：添加专用的UI测试场景/页面，通过定向截图进行断言（详见
```
references/phaser-canvas-testing.md
```
）。

如果使用Playwright MCP工具（Codex内的浏览器自动化），遵循相同思路：

使用

browser_console_messages

和

browser_network_requests

捕获静默失败。

使用
```
browser_evaluate
```
断言
```
window.__TEST__
```
状态并设置确定性模式。
在确保确定性后，使用
```
browser_take_screenshot
```
进行视觉断言。

Reconnaissance-Then-Action (Borrowed From Real Debugging)

先侦察后操作（借鉴真实调试思路）

When a UI is dynamic, don’t guess selectors—recon first, then act:

Quick decision guide:

Task → Is it static HTML (no JS runtime needed)?
  ├─ Yes → read the HTML to find stable selectors/content, then automate
  └─ No  → treat as dynamic: run the app, wait for readiness, then inspect rendered state

Navigate and wait for readiness:
- For many webapps: wait for a meaningful “loaded” element (preferred).
- ```
networkidle
```
  can help for SPAs, but avoid it if the app uses websockets/polling.
Capture evidence (what the user actually sees):
- screenshot (full page for DOM; targeted for canvas)
- console errors + failed requests
Discover selectors from the rendered state:
- prefer role/text/label selectors over brittle CSS
Execute actions using discovered selectors and re-check state.

Common pitfall: ❌ Inspect/interact before the app is ready. ✅ Wait on an explicit ready signal (DOM marker or

window.__TEST__.ready

), not a sleep.

当UI是动态的，不要猜测选择器——先侦察，再操作：

快速决策指南：

任务 → 是否为静态HTML（无需JS运行时）？
  ├─ 是 → 读取HTML找到稳定的选择器/内容，然后自动化操作
  └─ 否 → 视为动态内容：启动应用，等待就绪，再检查渲染后的状态

导航并等待就绪：
- 对于大多数Web应用：等待有意义的“已加载”元素（优先选择）。
- ```
networkidle
```
  可用于单页应用，但如果应用使用websockets/轮询则避免使用。
捕获证据（用户实际看到的内容）：
- 截图（DOM页面用全屏截图；canvas用定向截图）
- 控制台错误+请求失败记录
从渲染后的状态中发现选择器：
- 优先使用角色/文本/标签选择器，而非脆弱的CSS选择器
使用发现的选择器执行操作，并重新检查状态

常见误区： ❌ 在应用就绪前就检查/交互。 ✅ 等待明确的就绪信号（DOM标记或

window.__TEST__.ready

），而非休眠。

Server Lifecycle Helper (Playwright E2E)

服务器生命周期助手（Playwright E2E测试）

When the dev server isn’t already running, use the bundled helper as a black box:

Run
```
python scripts/with_server.py --help
```
first.
Start one (or multiple) servers, wait for their ports, then run your test command.

Example:

bash

python scripts/with_server.py --server "npm run dev" --port 5173 -- npm test

当开发服务器未运行时，使用内置的助手工具（无需了解内部实现）：

先运行
```
python scripts/with_server.py --help
```
查看帮助。
启动一个（或多个）服务器，等待端口就绪，再运行测试命令。

示例：

bash

python scripts/with_server.py --server "npm run dev" --port 5173 -- npm test

Flake Reduction Checklist

不稳定测试修复清单

Replace sleeps with explicit readiness conditions.
Control time (
```
Date.now
```
, timers), RNG, and animation loops.
Make network deterministic (mock, record/replay, or run against a seeded local backend).
Eliminate “first-run” differences (asset caches, fonts) or warm them explicitly.
Lock environment: viewport, DPR, locale/timezone, and rendering settings.

用明确的就绪条件替换休眠。
控制时间（
```
Date.now
```
、定时器）、随机数生成和动画循环。
让网络请求可预测（模拟、记录/重放，或针对本地种子化后端运行测试）。
消除“首次运行”差异（资源缓存、字体），或提前预热。
锁定环境：视口、设备像素比、区域/时区、渲染设置。

Anti-Patterns to Avoid

需避免的反模式

❌ Testing the wrong layer: E2E tests for pure logic. Better: unit tests for logic; reserve E2E for integration contracts.

❌ Testing implementation details: asserting DOM structure/classnames or internal engine objects. Better: assert user-meaningful outputs (text, navigation, score/HP changes) or a small stable test seam.

❌ Sleep-driven tests:

wait 2s then click

. Better: wait on explicit readiness (DOM marker, event,

window

flag).

❌ Uncontrolled randomness: RNG/time-based behaviors in assertions. Better: seed RNG, freeze time, and assert stable invariants.

❌ Pixel snapshots without determinism (especially canvas/WebGL). Better: add deterministic mode first; then screenshot selectively.

❌ Snapshot explosion: hundreds of snapshots that no one can interpret. Better: keep snapshots targeted (critical screens); prefer specific assertions for behavior.

❌ Retries as a strategy: “just bump retries in CI”. Better: fix readiness and determinism; use retries only as temporary guardrails.

❌ 错误的测试层级：用E2E测试纯逻辑。更好的做法：用单元测试测试逻辑；将E2E测试保留给集成契约。

❌ 测试实现细节：断言DOM结构/类名或内部引擎对象。更好的做法：断言对用户有意义的输出（文本、导航、分数/生命值变化）或小型稳定的测试接口。

❌ 依赖休眠的测试：“等待2秒后点击”。更好的做法：等待明确的就绪信号（DOM标记、事件、

window

全局变量）。

❌ 未受控的随机性：断言中包含基于随机数/时间的行为。更好的做法：设置随机数生成种子、冻结时间，断言稳定的不变量。

❌ 无确定性的像素快照（尤其针对canvas/WebGL）。更好的做法：先添加确定性模式；再选择性地进行截图。

❌ 快照爆炸：数百个无人能解读的快照。更好的做法：保持快照针对性（关键屏幕）；优先用特定断言测试行为。

❌ 将重试作为解决方案：“在CI中增加重试次数即可”。更好的做法：修复就绪逻辑和确定性；仅将重试作为临时防护措施。

Variation Guidance (Prevent One-Size-Fits-All)

差异化指导（避免一刀切）

Vary the approach based on:

UI type: DOM app vs canvas/WebGL game vs hybrid.
Risk: core revenue/progression flows get E2E first; edge UI polish gets component tests.
CI constraints: headless-only, limited GPU, slow CPUs, no audio devices.
Test seam availability: if you can add a stable
```
window.__TEST__
```
API, assert state; if not, stick to black-box input/output.

根据以下因素调整测试方法：

UI类型：DOM应用 vs canvas/WebGL游戏 vs 混合应用。
风险等级：核心营收/流程优先用E2E测试；边缘UI优化用组件测试。
CI约束：仅支持无头模式、GPU受限、CPU缓慢、无音频设备。
测试接口可用性：如果可以添加稳定的
```
window.__TEST__
```
API，则断言状态；否则坚持黑盒输入/输出测试。

Remember

谨记

You can make almost any frontend (including canvas/WebGL games) testable by adding a tiny, stable seam for readiness + state. This skill is meant to empower creative, high-signal testing rather than cargo-cult checklists. Aim for tests that are boring to maintain: deterministic, explicit about readiness, and rich in failure evidence. One reliable smoke test is the foundation; everything else compounds from there.

通过添加一个小型、稳定的就绪+状态测试接口，几乎所有前端应用（包括canvas/WebGL游戏）都可以被测试。本技能旨在赋能高效、高信号的测试，而非生搬硬套 checklist。目标是打造易于维护的测试：确定性、就绪逻辑明确、失败时提供丰富证据。一个可靠的冒烟测试是基础；其他所有测试都在此之上构建。

Bundled Resources

内置资源

Read these only when needed:

```
references/playwright-mcp-cheatsheet.md
```
: patterns for using Playwright MCP tools for assertions, waiting, and diagnostics.
```
references/phaser-canvas-testing.md
```
: deterministic mode + hooks for Phaser/canvas/WebGL games.
```
references/flake-reduction.md
```
: deeper flake triage and stabilization tactics.

Use these scripts as black boxes (run

--help

first; don’t read source unless you must):

```
scripts/with_server.py
```
: start/wait/stop one or more dev servers around a test command.
```
scripts/imgdiff.py
```
: lightweight screenshot diff helper (requires
```
pip install pillow
```
).

仅在需要时阅读以下内容：

```
references/playwright-mcp-cheatsheet.md
```
：使用Playwright MCP工具进行断言、等待和诊断的模式。
```
references/phaser-canvas-testing.md
```
：Phaser/canvas/WebGL游戏的确定性模式+钩子。
```
references/flake-reduction.md
```
：更深入的不稳定测试分类和稳定化策略。

将以下脚本视为黑盒工具（先运行

--help

查看帮助；除非必要，否则无需阅读源码）：

```
scripts/with_server.py
```
：在测试命令前后启动/等待/停止一个或多个开发服务器。
```
scripts/imgdiff.py
```
：轻量级截图对比助手（需要先
```
pip install pillow
```
）。