okooooooo/Ncurator

0 Fork 0

Files

T

hy b48859389d feat: implement structured output strategy and retry mechanism with exponential backoff

2026-07-23 13:46:58 +08:00

20 KiB

Raw Blame History

NCurator-Desktop 测试架构

1. 文档定位

本文是 NCurator-Desktop 的唯一测试总规范。
本文定义测试分类、回归准入、执行闭环、UI E2E 真实性、真实 AI / live 断言，以及 runner 和 raw logs 契约。
各业务域的 suite、case 和领域规则只在对应 doc/test-plan/** 中维护，本文不重复登记 case。
只有当功能代码发生变动、对应 doc/test-plan/** 明确要求对齐 doc/prd/**，或者 doc/prd/** 本身发生变更时，才需要校验实现与 doc/prd/** 的一致性。
新增任何测试文件前，必须先与用户确认目标分类：回归测试，或 unit / 辅助测试。

测试体系只沉淀一层长期执行产物：

原始日志：tests/logs/**

测试样例只记录事实，不直接写失败原因分析、优化建议或能力判断。

2. 测试体系总览

2.1 测试分类

回归测试
- 列入 doc/test-plan/**，放在 tests/case/<domain>/<suite>/**。
- 用于长期维护、批量执行和生成可追溯运行产物。
unit / 辅助测试
- 放在 tests/case/unit/**。
- 不进入 doc/test-plan/**，由 unit runner 独立发现和执行。
不落测试文件的排查不属于测试文档治理对象；新增测试文件前必须先确认归入回归测试还是 unit / 辅助测试。

2.2 目录结构

tests/
  harness/
  fixtures/
  case/
    ai/
    unit/
    settings/
    workbench/
    kb-search/
  logs/

规则：

目录使用 kebab-case。
测试发现目录使用通用树形结构：tests/case/<domain>/<suite>/<groups...>/<case>.test.ts。
e2e 测试文件使用 tests/case/<domain>/<suite>/<groups...>/<case>.e2e.test.ts。
suite 是第一层稳定分类；groups... 是 suite 下可选的子目录。
各 domain 的 suite 列表与归属，只在对应 doc/test-plan/** 中定义。
当某个 suite 不需要继续细分时，回归 case 可以直接放在该 suite 目录下。
tests/case/** 中除 unit/** 外，只允许放已在 doc/test-plan/** 登记的回归 case。
tests/fixtures/workspace/ 是共享工作区 fixture 根目录；凡是依赖“工作区里有什么文件”的测试，优先复用该目录。
当 case 直接传入 tests/fixtures/workspace 目录时，runner 应把该目录下的子内容原样复制到临时 workspace 根目录，而不是保留 tests/fixtures/** 中间层路径。

2.3 稳定映射模型

domain
- 稳定业务域，例如 ai、settings、workbench、kb-search。
suite
- 领域内第一层稳定分类。
- 具体取值与归属只看对应 doc/test-plan/**。
group
- suite 下可选子目录。
- 只有同一 suite 内确实需要继续分层时才创建。
case
- 最终测试定义，对应唯一 caseId 和日志目录；一个文件可以包含多个紧密相关的 case。
type
- 测试类型只通过文件名体现。
- 普通测试默认视为 backend；文件名包含 .e2e.test.ts 时视为 e2e。

3. 回归 case 规则

3.1 准入规则

新增任何测试文件前，必须先与用户确认目标分类。
doc/test-plan/** 是回归 case 的唯一规格来源；新增、修改或补齐回归 case 时，必须先更新对应测试计划，再修改测试代码。
tests/case/<domain>/** 只能放已登记的回归 case；tests/case/unit/** 不进入领域回归计划。
每个回归 caseId 都必须稳定映射到唯一测试定义与唯一日志目录。一个测试文件可以承载多个紧密相关的 case，但 --case <caseId> 必须能只执行目标 case。

3.2 回归 case 共享字段

回归 case 在 doc/test-plan/** 中统一使用以下字段：

测试类型
- backend 或 e2e。
What
- 这条 case 到底要验证什么。
Why
- 这条 case 为什么长期存在，解决什么真实风险。
How
- 输入、前置条件、fixture、运行方式与关键执行链路。
Oracle
- 必须成立的明确断言集合。
Not
- 明确不验证什么，防止实现时擅自扩张范围。
doc/test-plan/** 只保存稳定的 case 规格、执行规则和 Oracle，不保存单次运行结果或环境故障记录。
每次运行的模型、耗时、通过情况、完成度评分、失败归因和原始证据统一保存在对应 run 的 meta.json、timeline.jsonl、runtime-events.jsonl 与 artifacts 中。
测试数量和 case 清单以测试源码及 runner 实时发现结果为准，不在文档中维护容易失真的计数副本。
mock-llm 回归 case 只允许替换 LLM 输出；不得 fake tool、store、docx apply service、runner 或节点执行结果。
scripts/test/workflow.mjs 会自动读取仓库根目录的 .env.local、.env（已存在的 shell 环境变量优先）；可用 AI_TEST_DISABLE_DOTENV=1 禁用自动加载。

3.3 UI E2E 回归规则

UI E2E 必须通过真实 UI 和产品链路完成被测行为，不得用 fake、mock、stub、直接写状态或内部 IPC 绕过。
fixture 和 helper 只能准备真实输入、执行用户可见操作、等待结果和收集证据，不能替代产品输出。
每个 E2E case 必须显式声明 serviceMode；使用 fixture 模式时还必须提供 fixtureReason。
Workbench 和需要真实文件的 Settings case 将 tests/fixtures/workspace 复制到临时目录，case 结束并关闭应用后删除临时副本。
与当前 case 无关且已有独立覆盖的前置状态，可以通过真实 window.api.* 建立，但不能代替当前 case 的用户操作。
涉及真实 AI 时必须使用 live 配置；配置缺失应直接失败，不能跳过或回落到 mock。
产品缺少必要 testability 入口时，应记录缺口，不能改用模拟路径绕过。

3.4 真实 AI / live 断言规则

Workbench 真实 AI E2E 固定读取 AI_LIVE_BASE_URL、AI_LIVE_API_KEY、AI_LIVE_PRIMARY_MODEL_NAME、AI_LIVE_VISUAL_MODEL_NAME；缺少任意一项都必须 preflight fail。
Workbench 真实 AI E2E 必须通过应用 UI 同时选择主模型和视觉模型；视觉模型不得静默跟随主模型。
backend 视觉模型测试统一读取 AI_LIVE_VISUAL_MODEL_NAME；视觉模型专用地址、密钥和 provider 仍可通过 AI_LIVE_VISION_BASE_URL、AI_LIVE_VISION_API_KEY、AI_LIVE_VISION_PROVIDER_KIND 覆盖。
涉及真实 AI 调用的回归测试，硬断言只验证最低工程契约：完成态、关键事实、关键工具或事件、关键 artifact，以及用户诉求是否落地。
不对最终文案做逐字断言，不断言固定工具顺序，不断言固定 prompt 原文，不因表达差异判失败。
如果用户诉求已落地但断言过严，应先调整 Oracle 和测试代码，再根据 raw logs 记录完成度评分。
完成度评分由执行者或 agent 写入运行结论；测试代码不得在执行过程中修改文档。

4. 测试执行闭环

4.1 固定顺序

先确认是否新增或调整测试，以及目标分类。
如果是回归测试，先更新对应 doc/test-plan/**，再修改 tests/case/<domain>/**。
如果是 unit / 辅助测试，放入 tests/case/unit/**，不更新 doc/test-plan/**。
通过 scripts/test/workflow.mjs 执行并产出日志。
先看 timeline.jsonl；不足时再看 runtime-events.jsonl、meta.json 和 artifacts.json。
最后基于 raw logs 回流结论，决定是否需要更新 doc/test-plan/** 或实现代码。

4.2 runner 与常用命令

统一入口默认是 scripts/test/workflow.mjs。

runner 的职责：

找到目标测试文件并执行。
落原始日志到 tests/logs/**。
在不带 --type 时按“普通测试 -> 源码 E2E”顺序执行。
按 --target 准备源码应用，或构建、审计并安装正式包。

runner 不负责：

写事实汇总稿。
写失败原因分析。
写优化建议。

当前常用命令按域收口如下。

AI
- pnpm test:ai
- pnpm test:ai:backend
- pnpm test:ai:tool
- pnpm test:ai:human:mock-llm
- pnpm test:ai:human:live
Unit
- pnpm test:unit
- pnpm test:unit:ai
全量 E2E
- pnpm test:e2e:source：构建当前源码并运行全部 E2E。
- pnpm test:e2e:package -- --bundle <release-bundle.json>：校验并安装已经构建的正式包，再对安装后的可执行程序运行全部 E2E。
Settings
- pnpm test:settings
- pnpm test:settings:backend
- pnpm test:settings:e2e
Workbench
- pnpm test:workbench
- pnpm test:workbench:backend
- pnpm test:workbench:e2e
- node scripts/test/workflow.mjs --domain workbench
- node scripts/test/workflow.mjs --domain workbench --type backend
- node scripts/test/workflow.mjs --domain workbench --type e2e

runner 支持的过滤参数：

--domain
--type
--suite
--group，可重复传入
--case
--runs
--target，取值为 source 或 package，默认 source。
--bundle，正式包 E2E 必填，指向已构建候选包的 release-bundle-*.json。
--fresh-knowledge-cache，删除本次构建对应的知识库缓存，强制从零验证完整索引。
--reuse-knowledge-cache，人工调试时跨构建复用同一类缓存；不能和 --fresh-knowledge-cache 同时使用。

补充规则：

不带 --type 时，runner 会先收集普通测试，再收集 .e2e.test.ts。
--type 取值为 backend 或 e2e。
--target package 只能与 --type e2e 一起使用；普通测试和 backend 不允许使用正式包目标。
source 是日常默认目标：runner 准备 Electron native 模块、构建当前源码，并让每个 E2E 文件独立启动源码应用。
package 是正式产物目标：runner 校验 release bundle 及文件哈希；macOS 从指定 DMG 挂载并复制 App，Windows 静默安装指定 EXE；随后对安装后的真实可执行程序运行同一批 E2E。runner 不执行构建，也不得把 dist 中的未安装目录当成正式包验证。
macOS 正式包 E2E 按 macos-arm64、macos-x64 分目录将测试应用保留在 ~/Applications/NCurator-E2E/。
E2E case 通过 runner 按文件串行执行，每个文件独立启动并关闭一个 Electron app；runner 会在相邻 E2E 文件之间默认等待 1 秒，也可通过 --run-delay-ms 覆盖。单个文件失败后仍继续执行剩余文件，最终统一返回失败并保存每个文件的结果。
E2E runner 直接调用本地 Vitest binary，不经 pnpm exec；启动 Vitest 子进程和 harness 启动 Electron 时都会过滤 npm_* 环境变量，只保留系统环境与 NCURATOR_E2E_* 等项目测试变量，避免 npm lifecycle 变量影响 macOS Electron 原生注册。
如果需要继续收窄到某个 suite、group 或单条 case，统一通过 runner 参数过滤。
--group 只在目标 suite 确实存在额外子目录时使用；如果 case 直接位于 suite 根目录，则不需要 --group。
better-sqlite3 native 模块需要区分 Node ABI 和 Electron ABI。runner 会通过 scripts/build/native/better-sqlite3.mjs 自动准备对应缓存，并通过 NCURATOR_BETTER_SQLITE3_NATIVE_BINDING 注入本次测试使用的 binding；正常回归不需要手动 rebuild 或覆盖 node_modules 中的 native 文件。
正式包 E2E 的 bundle 校验、安装日志、安装包哈希和汇总写入 tests/logs/package/<runId>/；业务 case 自身的 raw logs 仍按原有 tests/logs/<domain>/<suite>/** 规则保存。
正式包 E2E 不负责构建。--target package 必须接收 --bundle <release-bundle.json>，只安装并测试 bundle 指定的既有安装包；bundle 的 tag、平台、fragment 和文件哈希必须全部匹配。
发布流程通过 --package-e2e 显式启用正式包回归门；未启用时不阻塞发布。macOS 启用时 arm64、x64 两个 bundle 均须通过。
发布候选包可使用 release:win|release:mac -- --tag <tag> --test-only 重跑正式包 E2E；该阶段只消费持久化候选 bundle，不重新构建。失败会把候选标记为 rejected，通过后恢复为 ready。
E2E 知识库缓存由 workflow 统一选择，一轮测试的全部 case 共用同一个目录。源码测试使用 tests/.cache/workspace-knowledge/source/<out-main-and-preload-sha256>；正式包测试使用 tests/.cache/workspace-knowledge/package/<installer-sha256>。两类缓存完全隔离，不再使用固定共享目录。
缓存键仍包含文件内容哈希、扩展名、分块配置和向量模型名。未修改文件可以命中；新增或修改的文件会重新处理；删除文件不会因为缓存仍存在而重新进入新 workspace 的索引。
每个 E2E case 的附件中会生成 knowledge-cache-summary.json，timeline 也会记录同样的命中和未命中统计。正式包总统计同时写入 tests/logs/package/<runId>/summary.json。

4.3 自动更新模拟测试

自动更新测试运行后端契约测试和模拟页面 E2E：

pnpm test:update

也可以分开运行：

pnpm test:update:backend
pnpm test:update:e2e

后端测试验证主进程更新状态、发布配置、R2 元数据和 release fragment。模拟 E2E 验证页面按钮、进度、错误提示和 IPC。自动化测试不下载或安装真实更新包。

4.4 读取与分析 raw logs

默认先读取目标 run 的 timeline.jsonl，理解语义步骤、断言事实和失败位置。
如果 timeline.jsonl 仍不足以解释结果，再继续读取 runtime-events.jsonl 与关键附件。
必要时回看 meta.json 与 artifacts.json，确认 run 摘要、统计值和附件索引。
所有分析结论都必须可回溯到 raw logs 与 artifacts，不得脱离证据做推断。

4.5 结论回流

如果问题出在 case 定义、验收口径或阶段边界，必须先改 doc/test-plan/**，再改测试代码。
如果只是实现缺陷或回归问题，可在保持 case 规格不变的前提下修实现并重跑。
测试结论以目标 run 的 raw logs 和 artifacts 为准，不将单次结论回写为长期文档事实。

5. runner 与原始产物契约

5.1 run 目录

每个 run 固定目录：

tests/logs/<domain>/<suite>/<groups...>/<caseId>/<runId>/
  meta.json
  timeline.jsonl
  runtime-events.jsonl
  artifacts.json
  artifacts/

固定原始文件：

meta.json
- 单次 run 的摘要索引。
- 用来回答“本次 run 是谁、结果是什么、统计值是什么”。
timeline.jsonl
- 单次 run 的事实事件流。
- 用来回答“本次 run 按顺序发生了什么”。
runtime-events.jsonl
- 单次 run 的完整运行时原始事件流。
- 用来回答“底层 runtime 真实发出了哪些事件”。
artifacts.json
- 单次 run 的附件索引。
- 用来回答“本次 run 产生了哪些可回看的附件”。
artifacts/
- 可选目录。
- 只有确实生成 trace、截图、HTML 诊断页等实体附件时才创建。

目录与命名规则：

<domain>/<suite>/<groups...>
- 目录层级体现业务域与 suite 树。
- runner 通过目录过滤测试范围。
<caseId>
- 对应用例稳定标识。
- 通常与测试文件名去掉 .test.ts 后一致；e2e case 通常以 .e2e 结尾。
<runId>
- 单次执行唯一标识。
- 当前格式：YYYYMMDD-HHmmss-SSS。
backend 正式 case 运行开始后，runner 应尽快创建对应 run 目录，并对 timeline.jsonl / runtime-events.jsonl / llm-io.jsonl 采用渐进式落盘；不得要求等到 run 结束后才首次出现日志目录。
backend raw logs 的完整记录以磁盘上的 JSONL 文件为唯一真相源；测试进程内允许不再长期保留这些日志的全量副本。

5.2 `meta.json`

固定字段：

schemaVersion
runId
caseId
scope
status
startedAt
finishedAt
stats
runtime

关键约束：

schemaVersion 固定值为 4。
scope 格式为 <domain>/<suite>/<groups...>，不包含 caseId。
status 当前值域是 passed / failed。
backend run 在执行中允许临时写出 running；正式结束后必须收口为 passed 或 failed。
stats 当前固定字段：
- durationMs
- steps
- assertions
- errors
- artifacts
runtime 当前固定字段：
- driver
- target
- modelName
meta.json 顶层只保留上述固定字段。
如果测试需要保留 fixture 依赖信息，应写在 timeline.jsonl 的 run/start 事件 data 中。
为降低长 live run 的内存压力，stats 可以来自运行中计数器或基于磁盘日志的回读统计；不要求依赖内存里的全量 timeline 副本。

5.3 `timeline.jsonl`

固定字段：

ts
type
name
status
id
message
data

字段规则：

type 当前值域：
- run
- step
- assertion
- artifact
- signal
- error
status 当前值域：
- info
- ok
- failed
- skipped
message 只写“发生了什么”，不写失败原因、优化建议或能力判断。
data 只放按需原始观测值，不要求统一业务 schema。

约束：

timeline.jsonl 只记录高价值语义事件，不记录底层噪音。
signal 用于记录可观察到的外部信号，例如路由变化、IPC 调用、AI 事件。
当失败事件存在明确证据时，优先把证据放进 data 或 artifact，不要在 message 中写大段解释。
e2e 下不把所有 Playwright 底层调用逐条倾倒进 timeline；底层重放依赖 trace.zip，timeline 只保留语义 step / assertion / signal。
run 之外的业务状态不要塞进 timeline.status。
- 例如 blocked、completed、cancelled 应保留在 runtime-events.jsonl 或写进 data。

5.4 `runtime-events.jsonl`

文件内容是逐行原始运行时事件 JSON，不包额外 wrapper，不做 schema 投影。
范围固定为完整 runtime 原始事件流。
普通测试与 e2e 的采集路径可以不同，但最终落盘契约必须一致。
runtime-events.jsonl 始终写出；如果本次 run 没有 runtime 事件，则写空文件。
当 Oracle、断言 data 或 timeline.jsonl 仍不足以解释失败原因时，必须继续回看 runtime-events.jsonl。

5.5 `artifacts.json`

固定字段：

顶层：
- schemaVersion
- items
items 每项固定字段：
- id
- kind
- path
- refs

关键约束：

schemaVersion 固定值为 4。
kind 当前值域：
- trace
- screenshot
- video
- playwright-report
- jsonl
- other
path 是相对当前 run 根目录的稳定路径。
refs 当前支持：
- stepId
- assertionId
artifacts.json 必须始终写出，即使 items 为空数组。
artifacts/ 目录只有在确实存在实体附件文件时才创建。

5.6 不同测试类型的统一约束

普通测试与 e2e 共用同一份 meta.json / timeline.jsonl / runtime-events.jsonl / artifacts.json 基础契约。
两类测试的差异只体现在：
- meta.runtime.driver
- meta.runtime.target
- artifacts.json.items[].kind
- runtime-events.jsonl 的采集路径
- timeline.jsonl 中出现的语义事件名与信号类型

5.7 e2e 默认附件策略

成功 run：
- 始终保留 Playwright trace。
- 只有测试或 runtime 显式要求保留的关键截图才写入。
- 默认不生成 Playwright HTML 诊断页。
失败 run：
- 始终保留 Playwright trace。
- 始终生成失败截图，并通过 refs.assertionId 或 refs.stepId 绑定。
- 生成位于 artifacts/playwright/report/index.html 的 HTML 诊断页。
默认不保留 video。

20 KiB Raw Blame History Unescape Escape

NCurator-Desktop 测试架构

1. 文档定位

2. 测试体系总览

2.1 测试分类

2.2 目录结构

2.3 稳定映射模型

3. 回归 case 规则

3.1 准入规则

3.2 回归 case 共享字段

3.3 UI E2E 回归规则

3.4 真实 AI / live 断言规则

4. 测试执行闭环

4.1 固定顺序

4.2 runner 与常用命令

4.3 自动更新模拟测试

4.4 读取与分析 raw logs

4.5 结论回流

5. runner 与原始产物契约

5.1 run 目录

5.2 meta.json

5.3 timeline.jsonl

5.4 runtime-events.jsonl

5.5 artifacts.json

5.6 不同测试类型的统一约束

5.7 e2e 默认附件策略

20 KiB

Raw Blame History

5.2 `meta.json`

5.3 `timeline.jsonl`

5.4 `runtime-events.jsonl`

5.5 `artifacts.json`