前端测试方案

dashboard-v6 · React 19 + Vite + Ant Design · 记录于 2026-09-07 实现位于独立目录 mint/dashboard-test，运行方式见 README

目标

把「人工点页面 + 肉眼看 console」的手工测试，交给 AI 助手（Claude Code）在容器内自动完成，同时不改动 dashboard-v6 的依赖——测试代码与依赖全部隔离在独立目录 mint/dashboard-test。

层面	选择	说明
浏览器驱动	Playwright Test（headless chromium）	独立目录 `dashboard-test` 的 devDependencies
运行位置	开发容器内	与 dev server 同一网络，直连 127.0.0.1
交互方式	`@playwright/test` spec 文件	而非 MCP 逐步操作，理由见下
采集内容	console 日志、pageerror、HTTP 4xx/5xx、请求失败、截图

MCP 每步一次工具调用，交互性确实更好，但有四个代价：

上下文消耗大 —— 每步返回整页 accessibility snapshot，中等复杂度页面就是几万 token，点十次即耗尽上下文。脚本方式一次跑完只回来十几行日志。
每步一次往返 —— 「登录 → 列表 → 筛选 → 详情 → 断言」= 5 次调用。测已知流程时纯浪费。
不留资产 —— 点完即逝，下次重测要从头再点；脚本是文件，可重跑、可沉淀为回归测试。
不确定性 —— 同样指令两次可能点到不同元素；脚本里的选择器是确定的。

结论：探索性调试（不知道页面哪坏了、需要边看边试）可临时启用 MCP；已知流程的重复验证一律用脚本。 当前默认走脚本。

测试是一个独立的 npm 工程 mint/dashboard-test，与 dashboard-v6 完全隔离：

cd dashboard-test
npm install                      # @playwright/test + @types/node，均在 devDependencies
npx playwright install chromium

dashboard-v6 的 package.json、package-lock.json、node_modules 零改动。

由 AI 在后台启动，端口如下：

登录：src/tests/auth.setup.ts 作为 setup project 跑一次登录， storageState 存到 playwright/.auth/user.json，各用例通过 dependencies: ['setup'] 复用（官方推荐模式）。
日志采集：src/lib/collect.ts 挂 console / pageerror / requestfailed / response>=400，并过滤掉 antd、React 开发态的已知废弃警告，只留真正值得看的内容。这是替代"人肉盯控制台"的关键。
已知缺陷写成断言：发现的 bug 直接写进 expect，注释标注 BUG 编号，修复前保持红灯，修复后自动变绿——测试同时充当回归网。
失败留证：trace: 'retain-on-failure' + video: 'retain-on-failure'，失败用例可用 npx playwright show-trace 逐帧回放。

路径	内容
`src/tests/<路由名>.spec.ts`	一个路由一个 spec
`src/tests/auth.setup.ts`	登录并保存 storageState
`src/lib/collect.ts`	日志采集与噪音过滤
`README.md`	运行方式与环境变量
`documents/development/testing-strategy.md`	本文：方案取舍与约定
`documents/testlog/<路由名>_<时间戳>.md`	每次测试的日志，待修项用 `- [ ]` 代办标记
`documents/testlog/assets/<路由名>_<时间戳>/`	该次测试的截图，在 md 中内嵌引用

目录布局参照 dashboard-v6：代码在 src/，文档在 documents/。

时间戳格式 YYYYMMDD_HHMMSS，例：channel_20260907_034904.md。

测试日志固定结构：概览表格 → 结论 → 一、通过的功能（含截图）→ 二、待修复（每条一个 - [ ] 代办，含日志片段、截图、定位到文件行号的原因、修复方向）→ 三、未覆盖（破坏性操作等）。

破坏性操作（新建、保存、删除）在开发机上实际执行。约定：

登录态：harness.login() 走一遍登录流程后用 context.storageState() 存到 .auth.json（已 gitignore）复用。测试账号通过 E2E_USER / E2E_PASS 传入。
脚本入库：已迁到独立工程 mint/dashboard-test，随代码进 git，依赖隔离在自己的 package.json。
端口冲突：5173 常被宿主机上已有的 dev server 占用，注意避免重复启动。

若接受修改 package.json，业界主流组合为：

层面	方案	备注
单元/组件	Vitest + React Testing Library	已基本取代 Jest；browser mode 在真实浏览器跑组件测试
E2E	Playwright	✅ 已采用（本目录）
API mock	MSW	网络层拦截，单测与浏览器共用一套 handler
视觉回归	Playwright `toHaveScreenshot()`	需团队协作看 diff 才上 Chromatic / Percy

E2E 一层已落地。单元/组件测试要落地必须动 dashboard-v6 的 package.json，待需要时再议。