openclaw/waoowaoo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a105c96444cec2382625dca4984704d1ac46086
waoowaoo/SYSTEM_BEHAVIOR_LEVEL_TEST_MASTER_PLAN.md

38 KiB
Raw Blame History

你必须按照目前的md文件详细执行我们的代码修改计划，且必须时刻关注，维护本次md文档，确保该文档能始终保持最新，和我们代码库保持完全一致，除非用户要求，否则默认禁止打补丁，禁止兼容层，我们需要的是简洁干净可扩展的系统，我们这个系统目前没有人用，可以一次性全量，彻底，不留遗留的修改，并且需要一次性完成所有，禁止停下，禁止自己停止任务，一次性完成所有内容。

全系统真实行为级测试替换执行主计划

版本: v1.0
仓库: /Users/earth/Desktop/waoowaoo
最后更新: 2026-02-25
定位: 用真实“行为结果断言”替换结构级/字符串级测试，覆盖全系统功能回归链路

1: 项目目标

1.1 为什么要做

当前系统历史回归集中在“链路行为错了但结构没变”的问题：

  • 编辑角色/场景后字段未正确回写。
  • 上传参考图后没有按参考图生成。
  • 三视图后缀、locale、meta、referenceImages 在 route -> task -> worker 过程中丢失。
  • 前端状态看起来正常，但真实任务状态或写库结果错误。

现有部分测试仍是结构级（例如检查源码里是否包含 apiHandler、submitTask、maybeSubmitLLMTask，或者仅检查 TASK_TYPE -> queue 映射），这类测试无法拦截真实业务回归。

1.2 需要达到的目标

把测试体系升级为“行为级为主、结构级为辅”：

  • 每个关键功能都必须有“输入 -> 执行 -> 输出/副作用”的断言。
  • 断言必须检查具体值（写入字段值、payload 值、response 值），不接受只断言“被调用了”。
  • route、task type、worker handler 三层都要有行为级覆盖矩阵。
  • 外部 API 全 fake，不走真实高成本调用。

1.3 本次扫描结论（基于当前仓库）

  • API 路由文件覆盖面: src/app/api/**/route.ts（全量 catalog 已维护）。
  • Worker 文件覆盖面: src/lib/workers/handlers/*.ts + src/lib/workers/*.worker.ts。
  • tests/**/*.test.ts 实际数量: 71。
  • src/lib/workers/handlers/*.ts 文件数量: 43（含 helper/shared/re-export 文件）。
  • handlers 目录中 export async function handle... 入口函数数量: 26（这是 worker 行为测试的主覆盖对象）。
  • 计数口径说明:
    • helper/shared/prompt-utils 文件不计入“handler 入口数”。
    • 仅 re-export 的别名文件（如 modify-asset-image-task-handler.ts、image-task-handlers.ts）不单独计入口径。
  • 已有结构级测试（需替换/下沉，已替换项会在阶段状态中标记）：
    • tests/integration/api/contract/direct-submit-routes.test.ts
    • tests/integration/api/contract/llm-observe-routes.test.ts
    • tests/integration/api/contract/crud-routes.test.ts
    • tests/integration/api/contract/task-infra-routes.test.ts
    • tests/integration/chain/{text,image,video,voice}.chain.test.ts
    • tests/unit/worker/video-worker.test.ts（已替换为行为断言）
    • tests/unit/worker/voice-worker.test.ts（已替换为行为断言）
    • tests/unit/optimistic/sse-invalidation.test.ts（已替换为行为断言）
    • tests/unit/optimistic/task-target-state-map.test.ts（已替换为行为断言）
  • 已落地的行为级样板（保留并扩展）：
    • tests/unit/worker/reference-to-character.test.ts
    • tests/unit/worker/asset-hub-image-suffix.test.ts
    • tests/unit/worker/modify-image-reference-description.test.ts
    • tests/integration/api/specific/characters-post-reference-forwarding.test.ts
    • tests/contracts/requirements-matrix.test.ts

1.4 修改前后的预计区别

修改前：

  • 大量“永远绿灯”风险：结构级测试通过但真实业务错误。
  • 关键回归（参考图链路、提示词后缀、写回字段）无法稳定拦截。

修改后：

  • 结构级测试只做守卫，不作为回归主防线。
  • 行为级测试覆盖 route 入参、task payload、worker 分支、DB 写回、返回值契约。
  • 新增或修改功能时，必须补行为级用例，否则 guard 失败。

1.5 规模预估

  • 预计新增/重写测试文件: 45-70 个
  • 预计修改文件: 25-40 个
  • 预计新增代码: 9,000-16,000 行（以测试与守卫脚本为主）
  • 预计执行阶段: 8 个阶段

2: 阶段+具体代码修改地方以及需要修改的内容

状态图例

✅ 已完成
🔄 正在执行
⏸ 待执行
⚠️ 问题

阶段1: 基线与约束固化

✅ Phase 1.1: 盘点路由、task type、worker 入口并建立 catalog。
修改位置:

  • /Users/earth/Desktop/waoowaoo/tests/contracts/route-catalog.ts
  • /Users/earth/Desktop/waoowaoo/tests/contracts/task-type-catalog.ts

✅ Phase 1.2: requirements matrix 存在性校验落地，阻断“文档写了但文件不存在”。
修改位置:

  • /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.ts
  • /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.test.ts

✅ Phase 1.3: 定义“行为级测试判定标准”并加入守卫。
要改内容:

  • 新增 /Users/earth/Desktop/waoowaoo/tests/contracts/behavior-test-standard.md
  • 新增 /Users/earth/Desktop/waoowaoo/scripts/guards/test-behavior-quality-guard.mjs 硬性规则:
  • 禁止只断言 toHaveBeenCalled()
  • 必须断言具体 payload/data 字段值或返回值
  • 禁止在 contract/chain 目录内读取源码文本做契约主断言

✅ Phase 1.3.a: 后端 Worker 单元测试硬规范已写入本主计划（本文件第 3 章）。
当前状态:

  • 规范文本已固化
  • 自动化守卫脚本已落地（Phase 1.3 完成）

⚠️ Phase 1.4: 历史结构级测试较多，改造期间可能出现“同名文件语义变化”导致误解。
处理策略:

  • 每次改造完成后，在本文件执行日志记录“此文件已由结构级改为行为级”。

阶段2: API 契约从结构级替换为行为级

依赖关系:

  • Phase 2 可先行推进（route 行为契约）。
  • Phase 3 与 Phase 4 依赖 Phase 2 的 route 输入输出基线稳定。

✅ Phase 2.1: 重写 direct-submit contract 为真实调用断言。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/direct-submit-routes.test.ts 必须断言:
  • 未登录 401
  • 参数缺失 400（错误码一致）
  • 正常请求返回 { taskId, async: true }
  • submitTask 入参包含 type/targetType/targetId/payload/locale

✅ Phase 2.2: 重写 llm-observe contract 为真实调用断言。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/llm-observe-routes.test.ts 必须断言:
  • maybeSubmitLLMTask 入参正确透传
  • displayMode/flow/meta 不丢失
  • 越权请求被拒绝

✅ Phase 2.3: 重写 crud contract 为真实行为断言（已补齐 asset-hub + novel-promotion 写回断言）。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/crud-routes.test.ts 必须断言:
  • PATCH 后数据库字段值确实变化
  • DELETE 后实体不存在
  • 无权限用户无法操作他人资源

✅ Phase 2.4: 重写 task-infra contract 为真实行为断言（已补 SSE 终态事件序列断言）。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/task-infra-routes.test.ts 必须断言:
  • dismiss 后任务状态变化
  • task-target-state 与任务终态一致
  • SSE 事件序列含终态事件

⏸ Phase 2.5: 扩展 route specific 测试，补关键历史回归点。
新增/扩展:

  • /Users/earth/Desktop/waoowaoo/tests/integration/api/specific/reference-to-character-api.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/integration/api/specific/characters-post-reference-forwarding.test.ts（已完成，继续扩展）
  • /Users/earth/Desktop/waoowaoo/tests/integration/api/specific/characters-post.test.ts

阶段3: Worker 决策测试全量行为化

依赖关系:

  • Phase 3 依赖 Phase 2（route 契约稳定后再固化 worker 结果断言）。

✅ Phase 3.1: 关键历史 bug 已有行为级样板落地。
已完成文件:

  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/reference-to-character.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/asset-hub-image-suffix.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/modify-image-reference-description.test.ts

✅ Phase 3.2: 把“失败快照类”worker 测试升级为“结果断言类”。
优先重写:

  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/image-task-handlers-core.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/script-to-storyboard.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/episode-split.test.ts 必须断言:
  • 具体生成参数（referenceImages/aspectRatio/resolution）
  • 具体写库字段值（description/imageUrl/imageUrls/selectedIndex）
  • 关键分支（character/location/storyboard）均触发

✅ Phase 3.3: 新增核心 handler 行为测试文件（按模块拆分，已全部落地）。
新增文件:

  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/character-image-task-handler.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/location-image-task-handler.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/panel-image-task-handler.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/panel-variant-task-handler.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/story-to-script.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/screenplay-convert.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/voice-design.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/voice-analyze.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/analyze-novel.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/analyze-global.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/character-profile.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/clips-build.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/asset-hub-ai-design.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/asset-hub-ai-modify.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/llm-proxy.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-tasks.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-variants.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-prompt-appearance.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-prompt-location.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-prompt-shot.test.ts 当前进度:
  • 已完成: character-image-task-handler、location-image-task-handler、panel-image-task-handler、panel-variant-task-handler、story-to-script、screenplay-convert、voice-design、voice-analyze、analyze-novel、analyze-global、character-profile、clips-build、asset-hub-ai-design、asset-hub-ai-modify、llm-proxy、shot-ai-tasks、shot-ai-variants、shot-ai-prompt-appearance、shot-ai-prompt-location、shot-ai-prompt-shot
  • 待完成: 无（Phase 3.3 范围内）

⚠️ Phase 3.3.a: 边界说明（避免误算）。
不纳入“handler 入口测试清单”的文件:

  • llm-stream.ts（stream context/callback helper）
  • modify-asset-image-task-handler.ts（re-export 别名）
  • image-task-handlers.ts（re-export 聚合）

✅ Phase 3.4: worker 入口层行为测试替换 routing-only 断言。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/video-worker.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/worker/voice-worker.test.ts 必须断言:
  • 任务类型分发到正确 handler
  • handler 结果被正确回传与封装
  • 失败分支日志与错误码一致

⚠️ Phase 3.5: 避免“mock 自己返回答案”造成假安全。
硬要求:

  • 每个测试至少 1 个断言检查具体字段值（不是调用次数）
  • 对 DB update/create 入参做 objectContaining(data: ...) 断言

阶段4: Chain 测试从队列映射升级为端到端行为链路

依赖关系:

  • Phase 4 依赖 Phase 2 + Phase 3（先稳定 route 和 handler 行为，再做链路端到端）。

✅ Phase 4.1: 重写 image chain（enqueue + worker 消费 + 持久化写回断言已落地）。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/chain/image.chain.test.ts 覆盖链路:
  • route -> submitTask -> queue -> image worker -> DB 回写 示例断言:
  • 任务状态从 queued -> processing -> completed
  • 目标实体 imageUrl/imageUrls 有值且结构正确

✅ Phase 4.2: 重写 text chain（enqueue + worker 消费 + 结果级边界断言已落地）。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/chain/text.chain.test.ts 覆盖链路:
  • analyze/story/script/reference-to-character 全链路关键节点

✅ Phase 4.3: 重写 video chain（enqueue + video worker 消费 + lip-sync 持久化断言已落地）。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/chain/video.chain.test.ts 覆盖链路:
  • generate-video/lip-sync 任务执行结果与状态持久化

✅ Phase 4.4: 重写 voice chain（enqueue + voice worker 消费 + 关键参数透传断言已落地）。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/integration/chain/voice.chain.test.ts 覆盖链路:
  • voice-design/voice-generate 的实体写回与任务状态

⏸ Phase 4.5: 固化外部 fake 层，保证零真实外网请求。
使用/扩展:

  • /Users/earth/Desktop/waoowaoo/tests/helpers/fakes/llm.ts
  • /Users/earth/Desktop/waoowaoo/tests/helpers/fakes/media.ts
  • /Users/earth/Desktop/waoowaoo/tests/helpers/fakes/providers.ts

阶段5: 前端状态回归测试行为化

✅ Phase 5.1: 替换源码字符串检查为 hook 真实行为测试。
重写文件:

  • /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/sse-invalidation.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/task-target-state-map.test.ts 必须断言:
  • 给定事件序列时 query invalidation 实际触发条件正确
  • target state map 在 queued/processing/completed/failed 下输出正确

✅ Phase 5.2: 现有 optimistic mutation 行为测试保留并扩展。
文件:

  • /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/asset-hub-mutations.test.ts
  • /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/project-asset-mutations.test.ts

阶段6: 覆盖矩阵升级为“行为测试矩阵”

✅ Phase 6.1: 新增 route 行为覆盖矩阵。
新增:

  • /Users/earth/Desktop/waoowaoo/tests/contracts/route-behavior-matrix.ts 要求:
  • 117 个 route 每个都映射到至少 1 条行为级 caseId + test 文件

✅ Phase 6.2: 新增 task type 行为覆盖矩阵。
新增:

  • /Users/earth/Desktop/waoowaoo/tests/contracts/tasktype-behavior-matrix.ts 要求:
  • 37 个 TASK_TYPE 每个都映射 worker 行为测试 + chain 行为测试

✅ Phase 6.3: 新增矩阵守卫脚本。
新增:

  • /Users/earth/Desktop/waoowaoo/scripts/guards/test-behavior-route-coverage-guard.mjs
  • /Users/earth/Desktop/waoowaoo/scripts/guards/test-behavior-tasktype-coverage-guard.mjs

⚠️ Phase 6.4: 矩阵维护成本高。
策略:

  • 优先通过脚本自动校验文件存在与 caseId 唯一性
  • 每次新增 route/tasktype 必须更新矩阵，否则 CI 失败

阶段7: CI 门禁与执行策略

✅ Phase 7.1: 新增行为级门禁命令。
修改:

  • /Users/earth/Desktop/waoowaoo/package.json 新增脚本:
  • test:behavior:unit
  • test:behavior:api
  • test:behavior:chain
  • test:behavior:guards
  • test:behavior:full

⏸ Phase 7.2: PR workflow 强制执行行为级全量门禁。
修改:

  • /Users/earth/Desktop/waoowaoo/.github/workflows/test-regression-pr.yml

✅ Phase 7.3: 失败诊断脚本已接入（保留）。
文件:

  • /Users/earth/Desktop/waoowaoo/scripts/test-regression-runner.sh

阶段8: 收口与冻结

⏸ Phase 8.1: 删除/降级旧结构级测试（仅保留轻量守卫，不计入行为覆盖率）。
目标:

  • contract/chain 中不再有“只读源码字符串”的主断言

⏸ Phase 8.2: 建立“新增功能必须附行为测试”的提交流程。
落地:

  • PR 模板加检查项
  • guard 失败提示明确指出缺失 case

✅ Phase 8.3: 冻结基线并发布“行为级测试开发规范”。
新增:

  • /Users/earth/Desktop/waoowaoo/docs/testing/behavior-test-guideline.md

⚠️ Phase 8.4: 不可达目标声明。
说明:

  • “100% 无 bug”不可证明；可达目标是“100% 关键功能链路行为覆盖 + 关键字段结果断言 + 变更自动门禁”。

阶段9: Billing 与并发测试纳入总蓝图

🔄 Phase 9.1: billing 现有测试纳入“行为级总体覆盖说明”，避免遗漏域。
覆盖现状:

  • tests/unit/billing/*.test.ts
  • tests/integration/billing/*.integration.test.ts
  • tests/concurrency/billing/ledger.concurrency.test.ts

⏸ Phase 9.2: 明确 billing worker/ledger 行为级断言增强点。
新增/重写方向:

  • 计费写账一致性（usage->ledger）字段级断言
  • 异常重试/幂等行为断言
  • 并发写入冲突场景断言

⏸ Phase 9.3: 将 billing 与 concurrency 纳入 test:behavior:full 报告维度。
要求:

  • 输出 billing/concurrency 独立通过率
  • 与 route/worker/chain 覆盖率同级展示

3: 后端 Worker 单元测试硬规范（强制）

3.1 必须覆盖的测试类型

每个 worker handler 必须至少包含三类用例：

  1. 失败路径：参数缺失/格式错误时，抛出正确错误信息。
  2. 成功路径：正常输入时，副作用结果正确（数据库写入/关键调用参数/返回值）。
  3. 关键分支：if/else 分支每条至少 1 个用例。

3.2 Mock 规范

必须 Mock：

  1. prisma 等数据库访问。
  2. LLM/图像生成/视觉分析等 AI 调用。
  3. COS/上传等文件存储。
  4. 外部 HTTP 请求。
  5. 一切需要网络的依赖。

不能 Mock：

  1. 待测业务逻辑函数本身。
  2. 项目内业务常量（例如 CHARACTER_PROMPT_SUFFIX），必须直接 import 使用。

3.3 断言规范（最高优先级）

每个 it() 必须断言“结果”，不能只断言“过程”。

必须断言：

  1. 数据库 update/create 的具体字段值（如 description、imageUrl、imageUrls）。
  2. AI/生成函数收到的核心参数（如 prompt 必含内容）。
  3. 图像生成相关关键参数（如 referenceImages、aspectRatio、resolution）。

弱断言限制：

  1. toHaveBeenCalled() 不能作为唯一主断言。
  2. toHaveBeenCalledTimes(N) 仅在“次数本身有业务意义”时使用。

3.4 测试数据规范

  1. 数据必须能触发目标分支（例如“有参考图/无参考图”分别建用例）。
  2. 关键业务字段必须使用有语义的固定值。
  3. 无关透传字段可用占位值（如 task-1）。

禁止模式：

  1. “自己给答案自己验证”：mock 返回值与断言目标完全同源。
  2. 正确做法：mock AI 返回值，断言该值被写入到 prisma.update({ data }) 的具体字段。

3.5 it() 结构模板（强制推荐）

it('[条件] -> [预期结果]', async () => {
  // 1. 准备 mock（仅覆盖本场景差异）
  // 2. 构造 job/payload（只给本场景关键字段）
  // 3. 执行 handler
  // 4. 断言：
  //    a. DB data 字段
  //    b. 核心调用参数（prompt/referenceImages/aspectRatio）
  //    c. 返回值关键字段（如 success）
})

3.6 命名规范

统一格式：[条件] -> [预期结果]
示例：

  1. 没有 extraImageUrls -> 不调用分析，description 不更新
  2. 有 extraImageUrls -> AI 分析结果写入 description
  3. AI 调用失败 -> 主流程成功且 description 不被污染
  4. 缺少必填参数 -> 抛出包含字段名的错误信息

3.7 一条 bug 一条测试（强制）

  1. 每修复一个 bug，必须新增至少一条对应回归测试。
  2. 测试名必须可追溯该 bug 场景（例如“防止 XXX 回归”）。
  3. 未补测试不得标记该 bug 任务完成。

执行日志（必须持续追加）

格式:

  • [YYYY-MM-DD HH:mm] 状态变更: <Phase/任务> <旧状态> -> <新状态>

  • [YYYY-MM-DD HH:mm] 修改文件: <绝对路径列表>

  • [YYYY-MM-DD HH:mm] 运行命令: <命令>

  • [YYYY-MM-DD HH:mm] 结果: <通过/失败 + 摘要>

  • [YYYY-MM-DD HH:mm] 问题: <若有>

  • [2026-02-25 21:59] 状态变更: Phase 3.1 ⏸ -> ✅

  • [2026-02-25 21:59] 修改文件: /Users/earth/Desktop/waoowaoo/tests/unit/worker/reference-to-character.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/asset-hub-image-suffix.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/modify-image-reference-description.test.ts, /Users/earth/Desktop/waoowaoo/src/lib/workers/handlers/reference-to-character.ts

  • [2026-02-25 21:59] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker/reference-to-character.test.ts tests/unit/worker/asset-hub-image-suffix.test.ts tests/unit/worker/modify-image-reference-description.test.ts

  • [2026-02-25 21:59] 结果: 关键历史回归点（后缀失效/参考图描述不更新）已行为级可测

  • [2026-02-25 21:59] 问题: 无

  • [2026-02-25 22:00] 状态变更: Phase 1.2 ⏸ -> ✅

  • [2026-02-25 22:00] 修改文件: /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.ts, /Users/earth/Desktop/waoowaoo/tests/contracts/requirements-matrix.test.ts

  • [2026-02-25 22:00] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/contracts/requirements-matrix.test.ts

  • [2026-02-25 22:00] 结果: 阻断不存在测试路径引用（已修复 crud-asset-hub-routes.test.ts 错误引用）

  • [2026-02-25 22:00] 问题: 无

  • [2026-02-25 22:10] 状态变更: Phase 1.3.a ⏸ -> ✅

  • [2026-02-25 22:10] 修改文件: /Users/earth/Desktop/waoowaoo/SYSTEM_BEHAVIOR_LEVEL_TEST_MASTER_PLAN.md

  • [2026-02-25 22:10] 运行命令: 文档更新（无测试执行）

  • [2026-02-25 22:10] 结果: 已将后端 Worker 单元测试硬规范（覆盖/Mock/断言/命名/一 bug 一测试）固化为主计划强制章节

  • [2026-02-25 22:10] 问题: 自动化守卫脚本仍待实现（Phase 1.3）

  • [2026-02-25 22:20] 状态变更: 文档校正（扫描计数与范围修正）

  • [2026-02-25 22:20] 修改文件: /Users/earth/Desktop/waoowaoo/SYSTEM_BEHAVIOR_LEVEL_TEST_MASTER_PLAN.md

  • [2026-02-25 22:20] 运行命令: rg --files/rg -n 扫描 tests 与 handlers

  • [2026-02-25 22:20] 结果: 已修正 test 文件数=51、handlers 文件数=43、handler 入口数=26；补齐 Phase 3.3 遗漏 handler；新增 Phase 依赖关系与 Phase 9（billing/concurrency）

  • [2026-02-25 22:20] 问题: Phase 1.3 自动守卫脚本尚未实现

  • [2026-02-25 23:05] 状态变更: Phase 2.1 🔄 -> ✅, Phase 2.2 ⏸ -> ✅

  • [2026-02-25 23:05] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/direct-submit-routes.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/llm-observe-routes.test.ts

  • [2026-02-25 23:05] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract/direct-submit-routes.test.ts tests/integration/api/contract/llm-observe-routes.test.ts

  • [2026-02-25 23:05] 结果: 两类 contract 测试已由结构级改为行为级并通过，覆盖 16 个 direct-submit routes 与 22 个 llm-observe routes

  • [2026-02-25 23:05] 问题: 无

  • [2026-02-25 23:06] 状态变更: Phase 2.3 ⏸ -> 🔄, Phase 2.4 ⏸ -> 🔄

  • [2026-02-25 23:06] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/crud-routes.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/task-infra-routes.test.ts

  • [2026-02-25 23:06] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract/crud-routes.test.ts tests/integration/api/contract/task-infra-routes.test.ts

  • [2026-02-25 23:06] 结果: 已替换为真实 route 调用断言；crud 完成鉴权行为覆盖，task-infra 完成鉴权/参数/核心成功路径，后续补 DB 写回与 SSE 终态序列

  • [2026-02-25 23:06] 问题: 无

  • [2026-02-25 23:06] 状态变更: Phase 3.2 🔄 -> ✅, Phase 3.4 ⏸ -> ✅

  • [2026-02-25 23:06] 修改文件: /Users/earth/Desktop/waoowaoo/tests/unit/worker/image-task-handlers-core.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/episode-split.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/script-to-storyboard.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/video-worker.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/voice-worker.test.ts

  • [2026-02-25 23:06] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker/script-to-storyboard.test.ts tests/unit/worker/video-worker.test.ts tests/unit/worker/voice-worker.test.ts tests/unit/worker/image-task-handlers-core.test.ts tests/unit/worker/episode-split.test.ts

  • [2026-02-25 23:06] 结果: worker 测试已升级为结果级断言，覆盖失败路径、成功路径、关键分支与关键写库字段

  • [2026-02-25 23:06] 问题: 无

  • [2026-02-25 23:07] 状态变更: Phase 4.2 ⏸ -> 🔄, Phase 4.3 ⏸ -> 🔄, Phase 4.4 ⏸ -> 🔄

  • [2026-02-25 23:07] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/chain/image.chain.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/text.chain.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/video.chain.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/voice.chain.test.ts

  • [2026-02-25 23:07] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/chain/image.chain.test.ts tests/integration/chain/text.chain.test.ts tests/integration/chain/video.chain.test.ts tests/integration/chain/voice.chain.test.ts

  • [2026-02-25 23:07] 结果: chain 测试已由映射断言升级为 addTaskJob enqueue 行为断言（校验 queue 选择 + jobId/priority）

  • [2026-02-25 23:07] 问题: route->worker->DB 端到端链路仍待补

  • [2026-02-25 23:08] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract tests/integration/chain tests/unit/worker

  • [2026-02-25 23:08] 结果: 16 个测试文件全部通过，117/117 测试通过

  • [2026-02-25 23:09] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/crud-routes.test.ts

  • [2026-02-25 23:09] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract/crud-routes.test.ts

  • [2026-02-25 23:09] 结果: 新增 CRUD 结果级断言（PATCH 写入字段值、DELETE 删除调用与越权 403），从“仅鉴权检查”升级为“含写库行为检查”

  • [2026-02-25 23:09] 问题: novel-promotion 侧 CRUD 的字段级断言仍待扩展

  • [2026-02-25 23:09] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/task-infra-routes.test.ts

  • [2026-02-25 23:09] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract/task-infra-routes.test.ts

  • [2026-02-25 23:09] 结果: 新增 SSE replay 成功路径断言（text/event-stream、last-event-id 回放、channel 订阅行为）

  • [2026-02-25 23:09] 问题: SSE 终态事件的 completed/failed 序列断言仍待补

  • [2026-02-25 23:10] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract tests/integration/chain tests/unit/worker

  • [2026-02-25 23:10] 结果: 16 个测试文件全部通过，120/120 测试通过

  • [2026-02-25 23:11] 状态变更: Phase 1.3 🔄 -> ✅

  • [2026-02-25 23:11] 修改文件: /Users/earth/Desktop/waoowaoo/tests/contracts/behavior-test-standard.md, /Users/earth/Desktop/waoowaoo/scripts/guards/test-behavior-quality-guard.mjs, /Users/earth/Desktop/waoowaoo/package.json

  • [2026-02-25 23:11] 运行命令: node scripts/guards/test-behavior-quality-guard.mjs && npm run check:test-coverage-guards

  • [2026-02-25 23:11] 结果: 行为级质量守卫已接入（拦截源码字符串契约 + 弱断言），并纳入 check:test-coverage-guards

  • [2026-02-25 23:11] 问题: 无

  • [2026-02-25 23:12] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/direct-submit-routes.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/llm-observe-routes.test.ts

  • [2026-02-25 23:12] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract/direct-submit-routes.test.ts tests/integration/api/contract/llm-observe-routes.test.ts

  • [2026-02-25 23:12] 结果: 两个 contract 测试新增 toHaveBeenCalledWith(objectContaining(...)) 强断言，通过行为质量守卫

  • [2026-02-25 23:12] 问题: 无

  • [2026-02-25 23:13] 状态变更: Phase 5.1 ⏸ -> ✅

  • [2026-02-25 23:13] 修改文件: /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/sse-invalidation.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/optimistic/task-target-state-map.test.ts

  • [2026-02-25 23:13] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/optimistic/sse-invalidation.test.ts tests/unit/optimistic/task-target-state-map.test.ts

  • [2026-02-25 23:13] 结果: 两个 optimistic 结构级测试已替换为行为级（SSE 终态 invalidation 与 target-state overlay 合并规则）

  • [2026-02-25 23:13] 问题: 无

  • [2026-02-25 23:16] 状态变更: Phase 3.3 ⏸ -> 🔄

  • [2026-02-25 23:16] 修改文件: /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-tasks.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/voice-design.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/asset-hub-ai-design.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/asset-hub-ai-modify.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-prompt-appearance.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-prompt-location.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-prompt-shot.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/shot-ai-variants.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/llm-proxy.test.ts

  • [2026-02-25 23:16] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker/shot-ai-tasks.test.ts tests/unit/worker/voice-design.test.ts tests/unit/worker/asset-hub-ai-design.test.ts tests/unit/worker/asset-hub-ai-modify.test.ts tests/unit/worker/shot-ai-prompt-appearance.test.ts tests/unit/worker/shot-ai-prompt-location.test.ts tests/unit/worker/shot-ai-prompt-shot.test.ts tests/unit/worker/shot-ai-variants.test.ts tests/unit/worker/llm-proxy.test.ts

  • [2026-02-25 23:16] 结果: 新增 9 个 worker 行为测试文件（20 条用例+5 条用例），覆盖 shot-ai 分发、prompt 修改链路、asset-hub ai 设计/修改、voice-design、llm-proxy 显式失败

  • [2026-02-25 23:16] 问题: 无

  • [2026-02-25 23:16] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker

  • [2026-02-25 23:16] 结果: worker 套件通过，17 文件 / 48 测试通过

  • [2026-02-25 23:17] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/optimistic tests/unit/worker tests/integration/api/contract tests/integration/chain

  • [2026-02-25 23:17] 结果: 全回归分组通过，31 文件 / 155 测试通过

  • [2026-02-25 23:25] 修改文件: /Users/earth/Desktop/waoowaoo/tests/unit/worker/story-to-script.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/screenplay-convert.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/analyze-novel.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/analyze-global.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/voice-analyze.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/clips-build.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/character-profile.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/character-image-task-handler.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/location-image-task-handler.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/panel-image-task-handler.test.ts, /Users/earth/Desktop/waoowaoo/tests/unit/worker/panel-variant-task-handler.test.ts

  • [2026-02-25 23:25] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker/story-to-script.test.ts tests/unit/worker/screenplay-convert.test.ts tests/unit/worker/analyze-novel.test.ts tests/unit/worker/analyze-global.test.ts tests/unit/worker/voice-analyze.test.ts tests/unit/worker/clips-build.test.ts tests/unit/worker/character-profile.test.ts tests/unit/worker/character-image-task-handler.test.ts tests/unit/worker/location-image-task-handler.test.ts tests/unit/worker/panel-image-task-handler.test.ts tests/unit/worker/panel-variant-task-handler.test.ts

  • [2026-02-25 23:25] 结果: 新增 11 个 worker handler 行为测试文件，覆盖剩余未落地入口（文本链路 + 图片链路），失败路径/成功路径/关键分支断言全部落地

  • [2026-02-25 23:25] 问题: 首轮运行出现 5 个断言问题（重试分支 mock 泄漏与断言过窄），已在同轮修复

  • [2026-02-25 23:26] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/worker

  • [2026-02-25 23:26] 结果: worker 套件通过，28 文件 / 76 测试通过

  • [2026-02-25 23:26] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/optimistic tests/unit/worker tests/integration/api/contract tests/integration/chain

  • [2026-02-25 23:26] 结果: 全回归分组通过，42 文件 / 183 测试通过

  • [2026-02-25 23:27] 状态变更: Phase 3.3 🔄 -> ✅

  • [2026-02-25 23:27] 运行命令: npm run check:test-coverage-guards

  • [2026-02-25 23:27] 结果: 覆盖守卫通过（behavior quality / route=117 / taskType=37）

  • [2026-02-25 23:27] 问题: 无

  • [2026-02-25 23:27] 运行命令: rg "export async function handle" src/lib/workers/handlers -l + tests/unit/worker import 对账

  • [2026-02-25 23:27] 结果: 26/26 handler 入口均存在对应 worker 行为测试文件引用

  • [2026-02-25 23:27] 问题: 无

  • [2026-02-25 23:46] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/crud-routes.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/api/contract/task-infra-routes.test.ts

  • [2026-02-25 23:46] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/api/contract/crud-routes.test.ts tests/integration/api/contract/task-infra-routes.test.ts

  • [2026-02-25 23:46] 结果: CRUD 合同新增 novel-promotion 写回断言（select-character-image / select-location-image / clips PATCH），task-infra 新增 SSE channel 终态事件序列断言（processing -> completed）

  • [2026-02-25 23:46] 问题: 无

  • [2026-02-25 23:46] 修改文件: /Users/earth/Desktop/waoowaoo/tests/integration/chain/image.chain.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/text.chain.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/video.chain.test.ts, /Users/earth/Desktop/waoowaoo/tests/integration/chain/voice.chain.test.ts

  • [2026-02-25 23:46] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/integration/chain/image.chain.test.ts tests/integration/chain/text.chain.test.ts tests/integration/chain/video.chain.test.ts tests/integration/chain/voice.chain.test.ts

  • [2026-02-25 23:46] 结果: 4 个 chain 文件由“仅 queue 映射”升级为“queue payload -> worker 消费 -> 结果/写回断言”

  • [2026-02-25 23:46] 问题: 无

  • [2026-02-25 23:47] 修改文件: /Users/earth/Desktop/waoowaoo/tests/contracts/route-behavior-matrix.ts, /Users/earth/Desktop/waoowaoo/tests/contracts/tasktype-behavior-matrix.ts, /Users/earth/Desktop/waoowaoo/scripts/guards/test-behavior-route-coverage-guard.mjs, /Users/earth/Desktop/waoowaoo/scripts/guards/test-behavior-tasktype-coverage-guard.mjs, /Users/earth/Desktop/waoowaoo/package.json, /Users/earth/Desktop/waoowaoo/tests/contracts/task-type-catalog.ts, /Users/earth/Desktop/waoowaoo/docs/testing/behavior-test-guideline.md

  • [2026-02-25 23:47] 运行命令: BILLING_TEST_BOOTSTRAP=0 npx vitest run tests/unit/optimistic tests/unit/worker tests/integration/api/contract tests/integration/chain && npm run check:test-coverage-guards

  • [2026-02-25 23:47] 结果: 分组回归通过（42 文件 / 191 测试），覆盖门禁通过（behavior quality + route 117 + taskType 37 + behavior matrices）

  • [2026-02-25 23:47] 问题: 无

  • [2026-02-25 23:51] 运行命令: npm run test:behavior:full

  • [2026-02-25 23:51] 结果: 行为级全链路命令通过（guards + unit + api + chain）；unit=39 文件/107 测试，api=4 文件/93 测试，chain=4 文件/12 测试

  • [2026-02-25 23:51] 问题: unit 辅助测试阶段出现本地 Redis 连接拒绝日志（127.0.0.1:6380）但不影响用例通过，后续可按需优化为静默 mock

4: 验证策略

4.1 可量化验收目标（全部必须达成）

  1. Route 行为覆盖率: 117/117（每个 route 至少 1 个行为级用例）。
  2. TASK_TYPE 行为覆盖率: 37/37（每个 task type 至少 1 个 worker 行为用例 + 1 个 chain 行为用例）。
  3. 结构级 contract/chain 主断言占比: 0%（不得再以源码字符串匹配作为主断言）。
  4. 关键回归场景覆盖: 100%（参考图链路、后缀链路、编辑写回链路、task state 链路）。
  5. 外部真实调用次数: 0（测试环境必须全 fake）。
  6. PR 门禁: 100% 执行 test:behavior:full，任一缺失即失败。
  7. Worker 用例规范符合率: 100%（每个 worker 测试文件均满足 3.1~3.7 规则）。
  8. Billing + Concurrency 维度通过率: 100%（纳入统一验收报告）。

4.2 核心验证命令

  • npm run test:guards
  • cross-env BILLING_TEST_BOOTSTRAP=0 vitest run tests/unit/worker
  • cross-env BILLING_TEST_BOOTSTRAP=0 vitest run tests/unit/helpers
  • cross-env BILLING_TEST_BOOTSTRAP=1 vitest run tests/integration/api
  • cross-env BILLING_TEST_BOOTSTRAP=1 vitest run tests/integration/chain
  • npm run test:pr

4.3 用例质量验证（防假绿灯）

每个新增行为测试必须至少满足两条：

  1. 断言具体业务字段值（例如 description/imageUrls/locale/meta/referenceImages）。
  2. 覆盖至少一个历史回归分支。
  3. 覆盖一个失败分支（权限/参数/模型未配置）。
  4. 不使用“mock 自己返回结果并直接断言调用次数”的空测试模式。

5: 备注

  1. 本文档是“行为级测试替换计划”，与 SYSTEM_REGRESSION_COVERAGE_MASTER_PLAN.md 并行存在；冲突时以“行为级优先”原则执行。
  2. 本计划默认不引入兼容层与静默回退，错误必须显式暴露。
  3. 新接手模型必须先阅读本文件，再执行代码修改；执行后必须回写执行日志。
  4. 如果出现“测试通过但线上仍回归”，优先审计断言是否为结果级而不是调用级。
Reference in New Issue View Git Blame Copy Permalink