@wenext/test-tool v0.1.8
独立的测试执行工具,命令为 wenext-test。发现受影响的 workspace 包,执行已声明的检查,生成可复核的报告。它不依赖 Wenext-Pi 或旧 Toolkit。
首版要求 Node.js >=22.19,执行平台为 macOS/Linux。本地修改发布前可在本包 npm ci && npm test && npm pack 后安装生成的 tgz。
使用
wenext-test plan --root /path/to/project --changed packages/app/src/main.ts
wenext-test run --root /path/to/project --package app --output /tmp/app-check-001
wenext-test verify --output /tmp/app-check-001--package 和 --changed 可重复;不指定范围时读取 Git 工作树的变更及未跟踪文件,--base main 再包含相对合并基点的提交变更。范围不完整时检查所有包。输出目录必须为空且在项目外,每次执行使用新目录。
工作区支持 npm/Yarn workspaces、pnpm YAML、嵌套 glob 和排除项。变更范围会纳入反向依赖;显式 --package 精确选择包。源码快照同时包括选中包的工作区依赖、所有包清单、根文件和规则。
默认检查 test(必需)、typecheck(存在则执行)、test:e2e:smoke(存在则执行)。这只是默认执行策略;业务要求 FLT/E2E 必须执行时,应使用规则明确声明,不能依赖可选默认值。
声明业务要求
默认直接使用原生脚本与 runner 配置。只有需要覆盖默认检查、文件范围或额外验收约束时,才在 .agents/rules/test-tool.json 中维护可选规则;不要求每个任务补一份配置:
{
"schemaVersion": 1,
"checks": [
{ "id": "flt", "script": "test", "runner": "auto", "minPassed": 1 },
{ "id": "smoke", "script": "test:e2e:smoke", "runner": "playwright", "requiredTests": ["account > login"] }
],
"overrides": [
{
"packages": ["utils/**"],
"checks": [{ "id": "unit", "script": "test", "runner": "vitest" }]
}
]
}单个 override 替换匹配包的 checks;多个 override 同时匹配会报错。也可用 --config path/to/rules.json 选择项目内的规则。普通测试文件、runner 配置、依赖和必要的业务 fixture 仍由项目维护。
Jest/Vitest/Playwright 可用 testFiles 声明本次必须执行的包内测试文件:
{ "id": "order", "script": "test", "runner": "vitest",
"testFiles": ["tests/order.test.ts"], "requiredTests": ["order submits"] }文件须存在、互不重复,不接受 glob、目录或行号过滤。每个指定文件都须至少有一个通过用例;缺失或来源不明的报告不能通过;原生 runner 多执行的测试按真实结果保留,不因数量增加而阻断。Jest 使用按路径执行,Playwright 使用转义后的完整路径正则;Vitest 原生参数为子串匹配,可能实际多跑文件,不能据此保证执行副作用仅限指定文件。多个文件的同名场景仍需拆成独立 check 才能逐文件约束标题。
smoke 请求拦截可采用随包分发的 Playwright fixture:复制到业务测试目录,以 fulfill 提供 mock,未接管的浏览器 XHR/fetch 会被阻断并使测试失败。它不增加核心运行时依赖,也不代替业务登录、完整网络隔离或设备验收。
Jest/Vitest 检查可加可选 coverage,明确要验证的包内源码和百分比阈值:
{ "id": "flt", "script": "test", "runner": "auto",
"coverage": { "files": ["src/domain/order.ts"], "thresholds": { "lines": 90, "branches": 80 } } }逐文件验证本次新生成的 JSON 统计,未声明的文件不混入分母。缺文件、缺报告、非法统计或没有可执行行会 blocked;低于阈值会 failed。项目须安装匹配版本的 coverage provider;工具不自动安装、不推断阈值,也不读取历史 coverage 目录。当前校验整文件,不支持 changed-line 覆盖率。
Runner 和报告
- Jest、Vitest、Playwright:保留原有脚本,追加 JSON reporter 参数,解析实际用例结果。
json:已有测试命令将{schemaVersion:1, tests:[{name,status}]}写到WENEXT_TEST_REPORT,status 为 passed/failed/skipped。exit:用于 lint/typecheck 等只承诺退出状态的命令,不能据此宣称执行了测试。- TypeScript API 的
RunnerAdapter可适配其他工具;CLI 不自动加载仓库 JavaScript 插件。
零通过用例、全部 skip、缺少必需场景、缺少报告、未知 runner 都不通过。Playwright 重试后最终成功计为 passed 并保留 flaky 标记;expected-failure 保留为 skipped,不充当通过用例。原生 fail-on-flaky 等导致非零退出仍失败。optional 仅允许脚本不存在;存在的脚本执行失败仍影响总结果。
输出包含 plan.json、report.json、result.json、evidence.json 及每项检查的日志和原始报告。result.json 保留兼容 verdict,并增加 status 与 reasons;报告版本读取当前安装包清单。退出码:0 通过,1 测试失败,2 blocked/unverified/输入错误,130 取消。verify 只读校验,不重新执行测试。
输入指纹与环境边界
从 0.1.5 起,扫描策略 v2 在打开文件之前排除 .env / .env.*(含 example)、.npmrc / .yarnrc.yml 等凭据配置、常见私钥/证书文件、凭据目录,以及 .gitnexus、.turbo 等缓存。规则适用于根目录、嵌套包、正向依赖与显式输入;不能把排除项声明为规则、testFiles 或 coverage 源。完整列表见执行契约。不读取 .gitignore 来决定快照范围;被 Git 忽略的普通源码仍参与校验。
plan/report 的 snapshot 记录扫描策略版本、执行工具的 Node 版本、平台、架构和项目声明的 packageManager。声明值不保证实际安装版本;environment: "not_captured" 表示环境变量、凭据及远端服务未被记录或证明不变。工具不输出这些敏感文件的内容或单文件摘要。
verify 会拒绝旧策略、不同运行时或被修改的源码/测试/规则/锁文件。它仅复核过去一次运行的证据,不证明当前外部环境有效。环境或凭据变化后,应使用新输出目录重新 run。扫描排除不限制子进程:应用测试、包管理器可能按自身行为读取环境配置;需要纯本地验证时由业务测试显式 mock。
不提供任意 glob 排除开关,避免把源码/测试排除后仍声称质量通过。新增排除类别需同时更新策略版本、契约和“不打开文件”的回归。
Wenext-Pi 接入
在 Pi 的 .agents/rules/workflow.json 中声明普通检查:
{
"schemaVersion": 1,
"quality": {
"schemaVersion": 2,
"requireVerified": true,
"checks": [{
"id": "tests",
"command": ["wenext-test", "run", "--input", "{{requestFile}}", "--output", "{{outputDir}}"],
"timeoutMs": 1800000,
"resultFile": "result.json",
"artifacts": ["report.json", "evidence.json"],
"verifyCommand": ["wenext-test", "verify", "--input", "{{requestFile}}", "--output", "{{outputDir}}"]
}]
}
}使用内置 quality-web 时,Pi 会选择其托管缓存中的 registry 最新版本;仅修改业务仓的依赖不会替换这个版本。发布 0.1.5 后,重新准备质量检查并确认提示的实际工具版本;旧报告需要重跑。
Pi 负责任务状态、检查重跑记录、最终门禁和指标;本工具只读取显式传入的公开请求。请确保 wenext-test 解析到新包:旧 Toolkit 存在同名命令,迁移验证时应使用新包 binary 的绝对路径,避免覆盖正在使用的旧版本。
API / 开发
import { planTestRun, runTestPlan, verifyTestReport } from '@wenext/test-tool';
const plan = planTestRun({ root: '/repo', packages: ['app'] });
const result = await runTestPlan({ root: '/repo', packages: ['app'], outputDir: '/tmp/run-001' });
verifyTestReport(result.outputDir);npm test 包括真实 runner 与 Chromium 的最小场景;开发环境需要先准备 Playwright Chromium(npx playwright install chromium)。npm run typecheck 同时检查核心和 recipe。运行时依赖仅 yaml/picomatch,测试 runner 为开发依赖,不替业务安装或升级 runner。
详细边界见 执行契约、业务能力映射 和 旧 Toolkit 精简迁移评估。本版完成独立执行、显式覆盖率、测试文件范围校验和最小 smoke recipe,尚不能据此删除业务仓库的全部旧流程。
Optional report observations
Each check now includes additive metrics facts: actual runner spawn, report availability, final business case counts, runner error count, flaky/expected-failure counts, and category. These facts do not change the existing pass/fail gate. Runner setup errors retain their gate behavior but are typed kind: "runner_error", so consumers can exclude them from business case counts.
Existing rules require no changes. A check may optionally declare category: "unit" | "e2e" | "other" in its existing rule. Without explicit category metadata the report says unknown; the runner name does not determine the category. Exit-only checks and missing/invalid reports have null case counts, not zero tests or 100% success. quality-web consumes the frozen report and optional existing coverage evidence; the test tool does not upload metrics itself.
已完成任务的附件回收
0.1.7 支持 wenext-test compact --task-dir <已完成任务目录> 只读预览,增加 --apply 执行回收。保留各业务包/检查最近失败的诊断附件、全部成功产物、完整对话、每轮报告及错误文字。只回收较早失败的 Playwright trace、录像和自动失败截图,不改变 CI 或重试。
wenext-test verify-evidence --output <运行输出目录> 可检查回收后的历史完整性;它不代表测试通过。策略、收据与中断恢复见附件回收契约。