Skip to content

Test-tool schema 1 执行契约 ​

1. Scope / Trigger ​

本契约约束独立 CLI/API、仓库 rules、外部 runner 和 Pi 普通命令之间的数据流。工具不读取 Pi 私有状态、不持有任务完成权、不上报平台指标,也不自动生成业务测试、安装依赖、修复失败或重试。所有检查顺序执行;前项失败不跳过后项。

2. Signatures ​

text
wenext-test plan [--root DIR] [--package NAME|PATH ... | --changed PATH ... | --base REF | --input FILE] [--config FILE]
wenext-test run  [同上] --output NEW_EXTERNAL_DIR
wenext-test verify --output DIR [--input ORIGINAL_REQUEST]
wenext-test --help | --version

JSON 为默认输出,--json 可显式写出。范围选项互斥。

ts
planTestRun(options?: PlanOptions): TestPlan
runTestPlan(options: RunOptions): Promise<{report: TestReport; outputDir: string}>
verifyTestReport(outputDir: string, requestFile?: string): TestReport
discoverPackages(root: string): PackageInfo[]
interface RunnerAdapter {
  id: string;
  prepare(context: {reportFile: string; artifactsDir: string}): {args: string[]; env?: Record<string,string>};
  parse(value: unknown): TestCase[];
}

扩展 adapter 通过 runTestPlan({adapters}) 注入,禁止覆盖内置 ID。内置 ID 为 jest/vitest/playwright/json,exit 为保留进程契约。公共 API 只从包根导出,内部模块不可作为稳定接口。

3. Contracts ​

输入与规则 ​

公开 request:schemaVersion:1、字符串 checkId/projectRoot/cwd/outputDir、scope.complete:boolean、scope.observedPaths:string[];可带 ambiguousPreexistingPaths、inputFingerprint 等公开字段。cwd 必须在真实项目根内。相对路径不允许绝对路径、反斜杠、空段、. 或 ..。输入文件原始字节参与绑定。Pi 的 writeScope 等附加字段保持由 Pi 管理。

scope 不完整或存在 ambiguousPreexistingPaths 时全选;根 README/CHANGELOG/LICENSE/NOTICE 不扩大选包;test-tool 规则按 Git 基线比较实际受影响的包,pnpm importer 变化按包定位;无法解释的共享配置或依赖解析变化仍全选;变更包加工作区反向依赖;显式包选择不扩散。Git rename 按删除与新增两端处理。无变更产生 unverified,不假装已有测试通过。

规则 schemaVersion 必须为 1;check 包含 id、script 或 command 二选一、runner、optional、minPassed、requiredTests、timeoutMs。未知字段拒绝。ID 唯一、小写字母开头并仅含小写字母数字和连字符,每组最多 32 项。command 为非空字符串 argv 数组,无隐式 shell;package script 保留包管理器本身的 shell 语义。默认 timeoutMs=120000,范围100..1800000;普通 runner 默认 minPassed=1 且不得小于1。exit 只能 minPassed=0、无 requiredTests。

runner=auto 只识别脚本文本中唯一的 jest/vitest/playwright;别名或包装脚本需显式 runner。工具追加 reporter、可选 coverage 和文件范围参数,未知包装器未产出 JSON 会 blocked。Jest/Vitest requiredTests 匹配 reporter 的 fullName,Playwright 使用 describe 与标题按 > 连接,不包含文件名。不做语义推断,也不保证同名用例来自不同项目。

可选 testFiles ​

check 可带 testFiles: string[],1..256 个互不重复、包内精确相对测试文件。拒绝 glob、行号过滤、越界、目录、符号链接及快照排除目录。仅支持 jest/vitest/playwright 与解析为这些 runner 的 auto;不支持 json/exit/自定义 adapter。无此字段时保留原始执行范围。

plan 检查文件存在性和 runner 能力;缺文件 blocked,不回退全量测试。run 在 reporter/coverage 参数后追加文件过滤:Jest --runTestsByPath 加绝对路径;Playwright 转义并锚定完整绝对路径;Vitest 传绝对路径,但原生匹配是子串,可能多跑文件。存在 wrapper、原有位置参数、Playwright project dependency 等扩大范围的情况时,工具不修改项目配置或关闭准备步骤;以报告中的实际文件执行门禁。额外执行的测试保留实际结果,不要求为其重复填写 testFiles。

内置 Jest/Vitest/Playwright 解析器为 cases 保留可选 file 来源;Jest/Vitest 读取 suite.name,Playwright 将 spec.file 按 report.config.rootDir 解析为绝对路径(不是工具 cwd)。TestCase.file 为兼容性新增字段;RunnerAdapter 方法签名不变。仅可能 passed 的 scoped check 进一步要求每个 case 有绝对文件来源、所有指定文件都出现。证据缺失/来源不明为 blocked;额外文件允许执行,真实失败仍失败;指定文件出现但全 skip 为 failed。已有测试或进程失败保留 failed。来源与原始报告都进入现有 evidence/源码绑定。

每文件至少一个通过用例,与 check 总 minPassed、requiredTests 同时生效。标题匹配仍在整个 check 内;同名场景必须逐文件约束时使用单文件 check。此功能不证明语义覆盖,也不保证 Vitest 的执行副作用只限指定文件。原生参数依据:Jest runTestsByPath、Vitest file filtering、Playwright CLI。

可选 coverage ​

check 另可带 coverage: {files: string[], thresholds: Partial<Record<"statements"|"branches"|"functions"|"lines", number>>}。files 必须 1..256 项、互不重复的包内精确相对源码路径,无 glob/目录/符号链接/越界/快照排除目录;thresholds 至少声明一个 0..100 有限百分比,未知键拒绝。未声明时无采集、无默认阈值。仅支持 Jest/Vitest(含解析为两者的 auto);不改变自定义 RunnerAdapter 接口。

plan 标记缺失/不支持的 coverage 源或 runner 为 blocked;原有 optional 脚本缺席规则不变。run 通过原生参数输出本次 checks/<id>/coverage/coverage-summary.json,仅读取这份新报告。按声明文件精确匹配唯一条目,校验四类 total/covered/skipped 为合法非负整数,covered/skipped 均不得超过 total;报告中的 pct 不用于判定。每文件按 covered/total 检查声明的阈值,不做全局平均,任一低于阈值 failed。无 statements 或 lines 的空统计 blocked;无函数/分支时该单项为 100%。

check 结果新增可选 coverage:status、files[{path,summary,failures}]、可选 reason。缺报告/漏文件/非法统计 blocked,原测试失败保留 failed,不由 coverage 成功或缺失覆盖。原始统计进入同一 evidence 清单,verify 不重跑。输出只证明 runner 提供的被插桩代码计数,不证明业务语义或被忽略代码全覆盖。项目自己维护 provider、source map、include/exclude 与业务测试;暂不支持 changed-line 算法。采集参数与 runner 版本应按实际测试验证。

结果与环境 ​

  • report schema1:kind:wenext-test-report、toolVersion、planId、root、inputHash、status、checks、reasons。新增必需 snapshot(见下文),check 包含 runner、packagePath、status、exitCode、durationMs、cases、counts、directory、可选 reason。
  • 总状态 failed/blocked/passed/unverified;任何失败不通过,任何 blocked 不通过,全部缺席/无检查为 unverified。
  • Pi result:{schemaVersion:1,verdict:"passed"|"failed",status,reasons},仅总状态 passed 发 passed。报告 toolVersion 来自当前安装的 package.json。
  • Playwright flaky 最终成功计 passed 并保留 outcome=flaky;expected failure 计 skipped 并保留 outcome=expected_failure,不能充当必需场景通过。原生非零退出始终失败。
  • evidence schema1:planId、每个输出文件相对路径与 SHA256;输出目录必须新建或为空、在项目之外。
  • runner 环境继承当前进程,加 CI=1、FORCE_COLOR=0、COREPACK_ENABLE_NETWORK=0 和 reporter 路径。凭据可由调用者环境提供,不写 rules;本工具不管理账号凭据。继承环境/安装的工具链/远端服务不由源码摘要证明。
  • JSON runner 使用 WENEXT_TEST_REPORT;Playwright 使用 PLAYWRIGHT_JSON_OUTPUT_NAME;Jest/Vitest 使用 outputFile 参数。

快照和执行限制 ​

快照覆盖选中包及其正向工作区依赖、所有发现包的 package.json、根普通文件和 .agents/rules、.wenext-spec/spec、指定规则。每次校验重枚举根普通文件,可发现新根配置。快照不推断跨包相对导入和外部文件依赖;这些需在工作区依赖中声明或扩大选包。

在解析软链和读取内容前排除 .DS_Store、Thumbs.db、desktop.ini 等明确的操作系统元数据;普通源码与技能文件的软链限制不变。排除 node_modules/.git/dist/dist-ssr/build/coverage/test-results/playwright-report/e2e-artifacts/.cache/.next/.nuxt/.gitnexus/.turbo/.parcel-cache/.vite/pycache;这些是生成物,不可作为源码目录使用。源码逐文件使用 64 KiB 缓冲分块计算 SHA-256,保留路径/缺失项/排序,摘要对象增加 policyVersion=3,不再因累计 50000 路径或 512 MiB 拒绝正常大仓。内存仍随路径数增长,读取时间随完整输入大小增长;不能缩小共享文件影响范围、跳过大资源或使用截断内容换取通过。Windows 执行暂为 blocked;支持 POSIX 进程组、500ms终止宽限和每流1MiB日志。独立 supervisor 通过 IPC 监测 owner 退出;Pi 或用户 SIGKILL 工具进程时也会清理 runner 组。主动脱离进程组的 daemon、整个 supervisor 被外部强杀或主机崩溃不在清理保证内。证据单文件最多64MiB,Pi 声明冻结的 artifact 另受 Pi 16MiB 限制。

快照策略 v2 逐路径段、大小写不敏感排除 .env、.env.*(包括 .env.example)、.npmrc、.yarnrc.yml、.netrc、_netrc、.pypirc、.git-credentials、.ssh、.aws、.azure、.gnupg、credentials.json、service-account.json、id_rsa/id_dsa/id_ecdsa/id_ed25519 及其点后缀,以及 .pem/.key/.p12/.pfx/.keystore 后缀。固定规则不能识别任意命名的秘密,不是内容识别或子进程沙箱。若测试需要公开配置/证书 fixture,应使用不含秘密、可纳入快照的文件命名和显式业务契约,不能把被排除文件当作已验证源码。

排除判定发生在存在性、realpath、stat 和 open 之前;根文件清单与递归共享同一判定,显式输入也不能绕过。testFiles、coverage.files、规则配置路径遇到排除项直接拒绝。既有普通源码软链限制继续生效;不根据 .gitignore 排除源码。不暴露任意额外排除选项,防止排除 src/tests 等制造通过。

plan/report 均新增 snapshot: {policyVersion:3,nodeVersion,platform,arch,packageManager,environment:"not_captured"}。Node/平台/架构来自工具进程,packageManager 来自项目声明(缺失时仅记录选定 manager 名称),不探测或保证实际依赖安装状态。校验要求 plan/report 与当前策略、运行时完全一致,策略也参与 sourceHash;缺失/旧值失败并要求重新运行。环境变量、凭据、实际安装依赖和远程状态未被证明不变;verify 不是检查缓存命中许可。环境依赖检查应在当前任务实际 run,不因源码指纹一致复用旧的环境验收。

verify 比对完整输出摘要、工具版本、plan/report/result 绑定、原始 request 和当前输入,再要求 passed。校验不执行 runner,也不刷新旧证据;输入或报告改变后须运行到新目录。本地 hash 用于受信任执行下的完整性检测,不抵抗同用户同时改写报告和全部摘要。

4. Validation & Error Matrix ​

条件行为
所有适用检查通过,至少一项执行passed / exit0
非零退出、用例失败、零通过、requiredTests 缺失failed / exit1
缺少必需 script、未知 runner、缺少/非法 JSON、超时、启动失败blocked / exit2
optional script 缺席not_applicable;全部缺席则 unverified/exit2
运行时源码变更blocked / exit2
CLI 参数、规则、输出目录、快照限制错误JSON stderr / exit2
SIGINT/SIGTERM停止后续启动,清理当前进程组,exit130
verify 输入/报告变化、缺原始请求或非通过报告exit2,无重放

5. Good / Base / Bad Cases ​

  • Base:独立单包 test: vitest run,成功解析一个通过用例,report passed。
  • Good:共享包变更扩散至依赖应用;业务规则要求 E2E 与精确场景名;Pi 以公开文件调用并冻结报告。
  • Bad:--passWithNoTests 使 runner 返回0但无通过案例,结果仍 failed。
  • Bad:只有 skip 或 Playwright expected-failure;不能计为测试通过。
  • Bad:基础检查通过便删除真实登录/WebView/远程验收的旧流程;这些能力不由本版提供。

6. Tests Required ​

test/source-snapshot.test.mjs:策略版本参与摘要;敏感/缓存文件在 plan/run/verify 从未被打开,根/嵌套/正向依赖/显式输入一致,排除项不能作为规则/测试/coverage;普通源码与 gitignored 源码变动仍使凭证失效,旧策略/运行时不匹配拒绝;513 MiB 单个资源在共享锁文件选包下完成 plan/run/verify,修改超过旧上限位置的字节后 verify 拒绝;超过 50000 项的输入清单末项变化仍被捕获。

test/planning.test.mjs:workspace/glob/排除、Git rename/untracked、逆向依赖、正向快照依赖、无/不完整范围、规则歧义。

test/execution.test.mjs:结果与退出状态、零/skip/required、缺失报告/runner/script、optional失败、timeout/cancel、过期/篡改、request绑定、自定义 adapter、真实 CLI。

test/runners.test.mjs:固定开发依赖 Jest30.2.0、Vitest4.0.18、Playwright1.60.0,执行真实 runner 的正负场景。Playwright fixture 为无浏览器的断言测试,不代表业务 UI E2E。其他版本需兼容验证。

test/coverage.test.mjs:覆盖率规则、路径/runner、旧报告/漏文件/非法/空统计、逐文件原始比例阈值、证据篡改、既有失败保留,以及真实 Jest30.2.0 / Vitest4.0.18 + coverage-v8@4.0.18 成功与未覆盖分支。coverage provider 仅作为开发依赖,运行时依赖不变。

test/test-selection.test.mjs:范围规则与路径、无执行提前阻断、来源缺失/同名替代/漏文件/单文件全skip、保留失败,三个真实 runner 的精确报告集合、嵌套路径及正则转义、Vitest 子串多跑成功与真实失败保留、script/auto/coverage 兼容和源码修改后 verify 拒绝。

test/smoke-recipe.test.mjs:真实 Chromium + 本地 HTTP server,验证 mock 成功、未 mock fetch/XHR/同 context 新页面/fallback 请求失败且未到达 API、Service Worker 配置保护。recipe 的 TS 通过独立 typecheck;此 fixture 不构成完整网络沙箱,边界见 recipe。

隔离 pack/install 和既有 Pi host 的公开 request/result/verify 测试记录在对应 Trellis 任务研究目录;工具运行时不引入 Pi 依赖。

7. Wrong vs Correct ​

错误:工具查 Pi 私有 task.json,决定任务归档;脚本 exit0 就标记所有领域验收完成。

正确:工具读取显式公开请求,执行并校验声明的测试,返回领域报告;Pi 冻结证据、记录显式重跑、决定任务完成。业务意义和验收场景在 rules/skills 中定义。

错误:旧业务 skill 可运行,新宿主遇到规模限制就要求缩小业务范围或改 skill;把准备阶段缺少测试脚本视为业务实现失败。

正确:先以原 skill、原任务输入定位新工具链回归,在宿主/执行工具中修复;配置与用例编写由现有领域 skill 纳入实施计划。完成检查仍保留全部已声明要求,不能以兼容性修复为由忽略缺入口或真实业务失败。

Reporter 参数依据:Jest CLI、Vitest reporters、Playwright JSON reporter。本版兼容性以固定 runner 的实际测试为准。

运行进度与中断(2026-10-24) ​

RunOptions.onProgress(TestProgress) 提供 completed/total/packages/state/current;CLI 在 stderr 输出简短进度,stdout 仍是最终 JSON。progress.json 原子替换,记录当前检查和已完成结果。进度回调失败不改变测试事实。它不是通过凭证。

SIGINT/SIGTERM 或 API signal 取消后停止后续启动,保留已完成案例,并生成 blocked 的 report/result/evidence,reasons 包含 run_cancelled。取消时跳过最终源输入重哈希,因为中断结果无论如何不能通过。verify 仍拒绝中断与失败;若外部 SIGKILL 来不及生成完整汇总,progress.json 仍可用于诊断,不视作完成报告。正常执行继续完整 sourceHash 与 evidence 验证。

回归:execution.test.mjs 验证运行中可见已完成案例、取消后的汇总及 verify 拒绝;Pi 执行器联调验证优雅取消保留三份汇总,既有进程树清理约束保持。