跳转至

为什么有这条

一次对抗审查(glm53,v0.16.21 快照)的判断:

测试体系给人的「有回归网」印象:实测把关键依赖从 deps 删掉全绿, 所谓钉住是源码字面正则……真正的行为级测试至今没有。

实证在同一天就出现了:ISSUE-0205 把两处重复的判据合流成一个函数后, 行为完全正确、一条字面判据却红了 —— 它量的是「那行代码长什么样」。

根因不是偷懒,是基建的天花板:在此之前全仓 environment: 'node', 没有 jsdom、没有 testing-library。React 组件的行为在结构上无法验证, 于是所有「钉住 UI 行为」的判据都只能退化成 grep。

现在的基建(v0.16.24 起)

vitest.config.ts 是两个 project,environment 完全隔离:

project 匹配 环境 用途
node tests/**/*.test.ts node 纯逻辑。与改造前逐字相同,零风险
dom tests/**/*.test.tsx jsdom 渲染真实 MUI 组件,断言用户看到/点到的东西

配套:

  • tests/setup-dom.ts —— ResizeObserver / matchMedia / IntersectionObserver / scrollTo 的 polyfill。每条都对应 jsdom 的一个真实缺口,注释里写了为什么,别删。
  • tests/render-app.tsx —— 统一渲染入口,套项目真实的 ThemeProvider。 🔴 不要自己造一个简化 theme:那等于让测试跑在一套和线上不同的样式系统上。
  • tests/stubs/wxt-browser.ts / wxt-storage.ts —— wxt/* 的替身, 经 dom project 的 resolve.alias 生效(node project 的解析逐字未动)。 🔴 替身只负责「加载不炸」,不假装行为像真的。要断言交互的测试自己 vi.mock 覆盖掉具体那个方法 —— 两件事混在一起,就会在替身的假数据上得出假结论。

🔴 改造既有判据时最容易踩的一个坑

不要在原来的 .test.ts 里加组件 import —— 新建一个 .test.tsx。

.test.ts 跑在 node project,那里没有 wxt stub(alias 只配在 dom project)。 一旦 import 链上出现任何加载 wxt/browser 的模块,整个文件在收集阶段就炸:

Error: This script should only be loaded in a browser extension.

而且它是 Failed Suites(收集失败),不是某条用例红 —— Tests 那一行的数字看起来还挺正常,容易被当成没事。

实测踩过(2026-09-21,一个执行方改 data-bar-adaptive.test.ts 时): 在原 .test.ts 里加了组件测试,文件整个加载不起来。

⇒ 正确做法:原 .test.ts 保留(或删掉被取代的那几条), 组件行为测试另起一个同名 .test.tsx。两个文件各跑各的 project,互不影响。

顺带:报用例总数时说清口径

npx vitest run 是两个 project 合计;--project node 只是其中一半。 拿这两个数去比会得出「测试丢了一百条」的错误结论 (2026-09-21 一次审查就因为口径不同报了 UNVERIFIABLE)。 报数字的时候把命令一起报出来。

怎么写一条行为级判据

// tests/mode-toggle.test.tsx
import { render, screen } from './render-app';   // ← 不是 @testing-library/react
import userEvent from '@testing-library/user-event';

it('每一个内置视图下,「快速」按钮都必须可点', () => {
  for (const v of BUILTIN_VIEWS) {
    const { unmount } = render(<ModeToggle {...base} filters={v.filters} />);
    expect(screen.getByRole('button', { name: '快速' })).toBeEnabled();
    unmount();
  }
});

判它写得对不对,看两件事:

  1. 纯重构不该让它红 —— 换变量名、换三元写法、抽函数,行为没变就该绿
  2. 变异必须让它红 —— 把那条 prop 的接线拆掉,它必须红

两条都要实测,不能只跑一遍看见绿就算完。

禁用状态验两层

// ① 真实用户层:MUI 给禁用按钮挂 pointer-events:none,user-event 会拒绝点击
await expect(userEvent.click(btn)).rejects.toThrow(/pointer-events/i);
// ② React 层:绕过 CSS 直接派发,验 disabled 真接进了组件
fireEvent.click(btn);
expect(onConfirm).not.toHaveBeenCalled();

只验 ①,CSS 换个写法就漏;只验 ②,用户物理上能不能点到没人管。

组件里有延迟渲染的,用 findBy 不用 getBy

TableViewsTabs 有 setTimeout(() => setActivateTab(true), 300)(绕 MUI 的 "value provided to Tabs is invalid" 警告)。前 300ms tablist 是空的, 同步查询会稳定地查不到任何 tab。

什么时候源码级判据才是对的

不是所有 readFileSync 判据都该改。 这三类源码级是正确形态,行为测试替代不了:

类型 例子 为什么行为测试不行
危险写法不许存在(absent) .catch(() => {}) 不许出现 行为测试只能证明「现在这条路对」,证明不了「没有别的路」
安全不变量 Key / 身份信息不许出现在某条网络路径上 同上,且漏一条就是泄露
单一入口没被绕开 某个网关函数是唯一出口 验的是代码结构,不是运行结果
配置正确性 manifest 字段 没有可渲染的东西

机器闸

pnpm scan:grep-as-behavior(已串进 pnpm verify)。

判据:.test.ts 里 readFileSync 了一个 .tsx,又拿它 toMatch 一个 JSX 属性/结构形状的模式(disabled={ / <Foo / {{)。

豁免:// SAFE: grep-as-behavior-ok — <为什么这条必须是源码级>

🔴 合格理由长这样:「这是静态不变量,行为测试证明不了『没有别的路』」 不合格:「改成组件测试太麻烦」「暂时先这样」—— 闸会识别这类成本借口并拒绝放行。

基线 19 处(v0.16.25 从 22 清掉 3 条:task-detail-paging / ai-ui-no-dead-ends 两条改成行为测试, dialog-fresh-mount 一条由另一刀改造)。每一条都欠着一次改造。

姊妹闸:pnpm scan:fake-wiring(v0.16.25 新增)

上面那道闸治「判据在量源码」,这道治它的上游 —— 判据验的接线在生产里根本不存在。

事故:ISSUE-0202 的「根因复现」测试直接渲染裸 <DataGridPremium>,断言抛 reading 'id',据此宣布根因已确证。对抗审查证伪:生产两个 wrapper 都传 getRowId={(row) => row?.[rowKey]},两种接线抛的是两条不同的错。 ⇒ 报错文本相同只是必要条件,不是根因证明。

判据:.test.tsx 里直接渲染第三方组件 X,而 src/ 里确实有 X 的生产接线, 且该渲染点与生产「每个渲染点都有、且内联箭头函数体逐字相同」的必接线属性零交集。

豁免:{/* SAFE: fake-wiring-ok — <为什么直接 render 是合法的> */} (exempt_verdict 同样拒绝「太麻烦」这类成本借口。)

自测 test-scan-fake-wiring.py 与姊妹闸同形:subprocess 跑真脚本,检测面 + 执法面, 外加 4 个我实际构造的误报样本(src 从不渲染的第三方 / 自定义组件 / @/ 别名 / react 原语)。

建这道闸时自己踩的三个坑

越是治某类错误的工具,越容易自己犯那类错误(本仓在 predicate-guard 上连犯三次)。 这次的自测 test-scan-grep-as-behavior.py 自己错了三次,全靠「破坏闸,看自测红不红」抓出来:

# 错法 症状
① 拿整条 key 比对,而 key 含临时目录路径 恒不等 ⇒ 假红
② 改成比 key.split("::",1)[1],而破坏方式是 path:line::sig split 恰好切掉含行号那半 ⇒ 恒相等、假绿
③ 用「往上反查 it('probe_」定位探针,而注释样本的命中行在 it( 之前 反查不到 ⇒ 返回空集 ⇒ 恒真

⇒ 每道闸的自测必须做「破坏闸本身,看自测会不会红」这一步。 自测跑绿只说明它没报错,不说明它在验东西。


🔴 附录:2026-09-21 那一轮的六次「声明 ≠ 实际」

这套 jsdom 基建建完后送了双路对抗审查(dshf + terra-dsh)。 两路加起来报了 7 条 X_FAKE,主控复核后几乎全部坐实。 把它们排在一起,会看到同一个模式:

# 写下的声明 实际 谁发现的
1 dispatch-gate 注释:「对 Workflow/Agent 默认硬拦」 settings.json 的 PreToolUse 没挂 Workflow matcher,323 个 agent 一次没被拦 主控自查
2 根因 issue:「喂 null 给 DataGrid 必抛 reading 'id',已实测复现」 用的是裸 DataGrid 无 getRowId,生产没有任何地方那么用;生产抛的是另一条错 dshf
3 代码注释:「tableData 是 DataGrid 的唯一入口」 page-results 是另一条活路径 dshf
4 commit:「净化接上两处就修好了」 净化在真崩溃点的下游,毫无作用 dshf
5 闸自测:6 条全绿即覆盖 只 exec 到主函数之前,执法层永远在观测范围外;塞一行 fresh = [] 闸变永久绿灯而自测全绿 dshf
6 stub 头注:「响亮地什么都不做,不假装成功」 sendMessage 永远返回 {success:true} terra
7 stub 头注:「每个测试文件自己的模块实例,天然隔离」 同一文件多个 it 串味;__resetStorage 导出了零调用 terra
8 代码注释:「派生统计/筛选均与顺序无关」 邮箱列表去重是首遇优先,顺序决定显示哪个商家名 terra

共同点

每一条的声明都是作者自己写的,紧挨着自己写的实现。 不是年久失修,不是别人留的坑 —— 是写下那句话的同一分钟里就不成立。

而且第 5 条最刺眼:那是一道专门用来治「判据在量别的东西」的闸, 它自己的判据就在量别的东西。越是治某类错误的工具,越容易在那一类上失守 (本仓 predicate-guard 已经连犯三次,这是第四个案例)。

可操作的防线

① 写「已确证」之前,先问「我验的是生产的那条接线吗」

第 2 条的教训:报错文本相同只是必要条件。 我构造了一个能产出同样字符串的最小样例,就以为找到了根因。 判据:去 grep 生产代码里那个组件/函数实际是怎么被调用的, 用那个调用形态复现。复现不出来,就说「未确证」。

② 写「唯一入口」之前,先证明没有第二条路

第 3 条的教训:这是个让人放心省略下游防御的论证, 所以它错的代价不是「多写几行」,是「以为防住了其实没防」。 判据:grep -rn 找所有到达同一动作的路径,列出来,一条条排除。

③ 净化 / 校验 / 守卫要放在第一个会崩的地方的上游,不是「出口」

第 4 条的教训:「出口」是个直觉词,不是位置。 判据:把会崩的那几行逐个列出来,看守卫在它们之前还是之后。

④ 每道闸的自测必须跑真实脚本,断言退出码

第 5 条的教训:exec(源码切一半) 拿到的只是检测函数, 基线比对、--diff、退出码这些「执法」逻辑全在观测范围外。 判据:自测用 subprocess 跑真脚本 + 临时基线目录,至少覆盖 「新增违规必红」「基线缺席 fail-closed」「基线格式错 fail-closed」。 并且做一次破坏验证:在主函数里塞一行让它永久绿灯,自测必须红。

⑤ 写在头注里的设计原则,要有一条判据钉住它

第 6、7 条的教训:「不假装成功」「天然隔离」都是可验证的断言, 写下来却没有任何东西检查它们。 判据:头注里每写一句「本模块保证 X」,就配一条测试验 X。 验不了的,就别写成保证,写成「意图」。

⑥ 写「与 X 无关」之前,先找 X 的消费者

第 8 条的教训:「顺序无关」是个关于下游的断言, 而作者只看了上游。 判据:grep 那个值的所有消费者,逐个看它们依赖什么。

🔴 它不只发生在测试里 —— 核验流程本身也会「量别的东西」

2026-09-22 一天之内,主控在核验这个动作上犯了四次同一个错。 前三次在判断「执行方做到没有」,第四次在判断「进程还活着没有」:

# 我用的判据 实际在量什么 真相
① grep "!canEvalClientSide(filters)" 在源码里 那行代码长什么样 判据合流后行为正确、判据却红
② grep preparing 在 popup-data.ts 有没有那个字面量 它调的是 isTaskUnfinished(),比硬编码好
③ grep maxRetries\|backoff 在 recovery 文件 我猜的那几个变量名 (这次恰好对,但方法一样脆)
④ 产出文件 0 字节 + inflight 无 DONE 监控还在不在 进程一直活着,只是没写到收尾那步

第 ④ 次最值得记,因为它的信号看起来最硬:

系统通知:2 个 task 无完成记录,已标记 stopped
briefs/reworkHangFix.txt   0 字节
inflight.log               只有 START,没有 DONE

三个信号一致指向「它死了」。但三个说的都是同一件事 —— 会话重启杀掉的是主控这边的 Monitor task,而执行方是 dsh 起的 独立进程,跟会话生命周期无关。

真正的存活判据是 lsof:

lsof ~/.claude/tools/briefs/<label>.txt     # 有进程握着 ⇒ 还在写

监控脚本用的就是它(存活判据 → 已验·在跑(lsof 坐实有人握着输出文件)), 而我没查就下了结论,还把它正在写的中间态提交了。

可操作的

判「它还在不在」只认 lsof。 产出文件大小、inflight 记录、系统通知里的 「no completion record」——这三样都只能证明「我这边没收到收尾」, 证明不了「那边停了」。

更一般地:核验一个外部实体的状态时,先问「我这个信号是它产生的,还是我这边产生的」。 自己这边的缺失,不是对方的状态。

一句话

这一轮真正的产出不是那几个修复,是这张表。 修复能防住这八条;这张表想防住的是第九条。