测试

• 1: QMTV 测试规划（Go 版，P0 底册）
• 2: QMTV E2E 测试约定
• 3: QMTV E2E 场景清单（覆盖地图）

1 - QMTV 测试规划（Go 版，P0 底册）

回答移植需求②"基于现有项目先写单元测试——移植现有测试（如果有），或另写"。现状实测：冻结版零单测，仅 4 个 API 冒烟脚本（verify_*.js）覆盖 60/239 端点。结论：以 TDD 另写为主（pms 范式），verify 断言移植为集成冒烟底册，e2e 骨架按 pms 约定立。

1. 分层测试范式（对齐 pms backend）

2. 分域单测规划（先红后绿，TDD 顺序=P 期次）

3. verify_*.js 断言移植矩阵（约 60 端点 → Go 集成冒烟）

现有脚本逐断言移植为 Go 集成测试（integration 标签，dev-up 环境执行；脚本本身保留在冻结区不动）。「可测期次」= 该端点 Go 实现落地期。端点数为约数（唯一路径口径）：分项 ~28+~20+~6+~9 含同端点多场景重复计数，去重后约 60。

4. E2E 约定骨架（正式版 P5，按 pms docs/test 三文档体系）

• 初始世界：独立库 qmtv_e2e（dev-up 变体建库导 full+seed）；账号矩阵=seed 三账号+按需 API 注册；业务单据不进种子，一律 API 造数（防绕过状态机）。
• 外部 API 零真实调用（用户指令 2026-10-17，instructions.txt）：e2e/集成测试局限在本系统内，外部 API 调用会引起费用——全部 mock。LLM/图像/视频供应商一律走 Mock 通道（测试环境不配 model_endpoints 的 api_key，或显式 provider_routing=mock）；网络出口断言（providers 适配层的真实 HTTP 调用）用 httptest 本地假服务器验证协议形状，绝不打真实供应商；CI 环境保持零 Key（llm.isAvailable()==false 全站 Mock 路径），真实供应商连通性只允许人工在管理后台用「测试连接」单次验证。
• 确定性：时间用相对量；金额固定值；禁按自增 id 断言（qmtv 全字符串 ID 天然满足）。
• 隔离：e2e-reset（DROP/CREATE+导入）/e2e-seed（快恢复）；失败不自愈必须 reset；连跑两轮间隔 reset。
• 明令禁止：禁 sleep 等事件链（一律 pollUntil，超时 20s——评估 stage 推进/视频轮询场景）；禁 retry；5xx 直接抛响应体。
• 场景登记：docs/test/e2e-qmtv-场景清单.md 行格式对齐 pms（场景ID E2E-XXX-NN｜FSD 功能 ID｜主干路径｜关键断言｜现状）；缺陷修复覆盖优先并入现有场景加断言。
• Playwright 引入与否：P5 决策——前端冻结的前提下，API-first 断言册已覆盖回归需求；截图册（操作手册配图）可单独用 Playwright 走真 UI，不与断言册共用一行代码。（二十六期已落地：前端演进后 Playwright 双配置入位——断言册 11 用例〔auth 4/dashboard/generation 2/credits/admin/nav/spark；含 setup 册 14〕 + 截图管线，约定见 docs/test/e2e-测试约定.md；本条 P5「前端冻结」前提已随 TS 演进裁决失效，双配置即终态。二十七期勘误：二十五/二十六期宣称「13 用例」系计数漂移，11 为亲数权威口径。）

5. CI 闸门（scripts/ci.sh，已落地）

JUnit 双断言（场景总数≠期望也阻断）随 P5 e2e 落地引入。

2 - QMTV E2E 测试约定

二十六期（2026-10-19）立册。对齐 pms e2e 约定骨架，按 QMTV 单库场景裁剪。 场景覆盖地图见 e2e-qmtv-场景清单.md。

§1 初始世界

• 环境：bash scripts/dev/e2e/e2e-up.sh 一键起——独立库 qmtv_e2e（DROP/CREATE 即全量 reset）+ 端口 :3301（与 dev :3300 三隔离：库/端口/产物文件名，可共存）+ 托管 frontend/dist（每次 up 强制重建，永测当前 src）。停环境 e2e-down.sh；快恢复（不重建库）e2e-seed.sh。
• 种子自检：e2e-verify.sh 六项（healthz / admin·demo·producer 三账号登录 / models-active / style-presets）——绿才能跑用例。
• 账号矩阵：admin@qmtv.com（管理员，credits 100000）/ demo@qmtv.com / producer@xingmang.cn——密码=seed 公开演示值，不入新密。API 造数的辅助账号一律 e2e- 前缀 email；storageState 册（.auth/{admin,demo}.json）由 setup 项目真实 UI 登录一次产出，用例零登录（对抗 login 20/min 限流）。
• 确定性规则：未配置 model_endpoints → 生成类全走内置 Mock 同步 done（无轮询等待、无外部超时）；Mock 图像/视频字节含随机源——只断结构确定（卡片存在/URL 可达/台账行），绝不断素材内容。
• 预置种子：SQL seed（admin/demo+分销配置+计费 KV）+ Go seed（producer+示例任务链）。业务单据不进种子，一律 API 造数。
• 隔离与清理：用例各自造数各自收尾（集成侧 integCleanup 同纪律）；失败不自愈——重跑前 e2e-up；连跑两轮必须间隔 reset（credits 水位会漂移）。

明令禁止

1. 禁 sleep 等待 UI 条件——唯一合法等待面是 Playwright 自动等待/expect.poll/waitForEvent/pollUntil。豁免两处（登记）：①巡检类用例的路由间静置窗口（nav/admin 的 waitForTimeout(400/1500)、snapshots 截图前 waitForTimeout(800)——错误收集窗/渲染落定窗，非断言等待）；②截图前 networkidle。
2. 禁 retry——config retries: 0（pms flaky 规则：禁 retry 掩盖；修复优先序 改等待>改定位>改断言>最后才是 retry）。
3. 禁断全局计数/绝对余额——流水断言用 total 相对面 + 最新行身份；余额用 assertBal 恒等式（后端集成侧）。
4. 禁触 qmtv_main / pms_ / sw_main*——e2e 只操作 qmtv_e2e 单库（远程 139 共享实例纪律平移）。
5. SSE 面禁 networkidle——EventSource 长连接使 networkidle 永不触发；巡检用 load+双 rAF+静置窗口。

§2 可测性硬规则

• 断业务结果，不断文案细节：toast 只断关键短语（「拆解完成」「去字幕完成」）；选择器优先 role/placeholder/既有稳定 class，不批量加 testid（触碰面爆炸）；高频锚点按需单点补并在此登记。
• 失败留证：trace retain-on-failure + screenshot only-on-failure → e2e/.artifacts/（gitignore）。
• 断言/截图分文件一行不共用（pms 硬规则）：断言册 playwright.e2e.config.ts（testDir e2e，smoke 项目收 assertion/*.spec.ts）；截图册 playwright.config.ts（只收 snapshots.spec.ts）。
• API 侧错误信封直接抛（e2e/lib/client.ts apiReq）：非 2xx 抛响应体——静默吞错=测试说谎。
• 对话框断言用 waitForEvent('dialog')（once+变体捕获有竞态——auth.spec 负样本抓获）；LoginView 错误走原生 alert，业务 confirm 各页分散（WorkbenchView 仅 repaint 空描述分支）——用例写前先读该页 submit 源码，勿凭笔记推 dialogs。

§3 运行手册

bash scripts/dev/e2e/e2e-up.sh          # 起环境+种子自检（首次/失败后/连跑第二轮前必跑）
cd frontend
npm run test:e2e                        # 断言册（smoke，:3301）
npm run test:e2e:headed                 # 有头观察
npm run test:snapshots                  # 截图管线（二十七期手册出图）
npx playwright show-trace <trace.zip>   # 失败取证
bash scripts/dev/e2e/e2e-down.sh        # 停环境
bash scripts/ci.sh --e2e                # 全栈验收档（=--with-env 全部 + e2e 册）

§4 flaky 处理规则

• 72h 内同一用例红 ≥2 次 → 摘出开单，不得带红合入；
• 7 天未修 → 删用例（场景清单「自动化?」列同步回落「待实现」）；
• 关键用例落地必配负样本演练（涉及金额/回归锁/A1 教训面——改断言键名/路径必红才转正；A1 fixture 死键教训：键名错→锚死力失效）。巡检类（nav/admin 只读遍历）可豁免——harness 判死力由其它用例的有机红佐证（二十六期如实报告：admin.spec 无单独负样本，nav/auth/credits/dashboard/generation 五处有机红已证）。

§5 场景登记与回归锁

• 场景 ID 唯一（E2E-<模块>-<序号>），ID 标注于 spec 文件头注释（用例名可不带前缀）——清单与 spec 双侧 grep 对账按场景 ID 级（「自动化?=是」的行必须有对应 ID 的 spec 文件，清单「现状」列登记 ✅ 文件名）。〔二十七期勘误：原「用例同名对账」与实际不符——ID 在头注释非用例名，对账实为场景 ID 级 9=9+文件级 ✅ 列。〕
• 缺陷修复优先「并入现有场景加断言」（回归锁），不新开用例——本仓 /review-plan A 类「验收锚点」判死力机制直接挂此。
• 写链场景（导出 ZIP、充值审核、分销提现等）先登清单「待实现」行，后续期次升格。

3 - QMTV E2E 场景清单（覆盖地图）

行格式：场景 ID 唯一；「自动化?=是」行与 frontend/e2e/assertion/*.spec.ts 按场景 ID 级对账（清单 ID ↔ spec 文件头注释 ID+「现状」列 ✅ 文件名，与测试约定 §5 同口径；二十七期勘误：原「用例同名」与实情不符——用例 ID 在文件头注释非用例名）。 「FSD 功能 ID」列=场景↔功能规格双向对账锚（三十一期回填）——指向 prd/fsd-qmtv/ 各册 F<m>.<nn> 节；横切场景（积分/导航/截图）无单册归属标「横切」。 二十六期首批冒烟 8 场景全走 Mock 同步面（避开 SSE 依赖与长轮询）；写链场景登「待实现」后续升格。