Civitai 测试基础设施迁移指南:从逐文件 vi.mock 迁移到共享模块规范 Mock
Civitai 测试基础设施迁移指南:从逐文件 vi.mock 迁移到共享模块规范 Mock
本文是 shared-module-mock-migration.md 的完整解读与仓库源码级展开。它聚焦于 Civitai 测试基建中一个被刻意保留下来的实战场景:当你新增的测试文件直接对
~/server/db/client、~/server/redis/client或~/server/logging/client调用了vi.mock,触发了no-direct-shared-module-mock守卫失败时,如何用 codemod 把该文件迁移到仓库既有的"规范共享 Mock"(canonical shared mocks)之上。读完本文,你将掌握:codemod 的三种调用形态与安全边界、按频次排序的拒绝原因及逐一手工修复手法、~/env/server的双桶规则、两种失效断言的改写方式、以"收集计数"而非"红绿颜色"为核心的验证流程,以及翻转isolate: false前的全量门槛检查。底层机制与设计哲学请先阅读姊妹篇 shared-module-mocks.md。
⚠️ 阅读前提(务必先读):2026-08-16 起,本迁移所服务的"批量迁移"已暂停。它本是为了让
isolate: false在整套测试中安全落地,但实测收益呈凸性——迁移 43% 的文件只换来 3% 的导入节省,100% 迁移才拿到 66%,而全量迁移需要横跨 354 个 specifier、改造 601 个文件;unit-fast(#3975)最终被关闭而非合并。然而本文的配方对仍然存在的唯一场景依然准确且有效:当no-direct-shared-module-mock守卫因你新增的直接vi.mock而让构建失败时,按本文操作即可。不要把它当作一份需要逐步完成的工作积压。
适用范围:三个共享基础设施客户端
本文的迁移对象是三个"共享 specifier"——它们被大量测试文件直接 mock,且每个都在 src/__tests__/mocks/ 下拥有一个规范 Mock 模块:
| specifier | 规范 Mock 模块 | 客户端根节点 | 语义 |
|---|---|---|---|
~/server/db/client |
db.mock.ts | dbRead / dbWrite |
Prisma 读写客户端 |
~/server/redis/client |
redis.mock.ts | redis / sysRedis |
Redis 客户端及其系统键空间 |
~/server/logging/client |
logging.mock.ts | logToAxiom |
Axiom 日志通道 |
这三个模块在 guarded-specifiers.ts 中被定义为 CANONICAL_SPECIFIERS,即"已有规范 Mock、禁止再直接 mock"的一组。守卫测试 no-direct-shared-module-mock.test.ts 通过扫描 src/**/*.test.{ts,tsx} 中是否存在 vi.mock('~/server/db/client', …) 之类的调用(同时匹配 ~/… 与相对路径两种写法,见 mockPattern)来判定违规,并携带一个只减不增的 allowlist。
第 1 步:运行 codemod
迁移入口是 codemod-shared-mocks.mjs,一个基于 TypeScript AST(typescript 包)的静态重写工具。三种调用形态:
# 1. 全仓 dry-run:只扫描、只报告,不写任何文件(repo-wide 安全)
node scripts/test-perf/codemod-shared-mocks.mjs --dry --report .test-perf/codemod-report.json
# 2. 显式列出要转换的文件
node scripts/test-perf/codemod-shared-mocks.mjs --write <file>...
# 3. 通过文件列表传入(Windows 下规避 8191 字符的命令行长度上限)
node scripts/test-perf/codemod-shared-mocks.mjs --write --list <file-of-paths>
🔴 铁律:永远通过 --list 传入属于你自己的文件清单再 --write。 裸 --write 会转换仓库里每一个可转换的文件——这正是某次一个 Agent 静默重写了属于另一个人的 53 个文件的原因。--dry 在仓库范围内是安全的,因为它只读不写。
codemod 的安全边界与拒绝哲学
从 convert() 的实现可以看出,codemod 只转换它能证明等价的形状,并且"要么针对某个 specifier 全量转换,要么原样保留"——绝无部分转换,因为残留的 vi.mock 会重新毒化整个 worker。每次拒绝都会附带原因,最终以计数形式汇总(如 N candidate files | M convertible | K with refusals),并按原因分组打印频次;若开启了 --report,机器可读的 JSON 会写入指定路径(main())。
目前它能处理的形状包括:
vi.mock('…', () => ({ dbRead: { model: { findMany: localSpy } } }))—— 直接绑定本地 spy;importOriginal展开(简洁箭头体与块体两种写法都支持);const { a, b } = vi.hoisted(() => ({ a: vi.fn(), b: vi.fn() }))—— 只移除被转换的条目,保留 hoisted 对象中供其他 mock 使用的剩余部分;- 整个客户端以 spy 对象字面量构建(如
mockDbRead: { $queryRaw: vi.fn(), collection: { findFirstOrThrow: vi.fn() } }),折叠为const mockDbRead = dbMock.dbRead—— 绑定根节点后,每个叶子都会在字面量命名的路径上自动"激活"(vivify); vi.hoisted使用块体、返回属性名指向本地变量时,会解析该标识符到其字面量,并在"该块只读取它恰好一次"的前提下连同本地声明一并删除——因此被两个客户端共享的make()辅助函数会原样保留;- 手写的
REDIS_KEYS/REDIS_SYS_KEYS,与真实常量表做深比较(详见下文"常量漂移"); - 内联 spy 只是复述规范默认值(如
findUnique: vi.fn(async () => null))—— 删除是无副作用的; - 纯透传包装器(
findMany: (...args) => localFn(...args))—— 它们存在的唯一目的是让工厂能触达 hoisted 本地变量,工厂消失后便毫无意义。
任何携带真实行为的叶子永远被拒绝而非丢弃。这就是 codemod 在所有地方坚守的底线:转换它可证明等价的部分,其余的全部报告出来(见 collect() 中 refusals.push 的各个分支)。
第 2 步:按频次处理拒绝项
以下是按出现频率排序的拒绝原因及手工处理方式。
factory declares an export the canonical mock does not own: REDIS_KEYS
工厂在客户端旁边手写了真实常量的一部分:
vi.mock('~/server/redis/client', () => ({
redis: { packed: { get: vi.fn() } },
REDIS_KEYS: { CACHES: { PUBLIC_MODEL_RESPONSE: 'packed:caches:public-model-response' } },
}));
规范注册通过展开原始包来提供这些常量(见 setup.ts),因此删除手写副本后,测试拿到的是真实的 REDIS_KEYS。codemod 替你完成比较:它静态解析 packages/civitai-redis/src/client.ts 中的 REDIS_KEYS_UNPREFIXED / REDIS_SYS_KEYS(见 realConstants()——注意 REDIS_KEYS 是 applyCacheKeyPrefix(REDIS_KEYS_UNPREFIXED) 的结果,而测试环境下未设置 CACHE_KEY_NAMESPACE,该函数等价于恒等变换),当每个叶子都匹配时删除字面量,不匹配时拒绝,并在 CONSTANTS THAT DRIFTED FROM THE REAL VALUE 一节打印分歧。
实测:42 个文件存在分歧,横跨 73 个叶子。有些是占位符("rl"、"kill");有些看起来像真的但确实错了——CACHE_LOCKS 写成 "caches:lock" 而真实值是 "cache-lock",TRPC.LIMIT.BASE 写成 "trpc:rate-limit" 而真实值是 "packed:trpc:limit",还有一个 system: 前缀的 sys key 漏写了前缀。它们都不是线上 bug,因为测试用同一份错误字符串在自身两侧做断言——这正是为什么仓库里没有任何东西会让它们浮出水面。
🔴 预期:真实常量换入后会出现红测,且不要用恢复手写副本来"修复"。 一个变红的测试,是在把自己的期望字符串硬编码进 fixture,而不是在断言行为。这个红就是发现。
⚠️ 同时预期:它们中的大多数不会变红——那才是更糟的情况。 在某一个切片中,替换了九个虚构常量,没有一个产生失败——没有受影响的测试在自身工厂之外引用过它们,所以比较的两端都是 fixture 的发明。一个无人断言的漂移常量在两个方向上都不可见:它不会失败,也无法被审查。其中九个里有六个是 new-order 键,其 fixture 名称是真实键的看似合理的变体(如 new-order:sanity-check-failures 对真实值 new-order:sanity-failures)——这正是它们能通过阅读审查存活的原因。唯一能让它们浮出水面的手段就是换入真实值——所以即使套件保持绿色,也要记录 codemod 报告的漂移项。
local "mockDb" aliases dbMock.dbRead and dbMock.dbWrite
一个 spy 同时服务两个客户端,导致 dbWrite 调用能满足 dbRead 的断言。规范 Mock 中 dbRead 与 dbWrite 是刻意不同的两个节点(db.mock.ts 明确注释了这一点,shared-mocks.test.ts 中也有 expect(dbMock.dbRead).not.toBe(dbMock.dbWrite) 的断言),因此需要拆分并命名代码实际触达的那个客户端。预期其中一部分会变红——那是碰撞浮出水面,不是回归。不要把它们再别名回去。
hoisted entry is not a bare vi.fn() / no module-scope declaration found
通常是带 make() 辅助函数的手工构建客户端工厂:
const { mockRead, mockWrite } = vi.hoisted(() => {
const make = () => ({ appListing: { findUnique: vi.fn(async () => null) }, … });
return { mockRead: make(), mockWrite: make() };
});
vi.mock('~/server/db/client', () => ({ dbRead: mockRead, dbWrite: mockWrite }));
手工处理:删除 vi.hoisted 与 vi.mock,然后替换为:
import { dbMock } from '~/__tests__/mocks/db.mock';
const mockRead = dbMock.dbRead;
const mockWrite = dbMock.dbWrite;
文件其余部分无需任何编辑。阅读旧的 make(),只保留不是规范默认值的行为——create: async (args) => args.data、updateMany: async () => ({ count: 1 }) 之类——作为文件 beforeEach 中显式的 mockImplementation 调用。findUnique → null、findMany → []、count → 0 已经是默认值,复述它们只是噪音。
inline behaviour at …
规范默认值覆盖不到的行为。保留它,在 beforeEach 中以 mockResolvedValue / mockImplementation 形式挂到规范节点上即可。注意 codemod 的"提升"(lift)机制只允许出现在方法位置——在客户端根节点(redis、dbRead)上包装整个客户端对象作为 spy 实现,会静默丢失其上所有方法(scanIterator 不再产出、del 消失),一个断言"什么都没被删除"的测试会因此变绿(collect() 中记录了这起由 archer 的五文件探针发现的事故:文件零拒绝地完成转换,却丢了八个断言)。
第 2b 步:~/env/server 拥有其他模块没有的第二个桶
🔴 逐文件覆盖无法影响在 MODULE 作用域读取的值。 在 isolate: false 下,被测模块在每个 worker 中只求值一次,因此只有恰好触发那次求值的文件能看到自己的覆盖。其后的每个文件读到的都是当时已就位的值。
这不是规范 Mock 的缺陷——逐文件的 vi.mock('~/env/server') 工厂有完全相同的问题,因为它同样每个 worker 只运行一次。不要试图通过退回逐文件 mock 来"修复"它。
因此 env 分为两个桶:
| 值的读取时机 | 放哪里 |
|---|---|
模块作用域(const host = new URL(env.S3_UPLOAD_ENDPOINT)、pLimit(env.X)) |
env.mock.ts 中的 TEST_ENV_DEFAULTS —— worker 级,在任何 import 之前设置 |
| 调用时(测试调用的函数内部) | 测试文件中的 setEnv({ … }) —— 逐文件,文件之间重置 |
对应地,env.mock.ts 实现了两层读取:setEnvDefaults() 写 worker 级 defaults 表,setEnv() 写逐文件 overrides 表,read() 优先读 overrides、其次读 defaults(read())。resetEnv() 只清 overrides,不清 defaults——因为模块在 import 时读过一次的值,无法被重新回答(index.ts 对此有明确注释)。另外,defaults 的基底不是手抄的,而是通过解析 serverSchema 中每个字段的 .default() 动态推导(schemaDefaults()),因此 schema 中新增 .default() 会自动出现,杜绝了 OC-317 那种手抄清单静默漂移的问题。
工作示例:三个 clickhouse/__tests__/tracker.*.test.ts 文件各自携带一份提供 CLICKHOUSE_TRACKER_URL 的 vi.mock('~/env/server'),而 clickhouse/client.ts 在模块作用域读取它。把那个字符串移入 defaults 并删除全部三个逐文件 mock,清掉了 11 个失败。
⚠️ 陷阱:测试经常用 Object.defineProperty(env, 'FLAG', …) 翻转单个变量。如果 proxy 上报的 descriptor 与随后 defineProperty 写入的内容不一致,第二次调用会抛 TypeError: Cannot redefine property——表现为一个文件里十几个互不相关的失败,症状完全指向不到病因。env.mock.ts 的 proxy 实现了 defineProperty / set / deleteProperty / getOwnPropertyDescriptor 的一致语义(descriptor 始终携带 value 且保持 configurable: true,getter 以 __envAccessor 标记并每次访问时重读);若你要扩展它,请保持这种一致性。
有些 env 测试无法迁移,这是 flag 的属性而非 Mock 的缺口
一个测试在模块作用域双向设置的布尔量——IS_BUILD、IS_DATAPACKET——在 isolate: false 下无法用任何机制实现逐文件变化。读取它的模块每个 worker 只求值一次,只有第一个文件的值永远可见。这不是规范 env Mock 的缺陷;逐文件 vi.mock 工厂有完全相同的问题,任何未来的方案也都会有。
这些测试的存在正是为了验证 build-vs-runtime 与 datapacket-vs-not 行为,所以选项是:停止通过 env 测试它——改为 mock 消费方模块导出的结果——或者让这些文件保持隔离。把它们当作永久排除项,而非剩余工作,也不要让一个包含它们的未迁移计数读起来像"还有进展要做"。
第 3 步:修复两种失效的断言形态
缺席断言(Absence assertions)。 测试可能通过 fixture 缺少某个方法来证明一条代码路径:
expect((db.dbRead.appBlockPublishRequest as Record<string, unknown>).findFirst).toBeUndefined();
规范 Mock 会激活每一个方法,缺席不再可观测。改写为行为化断言:
expect(dbMock.dbRead.appBlockPublishRequest.findFirst).not.toHaveBeenCalled();
这更强而不是更弱:如果读取被路由到副本,包括另一个文件已填充该方法之后,它依然会失败。工作示例见 purge-review-snapshots.test.ts(其中 mockFindFirst、mockFindMany 均取自 dbMock,并在 beforeEach 中显式 mockReset + 配置返回值)。
节点上的 toBeUndefined() 在设计上就是错的,尽管它看起来像显而易见的检查。 未设置的属性依然会激活成节点,所以断言会以 expected <a href="https://link.gitcode.com/i/bfbabd22b6de9b2386b6005825ed34e6" target="_blank">Function Mock] to be undefined 失败。当你想表达"上一个文件的值没有存活下来",请直说:expect(node.isReady).not.toBe(false)。赋值的数据属性会被跟踪并在每个文件间清除——sysRedis.isReady = false 就是真实案例——但"已清除"意味着赋值没了,而不是属性读起来像缺席。[hybrid.ts 解释了为何必须如此:没有 set 陷阱的话,赋值会落到底层 vi.fn 的自有属性上,而 mockReset() 只清 mock 状态不清任意属性,在 isolate: false 下该值会存活整个 worker 生命周期并泄漏进后续每个文件。
对键做断言:命名常量,且线值只钉一次。
expect(incrKey).toContain(REDIS_SYS_KEYS.BLOCKS.REVIEW_RUN_FOR_REAL_BUZZ_CAP);
expect(REDIS_SYS_KEYS.BLOCKS.REVIEW_RUN_FOR_REAL_BUZZ_CAP)
.toBe('system:blocks:review-run-for-real-buzz-cap');
它们守护的是不同的失败,谁也不包含谁。在行为断言中命名常量,能阻止测试重新发明键——正是那个一天之内造出十四个虚构值的类别。golden value 让重命名变得响亮:键的线值寻址的是部署代码写下的线上 Redis 条目,改变它会遗弃旧名之下的所有内容,这应该是刻意的决策,而不是测试静默跟随的东西。
beforeEach 中冗余的 mockReset()。 无害,但全局 setup 已经在文件被 import 之前重置了每个节点。既然已经在文件里,就删掉它;注意 mockReset() 也会清掉规范 DEFAULT,所以一个依赖 reset 后 findMany → [] 的测试必须自己设置该值。
第 4 步:验证——用计数,永远不用颜色
在 --no-isolate 下,模块作用域抛错的文件会收集到 ZERO 个测试。失败计数不会上升,运行可能读起来是绿的,而测试其实根本不在。所以:
node scripts/test-perf/run-pilot.mjs --label mine-iso-4 --workers 4 --list <list>
node scripts/test-perf/run-pilot.mjs --label mine-noiso-4 --workers 4 --no-isolate --list <list>
node scripts/test-perf/compare-runs.mjs mine-iso-4 mine-noiso-4
run-pilot.mjs 在指定 worker 数与隔离模式下运行 pilot 文件集,并把逐文件计时/失败 JSON 写入 .test-perf/runs/。它通过 node node_modules/vitest/vitest.mjs 直接派生 vitest(不经 .bin shim 与 shell)——几百个文件路径会撑爆 cmd.exe 的 8191 字符命令行,且失败会以普通非零退出码呈现,读起来像套件失败。而 compare-runs.mjs 先 diff 逐文件收集计数、把计数回归打印在失败之前,且任何文件收集到的测试变少就非零退出,哪怕零失败。
还有两条规则,都是在这个环境里用代价换来的:
- 在两个 worker 数下验证。 失败集合是顺序相关的——同一份代码、同一个 flag,8 个 worker 下 1574 个失败,31 个 worker 下 1161 个。单宽度下的绿跑不是证据。
- 绝不要用
| tail或| grep读套件结果。 你拿到的是管道的退出码。重定向到文件,再读文件。
在宣布一组文件迁移完成之前,确认其中没有任何文件仍在 mock 规范 specifier:
node scripts/test-perf/residual-mocks.mjs <list>
residual-mocks.mjs 扫描清单中仍直接 mock 三个规范 specifier 的文件并写入 .test-perf/residual-mocks.json。单个掉队文件会把自己的 mock 形状冻结进其 worker 中的每个消费模块,所以部分迁移的集合测量的是掉队者而非系统。实测:同一份 174 个文件,在 83 个已迁移时从 404 个失败降到 290,而完全干净的 83 个单独跑只有 11 个失败。
第 5 步:更新 allowlist
node scripts/test-perf/gen-mock-allowlist.mjs
🔴 allowlist 是派生状态。任何触碰测试文件的 merge 之后都必须重新生成。 解决冲突时取双方通常是对的,但如果一方删除了一个直接 mock,该文件现在已迁移,其 allowlist 条目就过期了——这会让守卫的第二个方向失败。这事已经发生过一次(在某个集成分支上),而那次守卫是 16,806 个测试的运行中唯一的失败。
gen-mock-allowlist.mjs 写入 src/tests/mocks/direct-mock-allowlist.json,并且拒绝增长——一次会新增条目的运行会以非零退出并点名那些条目,因为列表增长意味着有人新增了直接 mock,而守卫存在的意义就是阻止这个。no-direct-shared-module-mock 测试(no-direct-shared-module-mock.test.ts)还会对不再 mock 任何东西的条目报错,所以列表无法被充数;它的长度就是迁移的剩余工作量。注意该守卫还带有正向控制(expect(scanned).toBeGreaterThan(800)),防止扫描树静默缩小后所有断言变成空洞真值;并且扫描在测试内部执行而非模块作用域——历史上它曾因模块作用域抛错而收集零测试、在每次全量运行中缺席、以命名文件方式调用时却总是通过。
翻转门槛——在翻转前一刻,跑一次全量套件的收集计数 diff
🔴 这是阻塞性前提,不是建议。 isolate: false 在确切要发布的树上通过以下检查之前不得上线:
# 同一时间窗口,背靠背
<whole unit suite, migration branch> --label flip-candidate
<whole unit suite, main control> --label flip-control
node scripts/test-perf/compare-runs.mjs flip-control flip-candidate
通过条件,全部满足:
- 零个文件比 control 收集到的测试更少;
- 分支新增的每个文件至少收集到一个测试;
- 总数完全相等——不是"没有新失败",不是"没有回归",而是计数相等;
- 跑全量套件,而不是按切片跑;
- 在翻转前立刻跑,而不是迁移期间跑一次。
新增文件条件的存在,是因为第一个条件有个洞,而这个洞是通过跑门槛而非推理发现的。分支新增的文件在 control 侧没有可对比的对手,所以它可以收集 zero 个测试并且 diff 完美干净。这正是本项目自己的迁移守卫曾经以惰性形态上线的方式:它在每次全量套件运行中收集阶段就抛错、贡献零测试,而以命名文件方式被调用时却总是通过——于是它被检查了一整天。
最后两个条件才是重点,且各有原因。
全量套件,因为按切片的验证既正确又不充分。 每个切片负责人对自己文件做逐文件收集计数 diff 是正确的实践,但它仍然留着一个缺口:一个无人认领的文件可能收集零个测试,而没有任何负责人的 control 覆盖到它。这不是假设。规范 Mock 注册时带过一个 importOriginal 展开,让一个文件在模块作用域死掉、贡献为零;120 文件 pilot 用逐文件收集计数验证过,却不可能抓到它,因为受影响的文件在集合之外。它是由某人在转换任何东西之前对另一个切片跑 control 时发现的。失败不在任何人的工作里——它在所有人工作的缝隙里。
翻转前立刻跑,因为这个性质只对特定的一棵树成立。 迁移期间的一次干净 diff,说明不了三百次转换之后的树。这是对"要发布的东西"的门槛,不是里程碑。
它很便宜。 2026-08-15 的全量集成运行是 1069 个文件 / 16806 个测试、0 个零收集文件,约四分钟。这项检查已证明在完整规模下有效;它是一次运行,不是一个项目。
为什么一行摘要满足不了它
在 --no-isolate 下,模块作用域抛错的文件收集 zero 个测试。失败计数不上升。运行读起来是绿的。迁移期间发现的每个实例都以那种方式呈现,没有一个看起来像错误:
- mock 工厂在预打包(pre-bundling)下缺了
default键:收集到 7 个测试而非 106 个,报告为 1 个失败; importOriginal-on-a-shim 回归:870 通过、0 失败,一个文件贡献为零;- 缺了
event-engine-common子模块(预先存在,CLAUDE.md 有记录):整个套件收集 0 却仍读作通过。
compare-runs.mjs 就是为此而生的:它把收集计数回归打印在失败之前,并且在零失败时也因计数回归而非零退出。
规范的三个并不构成静默类别的边界
对任何多导出模块的全量 vi.mock 都会引发它。有一次一个测试 mock 了 ~/server/utils/server-domain——14 个导出——却只给了单键工厂;在 --no-isolate 下这冻结了该 worker 中的模块,之后某个消费方触达其余 13 个导出之一的文件在模块作用域死掉、收集零测试。它在每个 worker 数下干掉的是不同的文件,这正是它表现为偶发而非单个坏文件的原因。
所以当一个已迁移集合仍有零收集时,在 --no-isolate 日志里 grep No "<export>" export is defined on the——这条消息点名了被毒化的模块,而且通常不是这三个之一。对已迁移集合做一次"多导出模块全量 mock"扫描,是廉价的预防手段。
门槛抓不到什么
收集计数与 residual-mocks.mjs 检测的是缺席——一个丢失了测试的文件、一个仍被直接 mock 的 specifier。两者都看不见一个仍在运行、仍在通过、却已不再断言任何真实内容的测试。
这也不是假设。有一个 codemod 形状丢掉了工厂的 withSysReadDeadline,让 session-verifier.test.ts 的两条 fail-open 分支在断言虚无的情况下通过——因为测试替换成 spy 的那个导出,正是它注入超时的方式。另一个把整个客户端对象包成了叶子 spy:每个方法消失、调用返回空而非抛错,一个断言"什么都没被删除"的测试会变绿。两个文件都以零拒绝完成转换、保住了每个测试、在 residuals 上读起来干净。
抓住它们的是在断言层面、小集合上、由没写工具的人跑的一对 control。在门槛之外持续这样做;那是门槛做不到的一半。
以及一般形式,它比这次迁移活得更久
这一天最有价值的两个发现,都来自别人对另一个人的工作跑 control——而非作者自己的验证,那很仔细并且通过了。第三次修正方向相反,从作者到审查者。一天三次,两个方向都有。
作者验证他们改过的东西。没人验证的是他们周围被改动的东西。在多人分担的工作上,至少预算一次不属于任何切片的全量套件独立 control。
悬而未决的问题:browser-mode 测试
守卫检测 .test.tsx——否则一个 .browser.test.tsx 添加直接规范 mock 会成为它在结构上无法观测的类别,这与"恰好为空的类别"不同。而 codemod 刻意只处理 .ts:转换 browser-mode 文件会把它放进规范 Mock 从未被验证过的环境,一次 glob 改动会让那看起来像受支持的路径。
注意缺失的形态比"browser mode 能否工作"更窄:今天有 zero 个 .tsx 文件 mock 规范 specifier,所以证明它需要有人写一个,而不是迁移一个。这是一份工作,不是一次验证。
本配方不覆盖的内容
~/env/server(114 处)、~/server/services/buzz.service(98 处)、~/server/services/image.service(88 处)。基础设施客户端适合一个自动激活的单一原语;服务模块有手写的表面,所以它的规范 Mock 是手写的 stub,那是另一份工作。~/env/server 之后已被单独完成——它需要的是值表而非调用表面,见上文双桶规则。guarded-specifiers.ts 的 PENDING_SPECIFIERS 记录了下一梯队的候选项,且明确标注它是下限而非清单:specifier 会从另一个方向不断到来——即对列表上所有项都 residual-clean 的文件集在 --no-isolate 下跑出的失败中。
它也不覆盖生产代码中的模块作用域状态。一个断言 import 时副作用的测试——如 eventloop-longtask.ts 把指标注册进真实的 prom registry——在 --no-isolate 下会失败,因为模块每个 worker 只 import 一次,第一个触达它的文件拿走注册。那属于 no-module-scope-cache 的范畴,不在这里。
与机制文档的衔接
本文是"配方"(怎么做),而机制与设计在 shared-module-mocks.md:为何 vi.mock 是逐文件的而模块实例是逐 worker 的、毒化如何经由共享的非测试模块传播、混合 callable proxy 原语(hybrid.ts)如何让 dbRead.image.findMany、dbRead.$queryRaw、redis.packed.get 无需枚举即可存在、规范默认值表(findMany → <a href="https://link.gitcode.com/i/1c03464903230e4b837a715fcb09f3d2" target="_blank">]、findUnique → null、count → 0、$queryRaw → []、$executeRaw → 0、$transaction 运行回调)为何刻意保守、以及"每个 specifier 全有或全无"的迁移约束。注册入口在 [src/tests/setup.ts:规范 Mock 通过展开底层包而非对 shim 使用 importOriginal 注册——~/server/db/client 与 ~/server/redis/client 是 shim,它们既整包 re-export 又在模块作用域构造真实客户端,importOriginal 会把真实的 Prisma/Redis 构造强塞进每一个测试文件(process-vault-items.test.ts 正是因此死在模块作用域、收集零测试而失败计数纹丝不动)。底层的每文件重置钩子 resetSharedMocks() 在 mocks/index.ts,它在两种隔离模式下都正确:isolate: true 时注册表每个文件重建、重置是 no-op,isolate: false 时它才是唯一清除实现与调用计数的东西。