fix(test): 拒绝两种静默假绿的 vitest 调用,并把正确跑法写进 AGENTS.md

[yinlianghui]

Fixes #3378
Fixes #3288

（注：正文一律用 PKG / PATHS 当占位符,不写尖括号 —— GitHub 的正文消毒会把「尖括号+字母」
当成 HTML 标签整段吃掉,第一版正文里的占位符就是这么消失的。）

前提复核(两条都在 origin/main 上原样复现)

#3378 —— 包级 cwd 跑 vitest:

$ cd packages/app-shell ; pnpm exec vitest list --filesOnly
[@object-ui/console] ../../apps/console/src/LocalizationFetchProvider.test.tsx
[@object-ui/console] ../../apps/console/src/__tests__/preview-samples-spec-valid.test.ts
...  (22 行,全部是 @object-ui/console;app-shell 自己 281 个文件一个都没有)

#3288 —— 路径挂在 -- 后面:

$ pnpm --filter @object-ui/fields test -- --run packages/fields/src/widgets/useRecordQuery.test.ts
   实际执行: vitest run -- --run packages/fields/src/widgets/useRecordQuery.test.ts
 Test Files  22 passed (22)      # 又是 console 的 22 个;点名的那个文件零执行
 EXIT=0

补一条 issue 正文没写、同族的第三种:仓根跑但路径写错/写歪,passWithNoTests: true
把它变成绿的 ——

$ pnpm exec vitest run packages/fields/src/does-not-exist.test.ts   # main
 EXIT=0

共同点是没有任何 0-match 信号:计数是 22 不是 0,passWithNoTests 甚至没参与判定。
按「包级验证」约定干活的 agent 会据此报「整包绿」。

机制

vitest 把 root 定成 cwd。根级 projects(unit/dom/dom-heavy)的 include 是
相对 root 的 packages/** / examples/** / scripts/**,从 packages/app-shell 里看就成了
packages/app-shell/packages/**,匹配不到任何文件;唯一还解析得成功的是以绝对路径引进来的
apps/console project。于是收集到 22 个别人的文件,跑绿,退出 0。

-- 那条是另一半:pnpm 把 -- 原样转发进脚本,vitest 的 CLI 解析在 -- 处停止,后面的
一切在 vitest 看到之前就不存在了 —— 不是「忽略并警告」,是压根没传进去。

改了什么

• 新增 scripts/vitest-invocation-guard.mjs,在 vitest.config.mts 顶部调用。三条判定:

  1. vitest root ≠ 仓根 → 拒绝(pnpm --filter @object-ui/app-shell test 跑的是 @object-ui/console 的 22 个文件,app-shell 自己的 276 个一个没跑,却报绿 #3378);
  2. -- 之后还有参数 → 拒绝(pnpm --filter <pkg> test -- --run <paths> 静默忽略路径过滤:新加的测试文件根本没跑,而输出看起来正常 #3288);若同时又在包目录里,报错正文一并点出 pnpm --filter @object-ui/app-shell test 跑的是 @object-ui/console 的 22 个文件,app-shell 自己的 276 个一个没跑,却报绿 #3378;
  3. 位置参数点名了具体 *.test.* 文件却不存在 → 拒绝。

  每个包的 vitest.config.ts 都 re-export 根配置,没有自己配置的包(如 app-shell)也会向上
  解析到它,所以这是两条陷阱唯一的收口点。报错正文写清机制 + 唯一正确跑法。

• passWithNoTests 由无条件 true 改为 !cliHasTestFilters(process.argv):命令行点名了
  文件却零匹配 → 非零退出;没点名(CI 的 --shard、--project 切片)照旧容忍空集合。

• AGENTS.md 新增「怎么跑测试」小节:唯一正确跑法(仓根 pnpm exec vitest run PATHS)、
  两条陷阱的机制与症状、零匹配即失败、逃生阀 OBJECTUI_VITEST_GUARD=off。

没动的东西:17 个 per-package vitest.config.ts(那是 #3240,已上抛维护者)、39 条包级
test 脚本、.github/workflows/**、任何 package 源码。

关于 #3288 里的方向 C(改写包级脚本转发路径)—— 评估后没做

把 test 脚本改成 vitest run --root ../.. packages/PKG/ 能让 pnpm --filter PKG test 真跑
起来,但它要改 39 个脚本,并且会把 turbo run test 从「一个几乎空转的假绿」变成「39 个真跑」——
ci.yml 的注释明确写着不要跑 turbo run test(多个包配置继承根 project 列表,会重复大段套件)。
更关键的是:包级脚本该不该存在本身就是 #3240 的议题,让它们「能用」等于替维护者提前定了案。
现在它们只是失败,不再撒谎 —— 这既满足本 PR 的目标,也不占 #3240 的位。

验证矩阵(方向都是先预测再跑的)

#	调用	预测	实际
1	包目录里 pnpm exec vitest list(#3378 的复现命令)	拒绝	exit 1 + #3378 报错框
2	pnpm --filter @object-ui/fields test -- --run PATH	拒绝,并同时点出两条	exit 1,正文含 #3288 与 #3378
3	仓根 pnpm exec vitest run packages/fields/src/widgets/useRecordQuery.test.ts	照常绿	Test Files 1 passed (1) / Tests 10 passed
4	CI 形状 pnpm test --shard=1/4 --project unit	不受影响	Test Files 94 passed (94) / Tests 1313 passed, 1 skipped
5	pnpm --filter @object-ui/app-shell test(无路径参数)	应当失败(它收集的是别人的包)	exit 1 + #3378 报错框
6	仓根 + 不存在的路径	由 main 的 exit 0 变 exit 1	exit 1(guard)
7	仓根 + 零匹配的子串过滤	由 main 的 exit 0 变 exit 1	exit 1 No test files found

反向验证(把 guard 关掉,看是否原样退回旧行为):

$ OBJECTUI_VITEST_GUARD=off pnpm --filter @object-ui/app-shell exec vitest list --filesOnly
[@object-ui/console] ../../apps/console/src/LocalizationFetchProvider.test.tsx ...
collected files: 22

—— 底层 vitest 行为一点没变,变的只是「它现在会被拦下」。

guard 自身的单测:pnpm exec vitest run scripts/__tests__/vitest-invocation-guard.test.ts
→ Test Files 1 passed (1) / Tests 23 passed (23),其中两条钉住根配置确实接了线
(assertCanonicalVitestInvocation(...) 在位、passWithNoTests 不再是硬编码 true),
否则 guard 就成了「测试很齐、没人调用」的摆设。

node scripts/check-control-bytes.mjs → OK(3630 个 tracked 文本文件);另按
[\x00-\x08\x0b\x0c\x0e-\x1f] 自查四个改动文件,无命中。

type-check:改动全部落在 vitest.config.mts / scripts/ / AGENTS.md,而每个包的 tsconfig
include 都只到 src,apps/console/tsconfig.node.json 收的是 ../../scripts/vite-*.ts
(匹配不到 vitest-invocation-guard.mjs)—— 没有任何 tsconfig 覆盖到本次改动。作为实证跑了
tsc -b apps/console/tsconfig.node.json --force → exit 0。

changeset:按仓内先例(#3253 / #3273 / #3278 等纯 infra/CI 改动均无 changeset)不加 —— 本 PR
不触及任何已发布包的源码。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 6, 2026 4:04am