《Electron 45.2.3 内核解剖》第 21 章 测试体系:当被测对象就是运行时本身

1 阅读45分钟

《Electron 45.2.3 内核解剖》第 21 章 测试体系:当被测对象就是运行时本身

21.0 五层边界,以及三条判据

普通 Node 项目的测试是一句话:npm test,然后一个测试框架把源码 import 进来跑。Electron 不行,原因不是"项目大",而是被测的东西根本不是一个可以被 import 的模块:

  • BrowserWindow 只有在 Electron 的浏览器进程里才存在,在 node 里连 require('electron') 都拿不到窗口类;
  • process.mas、process.windowsStore、isComponentBuild() 这些值由构建产物决定,源码里写多少 if 都模拟不出来;
  • screen.getCursorScreenPoint()、系统剪贴板、全局快捷键、窗口焦点、D-Bus 通知守护进程,全都指向同一台机器上的同一份全局状态,两个测试并行跑就会互相踩;
  • fuses 要翻转一个真实可执行文件里的字节,MSIX 更新器要装一个真实签名的包,Squirrel.Mac 要真的起一个 ShipIt launchd job(第 20 章那条链路)。

所以 Electron 的测试体系不是一层,是五层。每一层的"被测对象"和"启动方式"都不同:

层测的是什么跑在哪里入口需要的前提
L1 API specJS API 在主进程里的行为真实 Electron 浏览器进程script/spec-runner.js → vitest → 自定义 pool编译好的 Electron 可执行文件
L2 Node 上游 suiteElectron 的 Node 集成有没有破坏 Node 自身ELECTRON_RUN_AS_NODE=1 的同一个可执行文件script/node-spec-runner.jsthird_party/electron_node 完整 checkout
L3 NAN / 原生 ABI suite用 Electron 的头文件编译出来的 addon 能不能加载系统 Node + 编译产物script/nan-spec-runner.jsChromium clang / libc++ / gen/node_headers
L4 构建产物验证打包出来的二进制、driver、snapshot、asar 是不是自洽构建机上,直接跑产物verify-chromedriver.py / verify-mksnapshot.py / gn-asar-hash.js一个完整的 out 目录
L5 打包后行为签名、更新、安装包注册这些"只有在真实 app 上才存在"的路径临时克隆出来的 .app / 稀疏 MSIX 包codesign-helpers.ts / msix-helpers.ts代码签名证书 + OS 级包注册权限

前面二十章里遇到的每一个"文档没写的行为",几乎都能在这五层里找到一条对应的验证路径。反过来也成立:很多行为没有被测试,恰恰是因为它需要的前提在 CI 里造不出来。第 20 章讲过的 Linux quitAndInstall() 空函数、MAS 构建里的 g_crash_reporter_initialized 恒 false,就属于这一类。

这一章用三条判据贯穿全篇。看到任何一个测试配置,先问这三个问题,基本就能解释它为什么长这样:

  1. 进程身份:这段代码跑在哪个进程里?是 Electron 浏览器进程、ELECTRON_RUN_AS_NODE 的 Node 进程、宿主 CLI 的 Node 进程,还是 renderer?ipc-serialization.ts 里那一大段编码器,全部源于"CLI 的 V8 和 worker 的 V8 不是同一个版本"。
  2. 构建身份:这个二进制是 darwin 还是 mas,是 component build 还是 release,是 ASan 还是普通构建?spec/vitest.config.ts:125 里的 retry、CI 里的 ELECTRON_SPEC_TIMEOUT=180000,都是按构建身份调的。
  3. 机器独占性:这个测试要不要动焦点、剪贴板、屏幕、全局快捷键、D-Bus 服务?要,就必须进 serial 阶段,而且不能只靠 maxWorkers: 1——21.8 会解释为什么。

21.1 spec/ 的规模、命名规则与目录语法

先把这一章要讨论的对象量清楚。统计口径是 spec/ 下所有文件(find spec -type f),不是只看 spec 文件:

指标数值
spec/ 下文件总数1003
spec/*.spec.ts90 个
顶层 .ts 文件93 个(另外 3 个是 ambient.d.ts、pipe-transport.ts、vitest.config.ts)
90 个 spec 的总字符数3,035,172
总行数79,043
it( / test( 出现次数(粗略)约 3559
describe( 出现次数(粗略)约 1133
spec/fixtures/ 顶层条目35
spec/fixtures/apps/16 个独立 fixture app
spec/fixtures/native-addon/9 个
spec/lib/ helper16 个 .ts + 1 个 .cjs + 2 个 .js

90 个 spec 里,最大的十个按字符数排:

字符数文件
386,768api-browser-window.spec.ts
255,081chromium.spec.ts
233,586api-web-contents.spec.ts
185,702asar.spec.ts
118,545api-protocol.spec.ts
105,622api-app.spec.ts
97,973api-session.spec.ts
96,636api-net.spec.ts
94,431webview.spec.ts
83,785extensions.spec.ts

单个文件 38 万字符(api-browser-window.spec.ts 超过 7000 行)已经不是"一个测试文件",而是一本按 describe 分册的手册。这直接决定了 21.9 的分片策略:分片单位只能是文件,因为文件内部的 7000 行没法再切。

21.1.1 文件名不是约定,是被强制检查的

spec/vitest.config.ts:31-34 里有两行看起来多余的代码:

const specFiles = fs.readdirSync(specDir).filter((file) => /\.spec\.[tj]s$/.test(file));
const misnamed = fs.readdirSync(specDir).filter((file) => /-spec\.[cm]?[jt]sx?$/.test(file));
if (misnamed.length > 0) {
  throw new Error(`Spec files must be named *.spec.ts, rename: ${misnamed.join(', ')}`);
}

注释把原因写得很直白:include 只收 *.spec.ts,一个从旧分支(那时叫 *-spec.ts)合过来的 PR 文件会静默地永远不跑。没有任何报错、没有任何日志,CI 一片绿。所以这里不是"检查规范",是把静默漏测变成启动期硬失败。

这条规则和本书第 17 章反复出现的"静默失效"是同一种病:Electron 里最危险的不是抛异常,是不抛异常地什么都不做。测试框架自己也不能免疫。

21.1.2 spec/package.json:2-6 暴露了 L5 的存在

spec/ 是一个独立的 yarn 项目,有自己的 package.json、node_modules 和 lockfile:

spec/package.json:2-6

{
  "name": "electron-test-main",
  "productName": "Electron Test Main",
  "main": "index.js",
  "type": "module",
  "scripts": { "node-gyp-install": "node-gyp install" }
}

三个值得注意的点:

  • main: index.js —— 这个目录本身就是一个 Electron app。runner 不是把 spec 文件喂给一个通用框架,而是 electron spec/,把整个 spec/ 当作应用启动。21.7 会逐行拆 index.js。
  • type: module —— spec 里用原生 ESM 和 Node 的类型擦除(type stripping)加载,不经过 Vite 转换。vitest.config.ts:105 里 experimental: { viteModuleRunner: false, nodeLoader: false } 就是把 Vite 的模块管线彻底关掉,理由是"让 spec 以真实 app 加载模块的方式加载"。
  • devDependencies 里出现了 @electron/fuses、@electron/packager、@electron-ci/* 九个包、pdfjs-dist、winreg、dbus-native、abstract-socket。也就是说测试代码自己会去翻转 fuse、打包 app、装证书、起 D-Bus 服务。spec/package.json:38 是判断"这一层到底在测什么"最快的入口。

九个 @electron-ci/* 包与 spec/fixtures/native-addon/ 下的九个目录一一对应:dialog-helper、echo、external-ab、is-valid-window、mouse-input、object-wrap、osr-gpu、uv-dlopen、virtual-display。它们是为测试专门编译的原生模块,用来覆盖纯 JS 无法触达的路径(真实窗口句柄、uv_dlopen、GPU 共享纹理、虚拟显示器)。

21.1.3 spec/CLAUDE.md:一份写在仓库里的"踩坑清单"

这个文件不是给人看的文档,是给写测试的人(和给 AI)看的硬约束,五条全部来自真实事故:

- Never call expect() inside a stream or event listener ('data', 'message', 'exit').
  A failing assertion there is an uncaught exception, not a test failure:
  the spec runner exits with no summary and no JUnit file, and the whole
  shard goes red with nothing to point at.
- Wait for the output you expect, not for 'exit'. A chunk the child wrote
  just before exiting can still be in the pipe when 'exit' fires ...
- Don't assert on the first chunk from a pipe. stdout and stderr race ...
- Register every forked child with deferKillUtilityProcess ...
- Only kill a child that is still running (child.pid is set) ...

第一条尤其关键:在事件监听器里 expect() 失败,抛出的异常不在测试框架的调用栈上,vitest 无法把它归因到某个 test,结果整个进程退出,既没有汇总也没有 JUnit XML。而 21.11 讲的失败重跑机制完全依赖那份 XML——于是"一个断言写错位置"会导致整个 shard 连重试的机会都没有。

第二、三条是同一个物理事实的两种表述:'exit' 事件触发时,子进程刚写进管道的数据可能还在内核缓冲区里没被读出来;stdout 与 stderr 又各自独立,stderr 上一条 GPU 警告完全可以排在你等的那行前面。所以正确写法是累积输出、匹配模式、等累积结果出现,而不是等 'exit' 或断言第一块。

第四条和 21.6 的 defer() 机制直接咬合:测试超时后,afterEach 里"正常收尾"的代码可能根本没执行到,只有全局 defer() 注册的动作会被 runner 强制执行。第五条是反过来的一面:kill() 一个已经退出的子进程,再 await once(child, 'exit'),那个 once 永远等不到事件,测试挂到超时。

CLAUDE.md 后半段还有一条常被忽略的:

- Each process has its own userData directory; do not assume the default
  path, ask app.getPath('userData').

对应 spec/index.js 里给每个 worker 单独改 userData 的那行(21.7)。写死 ~/Library/Application Support/Electron 的测试在 CI 上必然读不到自己刚写的数据。

21.2 七层启动链:从 npm test 到一个 Electron 浏览器进程

npm test 只有一行:node ./script/spec-runner.js。但从这一行到某个 it() 真正执行,中间有七层,每一层都在做参数翻译或身份切换:

npm test
  └─ pretest: npm run create-typescript-definitions   (生成 electron.d.ts + ts-smoke 类型检查)
     └─ script/spec-runner.js            [宿主 Node 进程, CLI 侧]
        ├─ 启动前置: hash 比对 / 装 spec 依赖 / 虚拟打印机 / d.ts 兜底
        └─ toVitestInvocation()          [参数翻译 + 环境变量装配]
           └─ vitest CLI (spec/node_modules/vitest/vitest.mjs)  [宿主 Node 进程]
              ├─ globalSetup: ./vitest/global-setup.js          [清残留进程]
              ├─ pool: electronPool()   [自定义 PoolWorker, 宿主 Node 进程]
              │  └─ spawn(electron, [spec/, --vitest-worker, ...])  [真实 Electron 浏览器进程]
              │     └─ spec/index.js    [app ready 之前的所有全局配置]
              │        └─ spec/vitest/worker.ts  [把主进程交给 vitest worker runtime]
              └─ runner: ./vitest/runner.ts  [TestRunner 子类, 四个语义补丁]
                 └─ 某个 *.spec.ts 里的 it()

关键在第四层到第五层之间:vitest 的 CLI 跑在宿主 Node 里,而测试代码跑在 Electron 里。这两者不是同一个进程、不是同一个 V8、甚至不是同一个 Node 版本。整个 spec/vitest/ 目录(6 个文件、727 行)存在的意义就是把这条裂缝补上。

21.2.1 runners 只有一个成员

spec-runner.js:48-52 开头:

const runners = new Map([['main', { description: 'Main process specs', run: runMainProcessElectronTests }]]);

仓库里 script/node-spec-runner.js 与 nan-spec-runner.js 都还在,但已不在这张表中,改由 CI 单独调用(21.12)。--runners 参数会校验你传的是不是这张 Map 的子集;--electronVersion 更是硬限制:

spec-runner.js:48-52

if (args.electronVersion) {
  if (args.runners && args.runners !== 'main') {
    console.log(`${fail} only 'main' runner can be used with --electronVersion`);
    process.exit(1);
  }
  args.runners = 'main';
}

--electronVersion 走 @electron/fiddle-core 的 ElectronVersions / Installer:支持 latest、latest@<major>(取该 major 最后一个版本)、具体版本号(用 versions.isVersion() 校验),然后 installer.install(version) 下载一个已发布的 Electron 二进制来跑当前仓库的 spec。这是"用新二进制跑旧 spec"和"用旧二进制验证 API 兼容"的通道,也是唯一一条 npm_config_target / npm_config_disturl / npm_config_runtime=electron / npm_config_devdir=~/.electron-gyp / npm_config_build_from_source=true 全被打开的路径。

21.2.2 unknownArgs:runner 自己不懂的参数怎么传递

minimist 只声明了 6 个已知参数(skipYarnInstall、runners、target、electronVersion、enableRerun),其余全部通过 unknown 回调收集:

spec-runner.js:23-30

const args = minimist(process.argv, {
  boolean: ['skipYarnInstall'],
  string: ['runners', 'target', 'electronVersion'],
  number: ['enableRerun'],
  unknown: (arg) => unknownFlags.push(arg)
});
const unknownArgs = [];
for (const flag of unknownFlags) {
  unknownArgs.push(flag);
  const onlyFlag = flag.replace(/^-+/, '');
  if (args[onlyFlag]) unknownArgs.push(args[onlyFlag]);
}

注意第二层:--foo=bar 会被 minimist 拆成键 foo 和值 bar,但 unknown 回调只看到原始串;这里补一次 args[onlyFlag] 把值再推回去,于是 --enable-logging 后面的文件名、--log-file=... 之类才不会丢。runTestUsingElectron 里 unknownArgs.slice(2) 砍掉的是 process.argv 的前两项(node 路径与脚本路径),它们也会被 unknown 回调当成"未知参数"收进来。

这套手写转发很脆,但它是刻意的:CI 里传的是 --trace-uncaught --enable-logging --files ... --enableRerun=3,其中 --enable-logging 这类开关必须原样交到 Electron 进程的命令行上,而不是被 vitest 消化掉。

21.2.3 toVitestInvocation():三种参数,三个去处

spec-runner.js:535-542

function toVitestInvocation(exe, specDir, runnerArgs) {
  const specRoot = path.resolve(__dirname, '..', specDir);
  const files = [];
  const electronArgs = [];
  let grep = null;
  let invert = false;
  for (let i = 0; i < runnerArgs.length; i++) {
    const arg = String(runnerArgs[i]);
    const takeValue = () => (arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : String(runnerArgs[++i]));
    if (arg === '--files') {
      while (i + 1 < runnerArgs.length && !String(runnerArgs[i + 1]).startsWith('-')) {
        files.push(String(runnerArgs[++i]));
      }
    } else if (arg === '-g' || arg === '--grep' || arg.startsWith('--grep=') || arg.startsWith('-g=')) {
      grep = takeValue();
    } else if (arg === '-i' || arg === '--invert') {
      invert = true;
    } else {
      electronArgs.push(arg);
    }
  }
  ...
}

三条分流规则:

  • --files 是变长参数:一直吃到下一个 - 开头的串为止。CI 里 split-tests 输出的是一串空格分隔的文件名,正是靠这个吃法变成 vitest 的多个位置参数。文件路径再转成相对 specRoot 的路径(path.relative),并且逐个 fs.existsSync 检查——不存在的直接 process.exit(1),因为 vitest 对"过滤器没匹配到任何文件"是 passWithNoTests: true,会安静地返回成功。
  • -g / --grep 变成 vitest 的 --testNamePattern。-i / --invert 不是传给 vitest 的开关,而是把 pattern 改写成负向前瞻:^(?!.*(?:${grep}))。这是 21.11 失败重跑时用来"排除某个测试"的基础。
  • 其余一切(--trace-uncaught、--enable-logging=file、--log-file=...)都进 electronArgs,最后 join(' ') 塞进 ELECTRON_SPEC_WORKER_ARGS。split(' ') 还原时如果某个参数值里带空格就会被拆成两个——这是这条链路的一个真实边界,CI 传的路径都不含空格才没暴露。

环境装配的最后两行:

spec-runner.js:580-587

const env = {
  ...process.env,
  ELECTRON_SPEC_ELECTRON_PATH: exe,
  ELECTRON_SPEC_WORKER_ARGS: electronArgs.join(' ')
};
let command = process.execPath;
let commandArgs = vitestArgs;
if (process.platform === 'linux') {
  commandArgs = [path.resolve(__dirname, 'dbus_mock.py'), command, ...commandArgs];
  command = 'python3';
}

Linux 上整个 vitest CLI 本身被包在 python3 dbus_mock.py 里,这样 mock D-Bus 的地址通过环境变量被所有 Electron worker 继承(21.14 展开)。也就是说 dbus mock 只启动一次、包住全流程,而不是每个 spec 起一次。

21.2.4 退出码与 pid 的两个细节

asyncSpawn 把子进程 stdout/stderr pipe 到父进程,ELECTRON_TEST_PID_DUMP_PATH 设了就把 child.pid 写进文件(供 CI 在超时时抓进程树)。失败时:

spec-runner.js:627-628

const textStatus = process.platform === 'win32' ? `0x${status.toString(16)}` : status.toString();
console.log(`${fail} Electron tests failed with code ${textStatus}.`);

Windows 的退出码被转成十六进制,因为 Windows 上常见的是 0xC0000005 这类 NTSTATUS,十进制打印出来完全没有可读性。status 为 0 但 signal 非空时改报 kill signal。

还有一处在重跑时才生效的小逻辑:

spec-runner.js:607-612

const launchIndex = electronLaunchCount++;
if (launchIndex > 0) {
  argsToPass = argsToPass.map((arg) =>
    String(arg).startsWith('--log-file=')
      ? String(arg).replace(/(\.[^./\\]+)?$/, (ext) => `.rerun-${launchIndex}${ext}`)
      : arg
  );
}

原因是注释里那句:"Each launch truncates the --log-file it is given"——Chromium 每次启动都会清空指定的日志文件。如果失败重跑沿用同一个路径,第一次失败的日志就被抹掉了,恰恰是最需要保留的那份。所以第二次及以后的启动把 electron_debug.log 改成 electron_debug.rerun-1.log。21.4 里 worker 级还有一次同类改写,但粒度不同。

21.3 main() 的四件前置工作,以及它们为什么必须在 Electron 启动之前

spec-runner.js:92-99 的 main() 里,真正跑测试之前有四步,顺序固定:

const [lastSpecHash, lastSpecInstallHash] = loadLastSpecHash();
const [currentSpecHash, currentSpecInstallHash] = await getSpecHash();
const somethingChanged = currentSpecHash !== lastSpecHash || lastSpecInstallHash !== currentSpecInstallHash;
if (somethingChanged && !args.skipYarnInstall) {
  await installSpecModules(path.resolve(__dirname, '..', 'spec'));
  await getSpecHash().then(saveSpecHash);
} else if (somethingChanged) {
  console.log(`${warn} --skipYarnInstall leaves the native addon fixtures needing Electron's headers unbuilt; their specs will be skipped`);
  process.env.ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECS = '1';
}
if (!fs.existsSync(path.resolve(__dirname, '../electron.d.ts'))) {
  console.log('Generating electron.d.ts as it is missing');
  generateTypeDefinitions();
}
const teardownPrinter = await setupVirtualPrinter();
process.on('exit', teardownPrinter);
await runElectronTests();

21.3.1 两个 hash,两种粒度

getSpecHash() 返回 Promise.all 的两个值:

spec-runner.js:855-862

(async () => {
  const hasher = crypto.createHash('SHA256');
  hasher.update(fs.readFileSync(path.resolve(__dirname, '../yarn.lock')));
  hasher.update(fs.readFileSync(path.resolve(__dirname, '../spec/package.json')));
  hasher.update(fs.readFileSync(path.resolve(__dirname, '../script/spec-runner.js')));
  return hasher.digest('hex');
})(),
(async () => {
  const specNodeModulesPath = path.resolve(__dirname, '../spec/node_modules');
  if (!fs.existsSync(specNodeModulesPath)) return null;
  const { hash } = await hashElement(specNodeModulesPath, { folders: { exclude: ['.bin'] } });
  return hash;
})()

第一个是声明式依赖的指纹:根目录 yarn.lock + spec/package.json + spec-runner.js:137-140 自己。把 runner 脚本本身算进去很不寻常,理由是它包含 installSpecModules 的实现——装依赖的逻辑变了,装出来的东西可能就该变。

第二个是安装结果的指纹:整个 spec/node_modules 目录的 folder-hash,排除 .bin(那里是可执行符号链接,内容不稳定)。两者都写进 spec/.hash,用换行分成两行:

spec-runner.js:137-140

function loadLastSpecHash() {
  return fs.existsSync(specHashPath) ? fs.readFileSync(specHashPath, 'utf8').split('\n') : [null, null];
}
function saveSpecHash([newSpecHash, newSpecInstallHash]) {
  fs.writeFileSync(specHashPath, `${newSpecHash}\n${newSpecInstallHash}`);
}

为什么需要第二个 hash?因为 node_modules 可能被别人手工改过、被上一次中断的 install 留成半成品、或者被 CI 缓存恢复成旧状态。只看声明文件会认为"没变化"然后跳过安装,接着跑出一个找不到模块的失败。--immutable 的 yarn install 通常很快,但对 1003 个文件的仓库来说省掉每次重装仍然值得,于是用两份指纹换这个缓存。

--skipYarnInstall 的分支不安装任何东西,但也不假装一切正常:它设置 ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECS=1,这个环境变量在 spec/node.spec.ts:687 被 ifit(...) 读到,把相关的原生 addon 用例标成 skip。注释点明了使用场景是 CI 的 linux-arm 分片。换句话说,runner 主动告诉测试"有些东西没编译好,你自己跳过",而不是让它在加载时抛 NODE_MODULE_VERSION 不匹配。

21.3.2 installSpecModules():一个项目,两套 Node 头文件

spec-runner.js:657-664

if (args.electronVersion) {
  env.npm_config_target = args.electronVersion;
  env.npm_config_disturl = 'https://electronjs.org/headers';
  env.npm_config_runtime = 'electron';
  env.npm_config_devdir = path.join(os.homedir(), '.electron-gyp');
  env.npm_config_build_from_source = 'true';
  // ... npm run node-gyp-install --ensure
} else {
  env.npm_config_nodedir = path.resolve(BASE, `out/${utils.getOutDir({ shouldLog: true })}/gen/node_headers`);
}

本地构建时,头文件来自当前构建的 out/<outDir>/gen/node_headers;测外部版本时,改为从 electronjs.org/headers 下载对应版本的头文件。这两条路径决定了 spec/fixtures/native-addon/ 编译出来的 .node 能不能被 Electron 加载(21.13 会展开 ABI 问题)。

之后是三步:

spec-runner.js:676-679

if (fs.existsSync(path.resolve(dir, 'node_modules'))) {
  await fs.promises.rm(path.resolve(dir, 'node_modules'), { force: true, recursive: true });
}
const yarnArgs = [YARN_SCRIPT_PATH, 'install', '--immutable'];
// spawnSync(process.execPath, yarnArgs, { env, cwd: dir, stdio: 'inherit' })
if (process.platform === 'linux') {
  // spawnSync('npm', ['rebuild', 'abstract-socket'], ...)
}

先整个删掉 node_modules 再装,而不是增量安装。原因是 yarn workspace 的构建脚本"每个 install state 只跑一次":如果沿用旧的 node_modules,九个工作区里的原生 addon 会保持上次(可能是针对系统 Node)编译的产物。注释写得很清楚:

The native addon fixtures are workspaces, so yarn only runs their build scripts once per install state and keeps whatever the root yarn install built them against (the system Node.js headers in CI). N-API addons are ABI-stable, so that is fine for them, but addons using Node's C++ module API embed NODE_MODULE_VERSION and fail to load in Electron unless they are compiled against the headers configured above.

于是后面还有一轮显式 node-gyp rebuild,只对 package.json:149 里带 "electron:requiresElectronHeaders": true 的 fixture 生效。全仓库只有 object-wrap 一个。

Linux 单独 npm rebuild abstract-socket,是因为它依赖的抽象 Unix socket 是平台相关且必须在目标环境重编。

21.3.3 electron.d.ts 兜底与 pretest

spec-runner.js:111-112

if (!fs.existsSync(path.resolve(__dirname, '../electron.d.ts'))) {
  generateTypeDefinitions();
}
// function generateTypeDefinitions() 里:
//   spawnSync('npm', ['run', 'create-typescript-definitions'], { stdio: 'inherit', shell: true })

package.json:75 里 pretest 已经挂了 npm run create-typescript-definitions,runner 里再兜一次,是为了支持直接 node script/spec-runner.js(绕过 npm 生命周期)的场景。这个 npm script 本身是一条链:

create-typescript-definitions
  = npm run create-api-json
    && electron-typescript-definitions --api=electron-api.json
    && node spec/ts-smoke/runner.js

script/create-api-json.mjs:1 用 @electron/docs-parser 从 docs/api/*.md 解析出 electron-api.json(packageMode: 'single', useReadme: false, moduleVersion: getElectronVersion());再由 electron-typescript-definitions 生成 electron.d.ts;最后 runner.js:7 起 tsc --project ./ts-smoke/tsconfig.json 对 spec/ts-smoke/electron/ 下的类型用例做一次编译检查。

也就是说文档是类型定义的唯一真源,而类型定义又被测试编译一次。这构成一个很特别的回路:改 docs/api/*.md 里的一个签名,electron.d.ts 会变,ts-smoke 会编译失败——测试体系把文档也纳入了可验证范围(21.16 展开)。

21.3.4 虚拟打印机:第 19 章那条 print() 路径的现实前提

setupVirtualPrinter() 是全篇最长的单个辅助函数(约 110 行),注释第一句就点出了时序约束:

Provision a silent virtual printer before launching Electron so the webContents.print() specs can run against a real device. Must happen here (before the test process starts) because macOS validates deviceName against a per-process PrintCore snapshot captured at startup.

这正是第 19 章 19.1 里 OnGetDeviceNameToUse / getPrintersAsync() 那条链路的对偶:PrintCore 在进程启动那一刻拍下设备快照,之后再往系统里加打印机,那个进程也看不见。所以打印机必须在 Electron 进程存在之前挂好。

三个平台三种做法:

平台做法名字
WindowsPowerShell Add-PrinterPort 指向临时 .pdf 文件 + Add-Printer -DriverName 'Microsoft Print To PDF'ElectronTestPDF
Linux / macOS起 ippeveprinter(IPP Everywhere)监听随机空闲端口,再用 lpadmin -p ... -v ipp://localhost:<port>/ipp/print -m everywhere 注册无驱动 CUPS 队列electron-ipp-test
环境已提供直接返回 noop,尊重 ELECTRON_TEST_PRINTER_NAME由 CI 指定

Linux 路径里有几处很讲究:locateBinary() 先 command -v,再逐个查 /usr/sbin、/usr/bin 等;getFreePort() 用 net.createServer().listen(0) 拿端口后立刻关掉;waitForPort() 每 200ms 探测、10 秒超时;ippServer.unref() 是为了不让这个长驻进程吊住 runner 的事件循环(注释原文:"otherwise the process hangs on exit instead of running teardown");teardown 用 process.on('exit', teardownPrinter) 注册,而 'exit' 回调只能是同步的,所以 teardown 里全是 spawnSync / rmSync。

整段是 best-effort:任何一步失败都 return noop,只是不设 ELECTRON_TEST_PRINTER_NAME。对应 spec 自己会检测这个变量并选择跳过。CI 的 Linux 步骤里也有一段同样的 PowerShell/CUPS 预置(作为 builduser 权限的替代路径),注释写着 "the print settings test will self-skip"。于是"没打印机"这个环境差异被表达成 skip,而不是 failure。

这是对"测试应该多严格"这个问题的一个很成熟的态度:能测的必须真测(真的加一台打印机、真的走 webContents.print()),测不了的要显式地、可追踪地不测,绝不留一条悄悄通过的假断言。


21.4 electronPool:把 vitest 的 worker 换成 Electron 浏览器进程

electron-pool.ts:53-59(261 行)实现了 vitest 的 PoolRunnerInitializer 接口。它的定位写在文件头两行:

A vitest pool whose workers are Electron browser processes instead of Node child processes, so that specs run in the Electron main process exactly as they did under the mocha runner. Each worker is electron spec/ --vitest-worker.

"exactly as they did under the mocha runner" 是理解整份代码的钥匙:这不是新设计,是把 old runner 的语义逐条搬到新框架上。文件里每一处不寻常的写法,后面都跟着一句"mocha 当年就是这么做的"。

21.4.1 PoolWorker 的六个接口点

electron-pool.ts:53-59

export function electronPool(poolOptions: ElectronPoolOptions): PoolRunnerInitializer {
  return {
    name: 'electron',
    createPoolWorker: (options) => new ElectronPoolWorker(options, poolOptions)
  };
}
class ElectronPoolWorker implements PoolWorker {
  name = 'electron';
  cacheFs = true;   // Same as the forks pool: the worker reads specs from disk itself
  ...
}

cacheFs = true 允许 vitest 主进程向 worker 提供缓存过的 fs 结果——因为 worker 自己从磁盘读 spec 文件,而不是由主进程把源码字符串发过去。这一点和 21.2 里 viteModuleRunner: false 是同一个决定:不做模块转换,直接让 Electron 的 Node 去加载文件。

ElectronPoolOptions 五个字段把"怎么起进程"全部外置给了 vitest.config.ts:

字段含义谁提供
electronPath要测的 Electron 可执行文件ELECTRON_SPEC_ELECTRON_PATH,否则 utils.getAbsoluteElectronExec()
specDir传给 Electron 的 app 目录(spec/)vitest.config.ts:14 的 import.meta.dirname
electronArgs每个 worker 的额外命令行开关ELECTRON_SPEC_WORKER_ARGS(CI 的 --no-sandbox、--enable-logging 等)
launcher包一层启动器Linux 上的 ['python3', 'dbus_mock.py']
exclusive等所有历史 worker 退出后才启动只有 serial project 传 true

on() / off() 有一个细节:error 事件走一个独立的 EventEmitter(this.errors),其他事件转发给子进程。原因是 proc getter 在 worker 被拆掉后会抛错,而错误回调在拆除过程中仍可能触发。

21.4.2 start():九个动作,每一个都对应一个历史事故

electron-pool.ts:102-109

async start(): Promise<void> {
  if (this.child) return;
  if (this.electron.exclusive) {
    await Promise.all(liveWorkers);
    if (this.stopped) throw new Error('The Electron spec worker was stopped before it started.');
  }
  const env: NodeJS.ProcessEnv = { ...this.env, ELECTRON_SPEC_WORKER_ID: String(this.id) };
  delete env.ELECTRON_RUN_AS_NODE;
  const electronArgs = (this.electron.electronArgs ?? []).map((arg) =>
    arg.startsWith('--log-file=') ? arg.replace(/(\.[^./\\]+)?$/, (ext) => `.worker-${this.id}${ext}`) : arg
  );
  const [command, ...prefix] = [
    ...(this.electron.launcher ?? []), this.electron.electronPath,
    this.electron.specDir, '--vitest-worker', ...electronArgs
  ];
  const child = childProcess.spawn(command, prefix, {
    cwd: path.dirname(this.electron.specDir), env,
    stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
    serialization: 'json',
    detached: process.platform !== 'win32'
  });
  ...
}

逐条拆:

  1. delete env.ELECTRON_RUN_AS_NODE。注释是 "Whatever the CLI's environment says, the workers must be real browser processes." 第 20 章讲过 ELECTRON_RUN_AS_NODE 会让同一个可执行文件退化成纯 Node。测试环境里这个变量很可能被外部设置过(CI、开发机、node-spec-runner 的残留),如果不删,起来的就是个没有 BrowserWindow 的 Node 进程,第一个 spec 就崩。
  2. --log-file 的 worker 级改写。21.2 里 runner 已经做过一次 .rerun-N,这里再做一次 .worker-N。两级后缀对应两级复用:重跑会复用不同进程,同一个 run 内多个 worker 又共享同一份参数。Chromium 每次启动清空日志,所以每个 worker 必须有独立文件,否则先启动的那个刚写就被后启动的清掉。
  3. stdio: ['ignore', 'pipe', 'pipe', 'ipc'] —— 第四个 fd 是 Node 的 IPC 通道,是 21.5 那条协议的全部物理载体。stdin 被关掉,避免 spec 里误读。
  4. serialization: 'json' —— 不是 vitest forks pool 默认的 'advanced',原因见 21.5。
  5. detached: process.platform !== 'win32' —— 让 worker 成为新进程组的组长,这样 stop() 能用负 pid 把 spec 泄漏的孙子进程一起收走。Windows 没有进程组语义,退化为单进程 kill。
  6. liveWorkers 是模块级 Set<Promise<void>>,跨越两个 vitest project 实例。注释直接引用了 vitest 的行为:"Runner terminations are started but not awaited until the end of full run"。意思是 vitest 结束一个文件时发起 worker 停止但不等它真的退出,就把下一个文件交给新 worker;所以哪怕 maxWorkers: 1,上一个 Electron 进程仍在退出中,下一个已经起来了。parallel 阶段末尾与 serial 阶段开头的重叠正是这么来的。exclusive 靠 await Promise.all(liveWorkers) 把这条缝堵死。
  7. 共享日志流的 setMaxListeners。所有 worker 的 stdout/stderr 都 pipe 到同一个 vitest logger 流,且 end: false(一个 worker 结束不能把流给别人关掉)。每起一个 worker 就把流的 maxListeners 加 1,stop() 里再减回去,否则十几个 worker 后 Node 会打 MaxListenersExceededWarning。
  8. WORKER_READY_MESSAGE 握手。注释解释了为什么不能依赖 IPC 缓冲:"vitest posts its 'start' request as soon as start() resolves. Electron only attaches the worker runtime once the app is ready, so wait for it to say so rather than relying on the IPC channel buffering the request." 如果不等,vitest 的 start 消息会在 process.on('message') 挂上之前到达并被丢弃,worker 永远不跑。
  9. START_TIMEOUT = 3 * 60_000。三分钟,注释说 "sanitizer builds are slow"。超时后 killGroup() 并 reject。握手同时监听 'message'、'exit'、'error',任一路径都走同一个 cleanup() 解除全部监听器。

还有一条容易被跳过:child.once('error', () => child.pid === undefined && resolve()) —— spawn 失败的子进程不会 emit 'exit',如果不给这条兜底,liveWorkers 里会永远留一个未决的 Promise,之后所有 exclusive worker 都会卡死在 await Promise.all(liveWorkers)。

21.4.3 stop() 的五段式收尾

electron-pool.ts:36-43

const SIGKILL_TIMEOUT = 5_000;
const FLUSH_TIMEOUT = 5_000;
async stop(): Promise<void> {
  this.stopped = true;
  const child = this.child;
  if (!child) return;
  this.child = undefined;
  const exited = new Promise<void>((resolve) => {
    if (child.exitCode !== null || child.signalCode !== null) resolve();
    else child.once('exit', () => resolve());
  });
  const sigterm = setTimeout(() => child.kill(), SIGKILL_TIMEOUT / 2);
  const sigkill = setTimeout(() => child.kill('SIGKILL'), SIGKILL_TIMEOUT);
  await exited;
  clearTimeout(sigterm); clearTimeout(sigkill);
  this.killGroup(child);
  let flushTimer: NodeJS.Timeout | undefined;
  await Promise.race([
    Promise.all([streamFlushed(child.stdout!), streamFlushed(child.stderr!)]),
    new Promise((resolve) => { flushTimer = setTimeout(resolve, FLUSH_TIMEOUT); })
  ]);
  clearTimeout(flushTimer);
  child.stdout!.destroy(); child.stderr!.destroy();
  child.stdout!.unpipe(this.stdout); child.stderr!.unpipe(this.stderr);
  this.stdout.setMaxListeners(this.stdout.getMaxListeners() - 1);
  this.stderr.setMaxListeners(this.stderr.getMaxListeners() - 1);
}

顺序是:先温柔等 → 2.5 秒 SIGTERM → 5 秒 SIGKILL → 等 'exit' → 杀整个进程组 → 最多 5 秒等管道排空 → 强制销毁并 unpipe。

"温柔等"指 worker 自己的 teardown 会 app.quit()(21.5 末尾),这是正常路径。SIGTERM 与 SIGKILL 是兜底。killGroup 之所以放在 await exited 之后而不是之前,是因为进程退出后它派生的 fixture app 可能还活着;负 pid 的 process.kill(-child.pid, 'SIGKILL') 正是为这个准备的。

FLUSH_TIMEOUT 的注释点出另一种泄漏:"a process the worker leaked can hold them open indefinitely"。第 19、20 章里那些 spawn 出来的 fixture app(Update.exe、ShipIt、remote-control)都可能继承 stdout/stderr。如果无限等 'end',整个测试 run 就挂在这里。所以这里是 Promise.race,超时后直接 destroy()。

stopped 标志还服务 21.4.2 的 exclusive 分支:一次被取消的 run 里,worker 可能正在 await Promise.all(liveWorkers),此时如果 stop() 被调用,醒来后不能再启动新 Electron——否则会留一个没人管的进程。

21.4.4 三个常量对应的三类故障

常量值防的是
START_TIMEOUT180 sASan/sanitizer 构建下 Electron 到 ready 极慢,握手不能按普通构建的秒级估
SIGKILL_TIMEOUT5 sworker 的 app.quit() 没走完(窗口卡住、before-quit 里有人 preventDefault())
FLUSH_TIMEOUT5 s逃逸出进程组的后代进程吊住 stdout/stderr

这三个数不是随手写的容忍度,而是把"测试框架假设子进程会干净退出"这个假设逐条替换成"有界等待 + 强制收尾"。配合 spec/CLAUDE.md:17 里"每个 fork 出来的子进程都要注册 defer",构成两层保险:spec 层主动清理,pool 层兜底杀组。

21.5 ipc-serialization.ts:两个不同版本的 V8 之间怎么传对象

这是全章最"底层"的一节,也是最能说明"为什么不能直接用现成框架"的一节。文件头 11 行把约束写得极完整:

serialization: 'advanced'(what vitest's own forks pool uses)is not an option: it is V8's wire format, and Electron's V8 is newer than the host Node's, so the host cannot read what the worker writes. JSON is version independent, but vitest's task trees are cyclic (test -> suite -> file -> tasks) and carry a few non-JSON values, so both ends run messages through this encoder first.

拆成三条硬约束:

  1. 不能用 V8 structured clone 的 wire format:宿主 CLI 跑在系统 Node 上,worker 跑在 Electron 内嵌的 Node 上,两者的 V8 版本不同。advanced 序列化出来的字节流没有跨版本兼容保证,宿主可能直接读不出来。
  2. 不能直接用 JSON:vitest 传给 worker 的任务树里有环——test.suite 指回 suite,suite.file 指回 file,file.tasks 又列着 test。JSON.stringify 会立刻抛 Converting circular structure to JSON。
  3. 不能丢类型:BigInt、NaN、±Infinity、undefined、Map / Set / RegExp / Date / Error / TypedArray / ArrayBuffer,JSON 要么抛错、要么变成 null / 0 / {}。测试结果里这些值都会出现(expect(BigInt) 的失败、超时里的 Infinity、错误对象上的自定义字段)。

于是方案是:先把任意值编码成一个 JSON 安全的「根 + 索引表」结构,再 JSON.stringify。

21.5.1 两个特殊键和索引表

ipc-serialization.ts:12-19

export const WORKER_READY_MESSAGE = 'electron-vitest-worker-ready';
const TYPE = '\u0000t';
const REF = '\u0000r';
type Encoded = { [TYPE]: string; v?: unknown } | { [REF]: number } | unknown;

export function serialize(value: unknown): string {
  const table: unknown[] = [];
  const seen = new Map<object, number>();
  const encode = (v: unknown): Encoded => { ... };
  const root = encode(value);
  return JSON.stringify([root, table]);
}

用 \u0000t / \u0000r 作键名,是因为 JS 对象的普通属性名几乎不可能以 NUL 开头——不可能和用户数据里的键撞车。这是很 economical 的命名空间手法。

循环引用的破法是"先登记索引、后填内容":

ipc-serialization.ts:39-46

case 'object': {
  if (v === null) return null;
  const existing = seen.get(v);
  if (existing !== undefined) return { [REF]: existing };
  const id = table.length;
  seen.set(v, id);
  table.push(null);          // 先占一个坑
  let out: unknown;
  // ... 按类型编码成 out ...
  table[id] = out;           // 再回填
  return { [REF]: id };
}

seen.set 发生在递归编码子属性之前,所以编码到 test.suite.file.tasks[0] 时会命中 seen,返回一个 {[REF]: 0},递归到此为止。共享引用也被一并压平:同一个对象出现两次,第二次就是同一个 REF,解码后还是同一个对象(不只是值相等)。

21.5.2 逐类型的标签表

输入标签 / 输出备注
undefined{t:'u'}JSON 里数组元素 undefined 会变 null,必须显式标
bigint{t:'b', v: v.toString()}解码 BigInt(p)
NaN{t:'n', v:'NaN'}数字本身直接透传(return v)
+Infinity / -Infinity{t:'n', v:'+' / '-'}同上
function / symbol{t:'u'}丢弃,理由见下
Arrayv.map(encode)数组本身也进 table
RegExp{t:'R', v:[source, flags]}
Date{t:'D', v:getTime()}
Map / Set{t:'M' / 'S', v: entries / values}键值都递归 encode
ArrayBuffer.isView{t:'T', v:[constructor.name, base64]}用 new Uint8Array(v.buffer, v.byteOffset, v.byteLength) 精确取字节,尊重视图偏移
ArrayBuffer{t:'A', v: base64}
Error{t:'E', v: {...}}见下
普通对象逐 Object.keys encodeObject.keys 只取可枚举自有属性

function / symbol 的处理有一句非常值得记的注释:

Structured clone would throw here; JSON drops them. Dropping is the more forgiving choice for stray values hanging off task objects.

也就是说这里的策略是宁可少传一个无关字段,也不要让一条测试结果把整个 IPC 通道打断。任务树上偶尔会挂一些函数(比如回调引用),它们对宿主 CLI 汇报结果毫无用处,降级成 undefined 比抛异常合理。

Error 的编码用的是 Object.getOwnPropertyNames(v) 而不是 Object.keys:

ipc-serialization.ts:39-45

case 'object': {
  ...
  } else if (v instanceof Error) {
    const o: Record<string, Encoded> = {
      name: encode(v.name), message: encode(v.message), stack: encode(v.stack)
    };
    for (const key of Object.getOwnPropertyNames(v)) {
      if (!(key in o)) o[key] = encode((v as any)[key]);
    }
    out = { [TYPE]: 'E', v: o };
  }

name / message / stack 在原生 Error 上是不可枚举的,Object.keys(new Error('x')) 返回空数组;而 chai / vitest 会往 Error 上挂 actual、expected、showDiff、operator 等断言元数据,这些才是失败报告里最有用的部分。所以既要手写那三个,又要遍历 getOwnPropertyNames 把自定义字段捞出来。

解码侧对应地用了 Object.defineProperty:

ipc-serialization.ts:163-167

Object.defineProperty(err, key, {
  value: decode(p[key]),
  enumerable: key !== 'stack' && key !== 'message',
  configurable: true,
  writable: true
});

让 stack / message 恢复成不可枚举,跟原生 Error 的属性描述符保持一致;name 则可枚举(编码时走的是普通对象路径,不过这个细节在报告里不重要)。

21.5.3 deserialize 的两个数组,以及"先挂壳再填肉"

ipc-serialization.ts:91-98

export function deserialize(text: unknown): unknown {
  if (typeof text !== 'string') return text;
  const [root, table] = JSON.parse(text) as [Encoded, Encoded[]];
  const revived: unknown[] = new Array(table.length);
  const done: boolean[] = new Array(table.length).fill(false);
  const revive = (id: number): unknown => {
    if (done[id]) return revived[id];
    done[id] = true;
    const raw = table[id] as any;
    if (Array.isArray(raw)) {
      const arr: unknown[] = [];
      revived[id] = arr;                 // 先把空数组挂上
      for (const item of raw) arr.push(decode(item));
      return arr;
    }
    ...
  };
  return decode(root);
}

done[id] = true 写在解码内容之前,revived[id] = arr 也写在填充之前。这是破环的镜像操作:如果等填完再注册,一个自引用对象会让 revive 无限递归。Map、Set、Error 三个分支也都用 revived[id] = m / s / err 先挂壳。

TypedArray 的还原有个巧思:

ipc-serialization.ts:147-151

case 'T': {
  const buf = Buffer.from(p[1], 'base64');
  const Ctor = (globalThis as any)[p[0]] ?? Uint8Array;
  return (revived[id] =
    Ctor === Buffer ? buf : new Ctor(buf.buffer, buf.byteOffset, buf.byteLength / (Ctor.BYTES_PER_ELEMENT || 1)));
}

编码时存的是 v.constructor.name(如 Uint16Array),解码时按名字从 globalThis 取构造器;找不到就退回 Uint8Array。Buffer 是 Uint8Array 的子类,但构造语义不同,所以单独处理。byteLength / BYTES_PER_ELEMENT 把字节数换算成元素个数。

还有一处"靠不变式而非完备性"的设计值得指出:decode() 里 TYPE 分支只处理 'u' / 'b' / 'n',遇到 'R' / 'D' / 'M' 等其他标签会穿透到下面当作普通对象解。而 revive() 里才有完整的标签分支。这能成立,是因为 serialize 保证所有带标签的对象值都走 REF 路径——{t:'R', ...} 永远只出现在 table 里,不会作为 decode 的直接输入。换句话说,解码器的正确性依赖编码器的输出形状,两端是同一个文件里的配对实现,不能单独替换其中一半。

21.5.4 worker.ts:13-18:把 Electron 主进程"交出去"

worker.ts:13-18 只有 52 行,是 Electron 侧的协议端点:

if (!process.send) {
  throw new Error('spec/vitest/worker.ts expects to be launched by the vitest Electron pool (no IPC channel)');
}
const processSend = process.send.bind(process);
const processOn = process.on.bind(process);
const processOff = process.off.bind(process);
const processExit = process.exit.bind(process);

开头先把四个 process 方法绑成局部常量,注释是 "Keep references in case a spec replaces them." 这很实际:有些 spec 就是测 process 对象的行为,会 monkey-patch process.exit / process.on;worker runtime 如果之后用被改过的版本,整个通道就断了。

三条进程级处理:

worker.ts:23-27

processOn('error', (error: NodeJS.ErrnoException) => {
  if (error?.code === 'ERR_IPC_CHANNEL_CLOSED' || error?.code === 'EPIPE') processExit(1);
});
processOn('disconnect', () => processExit(1));
processOn('unhandledRejection', (reason) => {
  console.warn('UnhandledPromiseRejectionWarning:', reason);
});

前两条是"CLI 没了就别活着":父进程消失后继续跑测试没有意义,还会留下占用端口和单实例锁的孤儿进程(21.8 的 global-setup.js 就是来清这种孤儿的)。

第三条最耐人寻味,注释写:

The main process runs with unhandled rejections in 'warn' mode and the mocha runner left them as warnings, so several specs fire and forget promises that reject once their window is gone. vitest would report every one of them as an error (it only does so when nobody else listens), so keep warning.

也就是为了兼容一批历史遗留的"窗口销毁后 promise 自然 reject"的 spec,主动注册一个 unhandledRejection 监听器把 vitest 的错误上报屏蔽掉。vitest 只在"没有别的监听器"时才把这些当测试失败,加一个监听器就退回 warn 模式。这是把 mocha 时代的语义手工搬过来的典型例子——不是修 spec,是改运行时行为。

最后:

worker.ts:37-44

init({
  post: (message) => processSend(message),
  on: (callback) => processOn('message', callback),
  off: (callback) => processOff('message', callback),
  serialize, deserialize,
  teardown: () => {
    process.removeAllListeners('message');
    setImmediate(() => app.quit());
  },
  runTests: (state, traces) => runBaseTests('run', state, traces),
  collectTests: (state, traces) => runBaseTests('collect', state, traces),
  setup: setupEnvironment
});
processSend(WORKER_READY_MESSAGE);

teardown 用 app.quit() 而不是 process.exit(),让 Electron 走正常的窗口关闭 / before-quit 流程(这也是 21.4 的 stop() 需要 5 秒兜底的原因:有 spec 可能在 before-quit 里拖着)。setImmediate 是为了让 init() 先返回、把 teardown 的完成消息发回 CLI,再退出进程。最后一行发 WORKER_READY_MESSAGE,与 pool 里那个 3 分钟超时的握手对上。


21.6 TestRunner 子类:四个语义补丁与 defer() 的契约

runner.ts(108 行)不是"配置",是改写了测试框架的执行语义。文件头把要补的四条列得很清楚,每一条后面都能找到 mocha 时代的对应行为:

 - Runnables start from a fresh macrotask.
 - `defer()`-ed cleanup runs straight after each test, before the enclosing
   suites' own afterEach hooks.
 - A failing afterEach hook or defer()-ed cleanup does not stop the rest.
 - spec/disabled-tests.json switches a test off by its full title.

21.6.1 补丁一:每个 runnable 都从新的宏任务开始

runner.ts:47-54

const fromFreshMacrotask = <T extends (...args: any[]) => unknown>(fn: T) =>
  async function (this: unknown, ...args: Parameters<T>) {
    await setImmediate();
    return fn.apply(this, args);
  } as T;

async onBeforeRunSuite(suite: RunnerTestSuite) {
  if (!prepared.has(suite)) {
    prepared.add(suite);
    const hooks = TestRunner.getSuiteHooks(suite);
    for (const list of [hooks.beforeAll, hooks.beforeEach, hooks.afterEach, hooks.afterAll]) {
      list.splice(0, list.length, ...list.map(fromFreshMacrotask));
    }
    ...
  }
  return super.onBeforeRunSuite(suite);
}

注释解释了为什么这是必需的:

vitest chains a file's hooks and tests as promise continuations, so without this nothing else on the main process event loop (Chromium tasks, IPC, window teardown) runs between one test's end and the next one's start, and a spec that destroys a window in afterEach and creates one in the next beforeEach trips over the half torn down one. mocha did the same (Runner.immediately).

这是 Electron 测试与普通 Node 测试最本质的差异:测试代码与 Chromium 的消息泵共享同一个线程。如果 hook 之间只用 Promise 微任务串联,事件循环根本没机会转一圈,窗口销毁的 IPC 回包、renderer 的退出通知、app 的事件都还排在队列里。下一个测试开新窗口时,上一个窗口还处在半死状态。await setImmediate() 强制让出一次宏任务,把 Chromium 的任务跑完。

prepared 是 WeakSet,保证一个 suite 的 hook 列表只被包装一次;onBeforeTryTask 里对每个 test 也有一次 await setImmediate()。

21.6.2 补丁二:defer() 排在 suite 的 afterEach 之前

hooks.afterEach.unshift(() => runCleanupFunctions(this.config.hookTimeout));

unshift 把它插到最前。配合 vitest.config.ts:122 里的 sequence: { hooks: 'list' }:vitest 默认是 'stack',after* hook 按声明的逆序执行;改成 'list' 才按声明顺序。注释点明原因——默认的逆序会"先关掉窗口,再跑那个还需要窗口的 cleanup"。

spec-helpers.ts:30-37 里的 defer() 与 runCleanupFunctions() 是这个契约的另一半:

const cleanupFunctions: { cleanup: CleanupFunction; timeoutError: Error }[] = [];
export function defer(f: CleanupFunction) {
  const timeoutError = new Error('defer()-ed cleanup timed out');
  Error.captureStackTrace(timeoutError, defer);
  cleanupFunctions.unshift({ cleanup: f, timeoutError });
}
export async function runCleanupFunctions(timeout: number) {
  const pending = cleanupFunctions.splice(0, cleanupFunctions.length);
  const errors: unknown[] = [];
  for (const { cleanup, timeoutError } of pending) {
    let timer: NodeJS.Timeout | undefined;
    const timedOut = new Promise<never>((_resolve, reject) => {
      if (timeout <= 0 || timeout === Infinity) return;
      timer = globalThis.setTimeout(() => {
        timeoutError.message = `defer()-ed cleanup timed out in ${timeout}ms`;
        reject(timeoutError);
      }, timeout);
    });
    try { await Promise.race([cleanup(), timedOut]); }
    catch (error) { errors.push(error); }
    finally { globalThis.clearTimeout(timer); }
  }
  if (errors.length === 1) throw errors[0];
  if (errors.length > 1) throw new AggregateError(errors, 'Several defer()-ed cleanup functions failed');
}

四个设计点:

  • unshift 注册、splice 全量取走 → 后进先出,符合"先关最后开的资源"。注释解释了为什么必须先 splice:一个 cleanup 抛错后,剩下的不能留在全局数组里,否则会被之后每一个测试重复执行并反复抛错。
  • 每个 cleanup 单独 Promise.race 一个超时 Promise,超时时间取 config.hookTimeout(this.config.hookTimeout 是运行时读,所以 vi.setConfig() 能改它),注释说 "so a cleanup that never settles fails the test instead of hanging the run"。
  • timeoutError 在 defer() 调用时用 Error.captureStackTrace(..., defer) 创建,堆栈指向注册 cleanup 的那行,而不是超时定时器触发的那行。排查泄漏时这是唯一有用的信息。
  • 所有 cleanup 都会跑完,错误最后聚合成一个 AggregateError。哪怕第一个抛了,后面的窗口、协议 handler、子进程照样被清理。

spec/CLAUDE.md:17 第四条要求的 deferKillUtilityProcess() 就是这个机制的具体用法:

spec-helpers.ts:421-426

export function deferKillUtilityProcess(utilityProcess: Electron.UtilityProcess) {
  defer(async () => {
    if (utilityProcess.pid) {
      const exit = once(utilityProcess, 'exit');
      utilityProcess.kill();
      await exit;
    }
  });
}

if (utilityProcess.pid) 正是第五条"只 kill 还活着的进程";once 先注册再 kill,避免事件抢跑。

21.6.3 补丁三:一个 hook 失败不能挡住后面的清理

runner.ts:55-62

const cleanupErrors = new WeakMap<object, unknown[]>();
function collectingErrors(hook) {
  return async function (this: unknown, context: TestContext, suite: Readonly<RunnerTestSuite>) {
    try { await hook.call(this, context, suite); }
    catch (error) {
      const errors = cleanupErrors.get(context.task);
      if (!errors) throw error;   // 没有收集者就让 vitest 立刻报
      errors.push(error);
    }
  };
}

注释把 vitest 的行为说死了:"Once one throws, vitest skips the test's remaining afterEach hooks, the enclosing suites' included, so one failed cleanup would leave a protocol handler or a window behind and break the tests after it."

所以策略是把所有 afterEach 包一层、把错误攒起来,等全部跑完再统一抛:

runner.ts:90-97

async onBeforeTryTask(test: RunnerTestCase, options: TestTryOptions) {
  await setImmediate();
  const errors: unknown[] = [];
  cleanupErrors.set(test, errors);
  test.context.onTestFinished(() => {
    cleanupErrors.delete(test);
    if (errors.length === 1) throw errors[0];
    if (errors.length > 1) {
      const all = errors.flatMap((error) => (error instanceof AggregateError ? error.errors : [error]));
      throw new AggregateError(all, 'Several afterEach hooks or defer()-ed cleanup functions failed');
    }
  });
  return super.onBeforeTryTask(test, options);
}

onTestFinished 的选择有讲究:注释说 vitest 在所有 afterEach 之后执行这些回调,且按 newest-first,所以在 onBeforeTryTask 里最早注册的那个反而最后跑——正好能收齐。如果测试自己又注册了 onTestFinished,它后注册、先执行,不影响汇总。

flatMap 展平一层 AggregateError,是因为 runCleanupFunctions 自己已经抛过一个 AggregateError;注释写明 "vitest reports each error in an AggregateError, but only one level deep",两层嵌套会让后面的错误在报告里消失。

21.6.4 补丁四:disabled-tests.json 按全标题关测试

runner.ts:34-41

const disabledTests = new Set<string>(
  JSON.parse(fs.readFileSync(path.join(import.meta.dirname, '..', 'disabled-tests.json'), 'utf8'))
);
function fullTitle(task: RunnerTask): string {
  const parts: string[] = [];
  // The outermost suite is the file itself, whose name is its path.
  for (let t: RunnerTask | undefined = task; t && !('filepath' in t); t = t.suite) parts.unshift(t.name);
  return parts.join(' ');
}
async onBeforeRunTask(test: RunnerTestCase) {
  if (disabledTests.has(fullTitle(test))) test.mode = 'skip';
  return super.onBeforeRunTask(test);
}

fullTitle 从 test 沿 suite 往上走,遇到带 filepath 的对象(即文件级 suite)就停,把中间的名字用空格拼起来。spec/disabled-tests.json:2-9 里是这种形式:

[
  "// NOTE: this file is used to disable tests in our test suite by their full title.",
  "process module main process process.takeHeapSnapshot() returns true on success",
  "session module ses.cookies should set cookie for standard scheme",
  "webFrameMain module WebFrame.visibilityState should match window state",
  "reporting api sends a report for a deprecation",
  "chromium features SpeechSynthesis should emit lifecycle events",
  "BrowserWindow module draggable regions should allow the window to be dragged when enabled",
  "BrowserWindow module draggable regions should allow the window to be dragged when no WCO and --webkit-app-region: drag enabled"
]

七条真实条目加一条注释字符串。注释本意是给人看的,但因为 JSON 里没有注释语法,它被当成数组第一个元素——Set 里多一个永远不会命中的字符串,无害。文件头 runner 的注释点明用途:"used to unblock a roll while a fix is pending",即为 Chromium roll 临时放行,不用改 spec 源码。

注意这是按标题字符串匹配,不是按文件或行号。改了 describe/it 的措辞,这条禁用就静默失效,测试会重新跑起来。这是这类机制的固有代价。

21.6.5 vitest.config.ts 里其余每一项的理由

配置值为什么
experimental.viteModuleRunner / nodeLoaderfalse / falsespec 由 Electron 自己的 Node 以原生 ESM + 类型擦除加载,不走 Vite 转换,与真实 app 一致
root / dirspecDir文件过滤器按相对 spec/ 的路径匹配
isolatetrue每个 spec 文件一个全新的 Electron 进程(注释 "A fresh Electron process per spec file")
globalsfalse必须显式 import { it, expect } from 'vitest'
chaiConfig.truncateThreshold0显示完整对象 diff(注释引 chaijs/chai#469),否则大对象断言失败只看到截断片段
testTimeout / hookTimeoutELECTRON_SPEC_TIMEOUT 或 30 ssanitizer 构建下 CI 设 180000
sequence.hooks'list'21.6.2 的顺序契约
teardownTimeout30 s"Electron takes a moment to quit; a slow worker stop is not a failure"
retryisCI ? 3 : 0框架层重试;21.11 还有 runner 层的 --enableRerun=3,是两套独立的重试
allowOnly!isCI本地允许 it.only,CI 里直接不允许(防止一个 .only 让整批测试只跑一条)
passWithNoTeststrue有些文件在别的平台上顶层 if 直接 return,一条测试都不注册;不算失败。文件级"没匹配到"由 21.2 的 missing 检查兜住
includeTaskLocationtrue报告里带位置,配合 JUnit 的 file 属性
reportersdefault + 可选 github-actions / junit / SpecTimingsReporter见下

github-actions reporter 只在 GITHUB_ACTIONS === 'true' 时加,因为 vitest 只在没有配置任何 reporter 时才自动加它;一旦显式配了 default,就必须手动补回来。还传了 onWritePath 把路径转成相对仓库根——注释说 CI 把 Electron checkout 在 src/electron,不是 GITHUB_WORKSPACE,不转换的话 PR 上的注解链接全是错的。

SpecTimingsReporter 的条件是 isCI && !process.argv.some((arg) => /^(-t|--testNamePattern)/.test(arg)):过滤运行(重跑、单测)不写时间,避免用一份不完整的数据覆盖全量 run 的耗时表。

21.7 spec/index.js:9-11:在 app.whenReady() 之前把世界摆好

spec/ 自己是个 Electron app,index.js:9-11 是它的 main。所有配置都必须在 ready 之前完成——第 17 章讲 registerSchemesAsPrivileged 时说过,自定义 scheme 一旦错过这个窗口就再也注册不上。这份文件把测试需要的"世界状态"一次性装好:

21.7.1 进程身份与目录隔离

spec/index.js:9-11

const isVitestWorker = process.argv.includes('--vitest-worker');
if (isVitestWorker) {
  app.setPath('userData', `${app.getPath('userData')}-worker-${process.env.ELECTRON_SPEC_WORKER_ID || process.pid}`);
}

多个 worker 并发跑(21.8),如果共用默认 userData,会去抢同一份 cookie / localStorage / cache 的 SQLite 文件。所以每个 worker 加一个后缀,且保留原路径里的 app 名(注释 "Keep the app name in the path, some specs check for it")。这正是 spec/CLAUDE.md:37-38 最后那条"不要假设默认路径"的来源。

let workerStarted = false;
process.on('uncaughtException', (err) => {
  if (workerStarted) return;
  console.error('Unhandled exception in the spec worker:', err);
  process.exit(1);
});

双阶段:worker runtime 起来之前,未捕获异常是致命的,直接 exit(1)(否则 Electron 会弹错误对话框,CI 挂死);起来之后直接 return——由 vitest 的监听器接管,把异常归因到当前测试并阻止对话框。

21.7.2 六组命令行开关

spec/index.js:27-32

process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = 'true';
if (process.env.ELECTRON_TEST_DISABLE_HARDWARE_ACCELERATION) app.disableHardwareAcceleration();
v8.setFlagsFromString('--expose_gc');
app.commandLine.appendSwitch('js-flags', '--expose_gc');
app.on('window-all-closed', () => null);
app.commandLine.appendSwitch('use-fake-device-for-media-stream');
  • --expose_gc 写两遍:v8.setFlagsFromString 作用于当前主进程的 isolate,appendSwitch('js-flags', ...) 作用于renderer / 子进程的 isolate。测试里有大量 global.gc() 驱动的堆快照与内存断言(api-process.spec.ts、chromium.spec.ts),两边都得开。
  • window-all-closed 被一个空函数吃掉:默认行为是最后一个窗口关闭就 app.quit(),而测试一个文件里会反复开关窗口。若不禁掉,第一个测试结束进程就没了。
  • use-fake-device-for-media-stream 用假摄像头 / 麦克风,让 getUserMedia 相关测试不依赖硬件。
  • ELECTRON_TEST_DISABLE_HARDWARE_ACCELERATION 是 Linux 某些机器显卡驱动有问题时的逃生开关;呼应第 19 章 OSR 在 --disable-gpu 时换整条后端的行为。

21.7.3 host-resolver-rules 六条,每条都在消掉一种外部依赖

app.commandLine.appendSwitch('host-resolver-rules', [
  'MAP localhost2 127.0.0.1',
  'MAP ipv4.localhost2 10.0.0.1',
  'MAP ipv6.localhost2 [::1]',
  'MAP notfound.localhost2 ^NOTFOUND',
  'MAP notfound.localhost ^NOTFOUND',
  'MAP redirector.gvt1.com ^NOTFOUND'
].join(', '));
  • 前三条给测试提供确定的 IPv4 / 指定 IPv4 / IPv6 回环地址,不用真去配 DNS。localhost2 不是保留域名,正是为了不被 Chromium / 代理的特殊规则影响。
  • 第四条 ^NOTFOUND 让 Chromium 直接返回 ERR_NAME_NOT_RESOLVED,不发 DNS 查询。第五条同时配 notfound.localhost:注释解释了两者的差别——代理默认绕过 *.localhost 但不绕过 localhost2,所以 .localhost 那条的结果不依赖网络里的 DNS 服务器或代理配置。
  • 第六条最有意思:注释说 "Every session downloads the default hunspell dictionary from redirector.gvt1.com when none is cached, and each spec worker starts with a fresh userData, so block it. spellchecker.spec.ts:81 serves its dictionaries from a local server."

因为 21.7.1 给每个 worker 分了独立 userData,拼写检查字典永远没缓存;不拦的话每起一个 worker 就触发一次外网下载,CI 里既慢又不稳。于是直接把它解析成 NOTFOUND,需要字典的 spec 自己起本地 HTTP 服务。这是"目录隔离"引发连锁问题、再用"DNS 隔离"补回来的完整闭环。

21.7.4 enable-features 两项与 14 个特权 scheme

app.commandLine.appendSwitch('enable-features', [
  'DocumentPolicyIncludeJSCallStacksInCrashReports',   // spec/api-web-frame-main.spec.ts
  'UnrestrictSpellingAndGrammarForTesting'             // spec/spellchecker.spec.ts
].join(','));

两个 feature 都注明了消费它们的 spec 文件。第二项允许无用户手势就触发拼写/语法检查。

接着是第 17 章 17.5 那套 registerSchemesAsPrivileged 的测试专用清单,共 14 个 scheme:

schemeprivileges用途
app(global.standardScheme)standard, secure, stream: false标准安全源,但明确关掉 stream
zoom(global.zoomScheme)standard, secure缩放相关用例
sw(global.serviceWorkerScheme)allowServiceWorkers, standard, secureService Worker(第 16 章)
http-likestandard, secure, corsEnabled, supportFetchAPI类 http 的完整能力
cors-blob / cors / no-fetch / no-cors / no-cors-file / no-cors-http / no-cors-standardcorsEnabled 与 supportFetchAPI 的不同组合CORS 组合矩阵
streamstandard, stream流式响应
foo / barstandard最小标准 scheme

cors* / no-cors* 这一组是第 17 章那个"CORS 洞"的对照实验装置:把 corsEnabled、supportFetchAPI、standard 三个开关两两组合成不同的 scheme,spec 就能逐个验证 IsCorsDisabledSchemeRequest 手工补丁的行为。这也是"测试代码即规格"的一个例子——privileges 的组合语义,仓库里最精确的定义其实在这张表里。

三个 global.* 变量(standardScheme、zoomScheme、serviceWorkerScheme)挂在 global 上,供 spec 直接引用,避免在几十个文件里硬编码字符串。

21.7.5 whenReady() 之后的三道闸

app.whenReady().then(async () => {
  if (!isVitestWorker) {
    console.error('This is the Electron spec app; it is started by the test runner. Run `npm test` ...');
    return process.exit(1);
  }
  const { isTestingBindingAvailable } = await import('./lib/spec-helpers.ts');
  if (process.env.ELECTRON_REQUIRE_TESTING_BINDINGS === '1' && !isTestingBindingAvailable()) {
    throw new Error('Testing build expected, but testing bindings are unavailable');
  }
  workerStarted = true;
  await import('./vitest/worker.ts');
}).catch((err) => { console.error(...); process.exit(1); });
  1. 不是 worker 就拒绝运行:手工 electron spec/ 会打印指引并退出,避免有人以为能这样跑测试。
  2. testing binding 断言:isTestingBindingAvailable() 尝试 process._linkedBinding('electron_common_testing')。这个绑定只在 testing 构建里编译进去(第 20 章 20.3 里 ELECTRON_REQUIRE_TESTING_BINDINGS 的用途)。如果 CI 声明"这是 testing build"却加载不到绑定,说明拿错了二进制,立刻失败而不是跑出一批莫名其妙的 skip。
  3. workerStarted = true 之后才 import('./vitest/worker.ts'),把 21.7.1 的 uncaughtException 切到"交给 vitest"模式,然后由 worker 发 WORKER_READY_MESSAGE。

注意这里用的是动态 import() 而不是顶层 import:spec-helpers.ts 会 import type Electron 的 BrowserWindow,而 utility process 里没有这个导出;makeRemoteContext() 也特意把 electron/main 的导入放在函数内部(注释 "so that this file stays loadable in a utility process")。模块加载时机在这里是功能的一部分,不是风格问题。


21.8 serial 标签:为什么 maxWorkers: 1 不够

spec/CLAUDE.md 第二条给出了这一节的问题:

The runner starts several Electron processes and gives each one spec file at a time, so other windows, from other processes, exist while a test runs. A test that needs OS-level focus, reads or writes the system clipboard, captures the screen, registers global shortcuts, moves the real mouse, or talks to the mocked D-Bus services must be inside a suite declared with describe(title, { tags: ['serial'] }, fn).

受影响的是六类进程外全局状态:窗口焦点、系统剪贴板、屏幕内容、全局快捷键注册、真实鼠标位置、mock D-Bus 服务。这些不属于任何一个 Electron 进程,所以给每个进程独立 userData 也没用。第 18 章讲过 globalShortcut 是进程级注册、Wayland 上 getCursorScreenPoint() 恒返回 (0,0),那些行为到了测试里就变成"两个测试互相抢全局快捷键"。

仓库里 90 个 spec 中有 27 个文件含 serial 标签,共 73 处 tags: 声明,例如:

ifdescribe(process.platform === 'darwin')('app isActive API', { tags: ['serial'] }, () => {
ifdescribe(shouldRunUpdaterSpecs)('autoUpdater behavior', { tags: ['serial'], timeout: 120000 }, () => {
it('correctly reports maximized state ...', { tags: ['serial'] }, async () => {

21.8.1 用正则扫文件内容来分 project

vitest.config.ts:38-40 里最反直觉的一行:

const serialTagPattern = new RegExp(`tags:\\s*\\[[^\\]]*['"]${SERIAL_TAG}['"]`);
const serialFiles = specFiles.filter((file) =>
  serialTagPattern.test(fs.readFileSync(path.join(specDir, file), 'utf8'))
);

它没有用 vitest 的 tag 系统来决定哪些文件属于哪个 project,而是读文件文本做正则匹配。 原因是 project 的 include 必须在配置阶段就确定(vitest 要先知道把哪些文件分配给哪个 project 才能起 worker),而 tag 是加载测试模块之后才有的运行时元数据。这是一个"先静态粗分、再运行时细分"的两级方案:文件里只要出现过 tags: ['serial'] 这个字面串,整个文件就同时进入两个 project;然后 parallel project 用 tagsFilter: ['!serial'] 排除带标签的 suite,serial project 用 tagsFilter: ['serial'] 只跑带标签的 suite。注释解释了收益:"A file only takes part in the serial phase if it mentions the tag at all, so most files start Electron once."

代价是:把 'serial' 写成一个变量、或用模板字符串拼 tag,正则就匹配不到,那个 suite 会被两个 project 都过滤掉(parallel 里被 !serial 排除、又没进 serial project 的 include)而静默不跑。这和 21.1 的 misnamed 检查是同一类风险,只是这里没有对应的检查。

vitest.config.ts:136-143

projects: [
  { extends: true, test: {
      name: 'parallel', include: specFiles,
      ...({ tagsFilter: [`!${SERIAL_TAG}`] } as object),
      maxWorkers, sequence: { hooks: 'list', groupOrder: 0 }
  }},
  { extends: true, test: {
      name: SERIAL_TAG,
      pool: electronPool({ electronPath, specDir, electronArgs, exclusive: true }),
      include: serialFiles.length ? serialFiles : ['.none'],
      ...({ tagsFilter: [SERIAL_TAG] } as object),
      maxWorkers: 1, fileParallelism: false,
      sequence: { hooks: 'list', groupOrder: 1 }
  }}
]

几个细节:

  • tagsFilter 用 ...({ ... } as object) 展开并强转,注释 "Typed as CLI-only, but honoured per project"——类型定义说它是 CLI 选项,实际上每个 project 都认。
  • include: serialFiles.length ? serialFiles : ['.none']。空数组会回退到继承 root 的 include(于是 serial project 会把全部 90 个文件再跑一遍),所以必须塞一个不存在的文件名当哨兵,配合 passWithNoTests: true 让它安静地什么都不做。
  • groupOrder: 0 / 1 保证 parallel 阶段整体先于 serial 阶段。
  • serial project 覆盖了自己的 pool,带上 exclusive: true(21.4.2 的 await Promise.all(liveWorkers))。maxWorkers: 1 与 fileParallelism: false 只是 vitest 侧的调度约束,真正保证"机器上没有别的 Electron"的是 exclusive——因为 vitest 不等待上一个 worker 真的退出。

21.8.2 global-setup.js:49-54:清孤儿进程只能做一次

export function setup(project) {
  project.vitest.logger.log(`Running specs in up to ${process.env.ELECTRON_SPEC_WORKERS} Electron processes at a time (ELECTRON_SPEC_WORKERS)`);
  const execPath = process.env.ELECTRON_SPEC_ELECTRON_PATH;
  if (!execPath || process.env.ELECTRON_SPEC_KEEP_RUNNING_INSTANCES) return;
  for (const pid of findProcesses(execPath)) {
    if (pid === process.pid) continue;
    // win32: taskkill /F /PID <pid> /T ; 其它: process.kill(pid, 'SIGKILL')
  }
}

注释点出了它和 mocha 时代的区别:

Kills Electron processes left behind by an earlier, interrupted run of this same build (a spec's fixture app that never quit keeps ports and single instance locks busy). The mocha runner did this before every file from inside Electron; with several workers sharing one executable that would take down the other workers, so it happens once up front instead.

"按可执行文件杀"在多 worker 架构下是危险动作:如果每个文件开跑前都扫一遍并杀掉同路径的进程,会把正在跑别的 spec 的 worker 一起干掉。于是挪到 globalSetup(CLI 进程里、任何 worker 启动之前)只做一次。ELECTRON_SPEC_KEEP_RUNNING_INSTANCES 是给"故意对同一个 build 起两个 invocation"的场景留的退出口。

findProcesses 三种实现:Windows 用 wmic process where ExecutablePath='...' get ProcessId /format:value(路径里的反斜杠要先转义);Linux 遍历 /proc,对每个数字目录 fs.readlinkSync('/proc/<pid>/exe') 精确比对(比 pgrep -f 精确,不会误杀命令行里恰好提到该路径的进程);macOS / 其他用 pgrep -f。整个函数包在 try/catch 里,wmic 不存在或没权限都忽略——清理是 best-effort,不能反过来让测试起不来。

21.8.3 并发度:为什么是 CPU 数的三分之一

function availableCpus() {
  let cpus = os.availableParallelism();
  if (process.platform === 'linux') {
    const quota = (text) => {
      const [max, period] = text.trim().split(/\s+/).map(Number);
      return max > 0 && period > 0 ? Math.ceil(max / period) : Infinity;
    };
    try { cpus = Math.min(cpus, quota(fs.readFileSync('/sys/fs/cgroup/cpu.max', 'utf8'))); } catch {}
    try {
      const v1 = ['cpu.cfs_quota_us', 'cpu.cfs_period_us'].map((f) =>
        fs.readFileSync(`/sys/fs/cgroup/cpu/${f}`, 'utf8').trim());
      cpus = Math.min(cpus, quota(v1.join(' ')));
    } catch {}
  }
  return cpus;
}
const maxWorkers = Number(process.env.ELECTRON_SPEC_WORKERS) ||
  Math.min(8, Math.max(Math.min(2, cpus), Math.round(cpus / 3)));

os.availableParallelism() 在容器里可能返回宿主机的核数,所以 Linux 上还要读 cgroup:v2 的 /sys/fs/cgroup/cpu.max(格式 max period,max 为字符串 max 时 Number 得到 NaN,max > 0 为 false → 返回 Infinity)、v1 的两个文件。quota 返回 Infinity 表示不限,取 Math.min 不影响结果。

cpus/3 的理由写在注释里:"Each one keeps roughly three processes busy (browser, GPU, renderer)"。下限 2("two even on the small 3-4 core CI hosts"),上限 8。ELECTRON_SPEC_WORKERS 可覆盖,且被写回环境变量供 global-setup.js:51 打印。

21.8.4 两阶段时序

CLI 进程
 ├─ globalSetup: 按 execPath 杀掉上次残留的 Electron
 ├─ project "parallel" (groupOrder 0, maxWorkers ≤ 8)
 │   └─ 每个 spec 文件一个 Electron 进程;tags: ['serial'] 的 suite 被 tagsFilter 排除
 ├─ [exclusive 等待] serial project 的每个 worker 启动前 await Promise.all(liveWorkers)
 └─ project "serial" (groupOrder 1, maxWorkers 1, fileParallelism false)
     └─ 一次一个文件、一次一个进程,只跑带 serial 标签的 suite

SpecTimingsReporter 的注释补了一句:"a file that runs in both the parallel and the serial phase has both durations added up" —— 27 个含 serial 标签的文件会起两次 Electron、耗时累加,这正是分片权重必须按文件实测而不是按文件大小估的原因。

21.9 CI 分片:LPT 装箱、每 job 一张权重表、三层过滤

21.9.1 shard 矩阵

pipeline-segment-electron-test.yml 的 matrix 是一长串 case 表达式(第 79 行):

条件shard 列表
display-server == 'wayland'[1]
macOS + UBSan[1,2,3]
Linux[1,2,3]
macOS + !full-macos-tests + x64[1]
macOS + x64(全量)[1,2,3]
其余(Windows、macOS arm64)[1,2]

build-type 还有一层 exclude:reduced macOS arm64 leg 会把 {"build-type":"mas","shard":2} 排除。ARTIFACT_KEY 是 <build-type>_<arch>,ASan/UBSan 步骤里再追加 _asan / _ubsan。这个 key 一路贯穿三处:产物上传名 test_artifacts_<key>_<shard>、split-tests.js:15-31 选权重表、SpecTimingsReporter 标 mas。

21.9.2 split-tests.js:77-84:最大处理时间优先的贪心装箱

const ordered = specFiles
  .map((file) => ({ file, weight: weightOf(file) }))
  .sort((a, b) => b.weight - a.weight || a.file.localeCompare(b.file));
for (const { file, weight } of ordered) {
  let target = buckets[0];
  for (const bucket of buckets) {
    if (bucket.total < target.total) target = bucket;
  }
  target.files.push(file);
  target.total += weight;
}
console.log(buckets[currentShard - 1].files.join(' '));

这是经典的 LPT(Longest Processing Time first):按预估耗时降序,每次投进当前最轻的桶。同权重时按文件名字典序,保证每次运行的分片结果完全确定(否则 gh run download 拿到的时序数据对不上分片)。

weightOf 是三级兜底:

const weightOf = (file) => {
  if (weights[file] !== undefined) return weights[file];
  if (known.length) return median;
  return fs.readFileSync(file, 'utf8').split('it(').length;
};

有表用表值,表里没有该文件用已知权重的中位数,整张表都没有则退回数 it( 的个数。最后一级只在仓库刚引入这套机制、还没跑过一次 CI 时生效。

21.9.3 为什么一个 CI job 一张表

split-tests.js:36-43 文件头的注释把理由给全了:

Jobs differ by more than a constant factor — MAS builds skip the updater specs, ASan slows native-heavy specs 7x and others not at all, arm64 is faster in some files than others — so one table per platform packs the other jobs' shards unevenly.

所以 spec-weights.json 不是 {file: seconds},而是 {jobKey: {file: seconds}}。文件里既有新的 darwin_x64 之类,也保留着旧的按平台命名(darwin)的表。pickTable 的回退链有五层:

const pickTable = (all, key) => {
  if (all[key]) return all[key];
  const [buildType, arch] = key.split('_');
  const family = buildType === 'mas' ? ['mas', 'darwin'] : [buildType];
  for (const type of family) {
    const nearest = Object.keys(all)
      .filter((k) => k.startsWith(`${type}_`))
      .sort((a, b) =>
        (a.split('_')[1] === arch ? 0 : 1) - (b.split('_')[1] === arch ? 0 : 1) ||
        a.split('_').length - b.split('_').length || a.localeCompare(b))[0];
    if (nearest) return all[nearest];
  }
  return all[process.platform] ?? all.darwin_x64 ?? all.darwin ?? Object.values(all)[0] ?? {};
};

排序键依次是:同 arch 优先 → 名字段数少(也就是没有 sanitizer 后缀的"最普通"表)优先 → 字典序。mas 特殊,找不到 mas 表时允许回退到 darwin 家族。

21.9.4 权重表从哪来:一个闭环

CI 跑完 → SpecTimingsReporter 写 spec/artifacts/spec-timings.json
        → CI 上传 test_artifacts_<key>_<shard>
        → 维护者在一次 green build 上执行:
             gh run download <run-id> --repo electron/electron -D /tmp/spec-timings -p 'test_artifacts_*'
             node script/gen-spec-weights.js /tmp/spec-timings
        → 脚本递归找所有 spec-timings.json
        → jobKeyOf(timings, file) 生成 key
        → 每个文件取 Math.max(所有 shard 的值)
        → 写回 script/spec-weights.json
        → 下一次 CI 的 split-tests.js 用它装箱

SpecTimingsReporter(46 行)只做一件事,但四个元数据字段都有用:

fs.writeFileSync(path.join(artifactsDir, 'spec-timings.json'), JSON.stringify({
  platform: process.platform,
  arch: process.arch,
  mas: process.env.ARTIFACT_KEY?.startsWith('mas') ?? false,
  sanitizer: process.env.IS_ASAN === 'true' ? 'asan' : process.env.IS_UBSAN === 'true' ? 'ubsan' : null,
  files
}, null, 2));

mas 为什么要从 ARTIFACT_KEY 推而不是 process.mas?因为 reporter 跑在 CLI 的宿主 Node 进程里,那里根本没有 process.mas。这是 21.0 三条判据里"进程身份"的一个具体体现。jobKeyOf 也照顾了旧数据:

const buildType = timings.mas ? 'mas' : (BUILD_TYPES[timings.platform] ?? timings.platform);
const sanitizer = timings.sanitizer ?? (/_(asan|ubsan)_/.exec(file)?.[1] || null);
return `${buildType}_${timings.arch}${sanitizer ? `_${sanitizer}` : ''}`;

老版本的 timings 没有 sanitizer 字段,就从产物目录名里正则捞。/_wayland_/ 的目录被整个跳过,因为 Wayland leg 只跑 allowlist,数据是残缺的,混进来会把对应文件的权重压低。

"多个 shard 覆盖同一文件取最大值"对应重试场景:一次重试说明那次跑得慢或者卡过,用最大值是保守估计,让分片宁可不均衡也不要超时。

21.9.5 三张 allowlist 与"改名了必须报错"

CI 命令先 split-tests 拿到本 shard 的文件列表,再按 allowlist 过滤:

if [ "${{ inputs.display-server }}" = "wayland" ]; then
  allowlist_file=script/wayland-test-allowlist.txt
elif [ -n "$MACOS_SPEC_ALLOWLIST" ]; then
  allowlist_file="$MACOS_SPEC_ALLOWLIST"
  while IFS= read -r allowed; do
    case "$allowed" in ''|'#'*) continue ;; esac
    if [ ! -f "$allowed" ]; then
      echo "::error file=$allowlist_file::lists $allowed, which does not exist"
      exit 1
    fi
  done < "$allowlist_file"
fi
...
for test_file in $tests_files; do
  if grep -Fxq "$test_file" "$allowlist_file"; then filtered_tests="$filtered_tests $test_file"; fi
done

三个要点:

  • grep -Fxq 是整行精确匹配(-F 固定字符串、-x 整行、-q 静默),不是子串。allowlist 里的注释行由 case ... '#'*) continue 跳过。
  • 那个 while 循环是专门防"spec 被改名/删除后,reduced leg 静默少跑一个文件"的:allowlist 里列的路径不存在就直接 ::error 并 exit 1。和 21.1 的 misnamed 检查是同一种防御。
  • 过滤后一个都不剩时 echo "No tests matched ... skipping."; exit 0,不算失败——因为分片是随权重表变化的,某个 shard 恰好落到 allowlist 之外是正常情况。

三张表的内容本身就是一份"哪些行为依赖 OS / 架构"的清单:

表条数选它的逻辑
wayland-test-allowlist.txt:17只有能在 Wayland 下成立的:parse-features-string、types、version-bump、api-app、api-browser-window、api-clipboard、api-menu
macos-x64-spec-allowlist.txt16注释写明选的是"行为可能随 CPU 架构变化"的:V8 code cache、JIT/WASM、Node 启动 snapshot、原生 addon、crash reporting,加上 Squirrel.Mac 的 x64-only 用例
macos-mas-spec-allowlist.txt:514注释写明选的是"mas 与 darwin 构建有差异"的:IS_MAS_BUILD()、is_mas_build、patches/chromium/mas_*,包括私有 API 扫描、app sandbox、security-scoped bookmark、keychain、StoreKit、无 crashpad 的崩溃路径

第 20 章讲过 MAS 构建里 crashReporter 整个降级、autoUpdater 编译成空函数;这张 mas allowlist 就是把那些差异逐条列出来并注明原因,读它比读文档快。

21.9.6 三层过滤叠加

一个 spec 最终跑不跑,要过三道互不知情的闸:

  1. 分片层(split-tests.js):按权重把这个文件分给某个 shard;shard 数随平台、sanitizer、full-macos-tests 变化。
  2. allowlist 层(CI shell):Wayland / reduced macOS leg 只保留白名单文件。
  3. 文件内层(ifdescribe / ifit):按 process.platform、process.mas、编译期 binding、环境开关再关一批 suite 或 case。

所以"这个测试在 CI 上跑了吗"不是一个能靠看 spec 源码回答的问题。这也是为什么 CI 要把 --files $tests_files 显式打进日志、把 JUnit XML 上传、并在 ::error 里点名不存在的 allowlist 条目。

21.9.7 权重表的实际内容,与注释承诺的形态不一致

读 script/spec-weights.json 本身比读注释更能说明现状。这份仓库快照里的表只有三张,键是旧格式:

表名条目数权重为 0 的文件数
darwin8413
linux8334
win328322

而 CI 传下来的 ARTIFACT_KEY 是 darwin_x64、linux_x64_asan、mas_arm64、win_arm64 这类新格式。把它们喂给 pickTable() 会发生什么:

  1. all[key] —— 三张表里没有 darwin_x64,精确匹配全部落空;
  2. family 回退找 k.startsWith('darwin_') 或 mas_ 的表 —— 同样一个都没有;
  3. 落到 all[process.platform] ?? all.darwin_x64 ?? ... 的第一项,也就是 darwin / linux / win32 三张旧表。

结论是:注释里那句"每个 job 一张表,MAS 跳过 updater、ASan 让原生重的 spec 慢 7 倍、arm64 有些文件更快",在这份快照里还没有兑现——所有 job(含 MAS、ASan、UBSan、arm64)共享同一张按平台命名的粗表。gen-spec-weights.js:36 确实会按 jobKeyOf() 生成 darwin_x64 之类的新 key,但它的使用说明是维护者在一次 green build 上手工执行 gh run download ... -p 'test_artifacts_*' 再跑脚本,产物需要人工提交;SpecTimingsReporter 只负责写进产物,不会自动回写仓库。

所以 pickTable 那条五层回退链不是冗余的防御,而是当前每次分片真正依赖的路径。这也意味着 21.9.3 列的三种 job 差异仍然会影响分片均衡——只是没有被权重表补偿,而是被 --enableRerun=3 与 60 分钟的 job 超时兜着。

另外两个可以直接从表里读出来的事实:

  • 权重 0 的文件:darwin 表里 api-auto-updater.spec.ts、api-autoupdater-msix.spec.ts、api-notification-dbus.spec.ts:26 等 13 个为 0;linux 表里有 34 个,包含两个 api-autoupdater-darwin*.spec.ts(第 20 章那两套 macOS 专用实现)。这些 0 不是"跑得飞快",而是该平台上整个文件被门控跳过、没有产生 timings。LPT 装箱会把它们排到末尾再投进最轻的桶,行为上无害,但读表时不能把 0 当成耗时。
  • 表外文件:三张表都只有 83–84 条,而 spec/*.spec.ts 有 90 个,缺口由 weightOf() 的中位数兜底。所以"新增一个 spec 文件"在第一次权重表更新前,是按所有已知文件的中位耗时估的,不是按它的 it( 数量。

这和第 19 章 osr/README.md 的情况是同一类:注释描述设计意图,数据描述当前状态。写"CI 怎么分片"时,两者都得看。

21.10 门控:ifdescribe / ifit 与被跳过的一整类行为

spec-helpers.ts:18-24 开头两行是全仓库用得最多的工具:

export const ifit = (condition: boolean) => (condition ? it : it.skip);
export const ifdescribe = (condition: boolean) => (condition ? describe : describe.skip);
export const isWayland =
  process.platform === 'linux' &&
  (process.env.XDG_SESSION_TYPE === 'wayland' ||
    !!process.env.WAYLAND_DISPLAY ||
    process.argv.includes('--ozone-platform=wayland'));

isWayland 用三个判据的或,因为 CI 的 Wayland leg 是 run-tests-wayland.sh:4 设 XDG_SESSION_TYPE + WAYLAND_DISPLAY、再传 --ozone-platform=wayland;本地开发可能只设其中一个。第 18 章的 screen.getCursorScreenPoint() 在 Wayland 恒返回 (0,0),相关用例就靠这个常量跳过。

把仓库里的门控条件按"判据来自哪里"分层,能看出哪些行为是根本测不了的:

层次判据例子关掉的是
平台process.platform / process.mas / process.windowsStoreifdescribe(process.platform === 'darwin')('dock APIs', ...)该平台不存在的 API
显示后端isWayland / hasCapturableScreen()ifdescribe(!isWayland)('focus, blur, and z-order', ...)协议不提供全局坐标 / 焦点
构建身份features.isComponentBuild() / isTestingBindingAvailable()shouldRunCodesignTests、spec/node.spec.ts:359该构建没编译进去的绑定
签名 / 包身份getCodesignIdentity() / shouldRunUpdaterSpecs / shouldRunMsixTests第 20 章 autoUpdater 的三套实现需要真实证书、真实安装包
工具链可用性ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECSspec/node.spec.ts:687没编译出 Electron 头文件的 addon
运行时禁用disabled-tests.json 的全标题21.6.4 的 7 条roll 期间临时放行
Node 上游node-disabled-tests.json / node-flaky-tests.json21.12upstream suite 里在 Electron 下不通的用例

几个具体常量的因果:

// spec/lib/codesign-helpers.ts
export const shouldRunCodesignTests =
  process.platform === 'darwin' && !process.mas && !features.isComponentBuild();

// spec/lib/autoupdater-darwin-helpers.ts
export const shouldRunUpdaterSpecs = shouldRunCodesignTests && !process.env.IS_UBSAN;

// spec/lib/msix-helpers.ts
export const shouldRunMsixTests = process.platform === 'win32';

isComponentBuild() 是第 20 章 20.1 里 features.cc:37-55 导出的 6 个 buildflag 方法之一(IsComponentBuild 读 defined(COMPONENT_BUILD))。component build 里 Electron Framework 是分散的 dylib,无法整体签名,所以签名测试直接关掉。UBSan 又额外把 updater 测试关掉,因为那一套要反复 codesign / ditto / 起 ShipIt,在 sanitizer 构建下慢到不可用。

isTestingBindingAvailable() 的实现是"试着取一下":

export function isTestingBindingAvailable() {
  try { process._linkedBinding('electron_common_testing'); return true; }
  catch { return false; }
}

它同时被两处使用:spec/index.js 在 ELECTRON_REQUIRE_TESTING_BINDINGS === '1' 时做硬断言(拿错二进制直接失败),spec/node.spec.ts 用它做软门控(没有绑定就 skip 那条 suite)。同一个信号,一个当断言、一个当开关——区别只在于"这个测试是否必须依赖 testing 构建"。

这些都是 skip 而不是"改写期望值"。所以 CI 的绿色从来不等于"所有行为都验证过",它等于"在当前构建身份与机器能力下,能验证的都过了"。理解这一点,才知道为什么第 20 章那些平台差异要靠读源码而不是靠读测试来确认。


21.11 两套重试与 JUnit XML:失败是怎么被找回来重跑的

Electron 的测试有两层彼此不知道对方存在的重试:

层位置触发次数依据
框架层spec/vitest.config.ts 的 retry: isCI ? 3 : 0某个 test 失败最多 3 次重试(共 4 次尝试)vitest 内部的 task 状态
runner 层script/spec-runner.js:327-329 的 --enableRerun=3vitest 进程退出码非 0每个失败用例最多 3 次JUnit XML

两层叠加的最坏情况是同一个 flaky 用例被跑 16 次,但它们解决的是不同问题:框架层重试发生在同一个 Electron 进程内,对"偶发时序抖动"有效;runner 层重试会重新起一个干净的 Electron 进程,对"上一个测试泄漏了全局状态"有效。CI 里 Windows / macOS / Linux 普通构建传 --enableRerun=3,ASan / UBSan 步骤则不传(sanitizer 构建每次启动都很贵,且失败多为真实内存错误)。

21.11.1 JUnit 文件从哪来

runElectronTests() 在跑每个 runner 之前拼出路径:

const testResultsDir = process.env.ELECTRON_TEST_RESULTS_DIR;
if (testResultsDir) {
  process.env.ELECTRON_SPEC_JUNIT_FILE = path.join(testResultsDir, `test-results-${runnerId}.xml`);
}

vitest.config.ts 里看到这个变量就挂上 ['junit', { outputFile: ..., includeConsoleOutput: false }] reporter。CI 步骤开头 export ELECTRON_TEST_RESULTS_DIR=\pwd`/junit,所以产物是 junit/test-results-main.xml,后面既用于失败重跑,也上传到 DataDog(datadog-ci junit upload)和 test_artifacts_*`。

includeConsoleOutput: false 值得留意:不把 console 输出塞进 XML,否则一个打了大量 --enable-logging 日志的失败用例会把 XML 撑到几十 MB,重跑时解析都慢。

21.11.2 parseJUnitXML():从 XML 反查文件与用例名

function parseJUnitXML(specDir) {
  if (!fs.existsSync(process.env.ELECTRON_SPEC_JUNIT_FILE)) {
    console.error('JUnit XML file not found:', process.env.ELECTRON_SPEC_JUNIT_FILE);
    return [];
  }
  const xmlDoc = new DOMParser().parseFromString(fs.readFileSync(...), 'text/xml');
  const failedTests = [];
  const testSuites = xmlDoc.getElementsByTagName('testsuite');
  for (let i = 0; i < testSuites.length; i++) {
    const testSuite = testSuites[i];
    const failures = testSuite.getAttribute('failures');
    if (failures > 0) {                 // 字符串与数字比较,隐式转换
      const testcases = testSuite.getElementsByTagName('testcase');
      for (let i = 0; i < testcases.length; i++) {
        const testcase = testcases[i];
        const failures = testcase.getElementsByTagName('failure');
        const errors = testcase.getElementsByTagName('error');
        if (failures.length > 0 || errors.length > 0) {
          const testName = testcase.getAttribute('name');
          const suiteName = testSuite.getAttribute('name');
          const filePath = testSuite.getAttribute('file') ||
            (suiteName ? path.resolve(__dirname, '..', specDir, suiteName) : null);
          const fileName = filePath ? path.relative(specDir, filePath) : 'unknown file';
          failedTests.push({ name: testName, file: fileName, filePath, ... });
        }
      }
    }
  }
  return failedTests;
}

注释点明了一个 vitest 输出格式的细节:"vitest names each <testsuite> after the spec file, relative to spec/",所以 suiteName 可以直接和 specDir 拼成路径;优先用 file 属性,没有才回退。includeTaskLocation: true(21.6.5)让 file 属性尽可能存在。

内层 for 复用了外层变量名 i(let i 各自作用域,没问题但读起来容易误判)。每个失败项同时收集 <failure> 与 <error> 节点的 textContent || nodeValue || 'No failure message'。

21.11.3 单条重跑:正则转义与原参数清理

async function rerunFailedTest(specDir, testName, testInfo) {
  let grepPattern = testInfo.name;
  grepPattern = grepPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const args = [];
  if (testInfo.filePath) args.push('--files', testInfo.filePath);
  args.push('-g', grepPattern);
  const success = await runTestUsingElectron(specDir, testName, false, args);
  ...
}

测试标题里几乎必然带括号、点号、[](例如 ses.cookies should set cookie for standard scheme、各种 'should emit ...' 带路径),直接当 --testNamePattern 用会被正则元字符改变语义,所以必须先转义。这一步和 21.2 的 -g → --testNamePattern 串起来:runner 层重跑实际上重新走了一遍完整的七层启动链,只是 --files 缩到一个文件、-g 缩到一条用例。

runTestUsingElectron 里有一段专门为重跑准备的参数清理:

if (additionalArgs.includes('--files')) {
  argsToPass = argsToPass.filter((arg) =>
    arg.toString().startsWith('--log-file=') ||
    (arg.toString().indexOf('--files') === -1 && arg.toString().indexOf('spec/') === -1)
  );
}

把第一次运行传进来的整批 --files spec/a.spec.ts spec/b.spec.ts ... 全部丢掉(否则重跑会把整个 shard 再跑一遍),但保留 --log-file=,这样 21.2 的 .rerun-N 改写才有对象。shouldRerun 传 false,防止重跑失败又触发一轮重跑形成递归。

21.11.4 整轮重跑的状态机

async function rerunFailedTests(specDir, testName) {
  const failedTests = parseJUnitXML(specDir);
  if (failedTests.length === 0) { console.log('No failed tests could be found.'); process.exit(1); }
  if (fs.existsSync(process.env.ELECTRON_SPEC_JUNIT_FILE)) {
    fs.copyFileSync(process.env.ELECTRON_SPEC_JUNIT_FILE, `${process.env.ELECTRON_SPEC_JUNIT_FILE}.save`);
  }
  ...
  for (const testInfo of failedTests) {
    let runCount = 0, success = false;
    while (!success && runCount < args.enableRerun) {
      success = await rerunFailedTest(specDir, testName, testInfo);
      if (success) results.passed++;
      else if (runCount === args.enableRerun - 1) results.failed++;
      else retryTest = true;
      if (retryTest || index < failedTests.length - 1) await new Promise((r) => setTimeout(r, 2000));
      runCount++;
    }
  }
  // 恢复原始 junit xml
  if (fs.existsSync(`${...}.save`)) fs.renameSync(`${...}.save`, process.env.ELECTRON_SPEC_JUNIT_FILE);
  if (results.failed === 0) { /* 视为整轮通过 */ } else process.exit(1);
}

三处值得记:

  • 先把原始 XML 复制成 .save,最后再 rename 回来。因为每次重跑都会让 vitest 覆写同一个 outputFile,不备份的话最终上传的只剩最后一条用例的结果,其余失败记录全丢。
  • 每条失败用例之间固定等 2 秒。这是给上一轮泄漏的进程 / 端口 / 单实例锁留的消散时间(21.5 的 global-setup.js 只能清 Electron 主进程,Update.exe、ShipIt 这类不在其中)。
  • 解析不到失败用例时 exit(1),不是"当作通过"。因为进入这个函数的前提是 vitest 退出码非 0;如果 XML 里没有可归因的失败,说明是进程崩溃 / 启动失败 / 框架级错误,重跑单个用例解决不了,必须让 CI 红。

还有一条容易忽略的:rerunFailedTests 全通过时,函数正常返回,runTestUsingElectron 随后仍会打印 ✓ Electron main process tests passed.——也就是一次实际失败过的 run 最终被判为绿,只在日志里留下 "Rerunning failed test" 与 "Passed on rerun" 的痕迹。查 flaky 率时不能只看 CI 是否绿,要看 JUnit 里原始那份(.save 被恢复了)与日志。

21.12 三套"非 spec"测试:Node 上游、NAN ABI、构建产物

L1 之外的三层各有自己的 runner,都不经过 spec/vitest/。

21.12.1 node-spec-runner.js:29-36:拿 Node 官方 suite 测 Electron

script/node-spec-runner.js:29-36(169 行)跑的是 third_party/electron_node/test/ 里的 Node.js 上游测试套件,通过 tools/test.py 执行,但 --shell 指向 Electron 可执行文件:

const defaultOptions = [
  'tools/test.py', '-p', 'tap', '--logfile', TAP_FILE_NAME,
  '--mode=debug', 'default',
  `--skip-tests=${DISABLED_TESTS.join(',')}`,
  '--flaky-tests=dontcare', '--measure-flakiness=9',
  '--shell', utils.getAbsoluteElectronExec(), '-J'
];
...
const testChild = cp.spawn('python3', options, {
  env: { ...process.env, ELECTRON_RUN_AS_NODE: 'true' },
  cwd: NODE_DIR, stdio: 'inherit'
});

ELECTRON_RUN_AS_NODE: 'true' 让同一个二进制以纯 Node 模式运行——第 20 章 20.2 讲过,这个环境变量还被 run_as_node fuse 前置闸住。这里与 21.4.2 的 delete env.ELECTRON_RUN_AS_NODE 构成一组漂亮的对仗:同一份测试基础设施里,一个 runner 必须把它设上,另一个必须把它删掉;差别只是被测的进程身份不同。

最有意思的是 REWRITES:

const REWRITES = [
  { file: ROOT_PACKAGE_JSON, rewrite: () => null },
  { file: OUT_PACKAGE_JSON, rewrite: () => null },
  { file: ROOT_STATUS, rewrite: (original) =>
      `${original}\n[true]\n${FLAKY_TESTS.map((test) => `${test}: PASS,FLAKY`).join('\n')}\n` }
];

注释把原因说透了:

The upstream suite assumes there is no package.json above its test files or rooted at process.execPath; Chromium's src/ root and the output directory both have a "type": "module" one, which changes module-type detection for test files and fixtures and emits MODULE_TYPELESS_PACKAGE_JSON warnings that break tests asserting clean stderr.

也就是说两个无关的 package.json 会改变上游测试对 .js 文件模块类型的判断,并往 stderr 打警告,而上游有一批测试断言 stderr 为空。解法不是改测试,而是在跑测试期间把这两个文件临时移走,跑完再放回来。

自愈机制做得很完整:

const backupPath = (file) => `${file}.spec-runner-backup`;
async function main() {
  restoreRewrites();     // 先撤销上一次被中断的 run
  applyRewrites();
  process.on('exit', restoreRewrites);
  process.on('SIGINT', () => process.exit(130));
  process.on('SIGTERM', () => process.exit(143));
  ...
}

--validateDisabled 模式则遍历 node-disabled-tests.json 与 node-flaky-tests.json,确认每个名字还能在 test/<name>.js 或 .mjs 找到;Node roll 之后上游删了某个测试,这份清单就会报错,避免"禁用清单里躺着一个不存在的名字"慢慢腐烂。

TAP 输出由 tap-xunit 转成 nodejs.xml 放进 JUNIT_DIR。

21.12.2 nan-spec-runner.js:24-28:验证头文件能编出能加载的 addon

NAN(Native Abstractions for Node.js)的测试套件在 third_party/nan/。这类测试不测 JS 行为,测 ABI:用 out/<outDir>/gen/node_headers 编译一遍 NAN 的 C++ 测试 addon,看它在 Electron 的 Node 下能不能 require 进来。

const nodeDir = path.resolve(BASE, 'out', outDir, 'gen', 'node_headers');
const env = {
  npm_config_msvs_version: '2022', ...process.env,
  npm_config_nodedir: nodeDir,
  npm_config_arch: process.env.NPM_CONFIG_ARCH
};

编译标志几乎逐条抄自 Chromium 的构建配置:

const cxxflags = [
  '-std=c++20', '-Wno-trigraphs', '-fno-exceptions', '-fno-rtti',
  '-nostdinc++',
  `-isystem "${.../buildtools/third_party/libc++}"`,
  `-isystem "${.../third_party/libc++/src/include}"`,
  `-isystem "${.../third_party/libc++abi/src/include}"`,
  '-fvisibility-inlines-hidden', '-fPIC',
  '-D_LIBCPP_ABI_NAMESPACE=Cr',
  '-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE',
  ...platformFlags
].join(' ');

-nostdinc++ + 三个 -isystem 强制使用 Chromium 自带的 libc++;-D_LIBCPP_ABI_NAMESPACE=Cr 匹配 Chromium 构建时改过的 ABI 命名空间——用系统 libstdc++ 编出来的 addon 在 Electron 里会在符号解析阶段就失败。macOS 上还要从 out/<outDir>/sdk/xcode_links 里按版本号排序挑最新的 .sdk,多个 SDK 时打一条警告。

这条链路是 L3,它和 21.13 的 fixture 编译是同一个问题的两面:一个测"上游 NAN 能不能用",一个测"仓库自己那九个 addon 能不能用"。

21.12.3 L4:直接对产物下手的四个 verify 脚本

脚本检查什么手法
script/verify-chromedriver.py打包出来的 chromedriver 能否初始化起进程读第一行 stdout,正则 ^Starting ChromeDriver [0-9]+.[0-9]+.[0-9]+.[0-9]+ .* on port [0-9]+$ 匹配(源码里四个 . 未转义),不匹配就返回 1,最后 terminate()
script/verify-mksnapshot.py:29自定义 V8 snapshot blob 是否真的被主进程加载解压 mksnapshot.zip → 按 mksnapshot_args 重建 snapshot_blob.bin → 跑 v8_context_snapshot_generator → 复制 .bin 到 app → 启动 spec/fixtures/snapshot-items-available 检查自定义项存在
script/gn-asar-hash.js / gn-asar.jslib/ / default_app/ 打进 asar 的内容与构建图一致计算 hash 与 GN 声明比对
script/check-patch-diff.mtspatches/ 与上游 Chromium 的差异仍适用比对补丁应用结果

verify-mksnapshot.py 对应的 CI 步骤有个非常具体的名字:"Verify custom mksnapshot blobs reach the main process",且只在 linux + x64 + 非 ASan + 非 Wayland + shard == 1 跑一次。注释解释了为什么必须单独立一步:

The build leg only exercises --create-snapshot-only —— 构建阶段只验证"能生成 blob",不验证"生成的 blob 会被主进程用上"。第 20 章 20.2 里 EnableNodeStartupSnapshot 与自定义 snapshot 互斥的那条规则,正是靠这一步从产物侧兜住。

L4 的共同特征是:完全不用 spec 框架、不开 Electron app、不装依赖,直接把产物当黑盒跑一遍,用一行 stdout 或一个 fixture app 的存在性做断言。它能抓到的是"构建配置正确但产物有偏差"这类 L1 永远发现不了的问题。

21.12.4 五层 runner 的对照

层runner进程输入输出
L1spec-runner.js + vitest poolElectron 浏览器进程spec/*.spec.tstest-results-main.xml
L2node-spec-runner.js:144ELECTRON_RUN_AS_NODE上游 test/*.jsTAP → nodejs.xml
L3nan-spec-runner.js系统 Node + 编译器NAN C++ 源码编译/加载结果
L4verify-*.py / gn-*.js构建机 shellout/ 里的产物退出码
L5L1 里的 helper克隆的真实 .app / MSIX签名包 + 更新服务器L1 的断言

注意 L5 没有独立 runner——它寄生在 L1 的 spec 文件里,靠 shouldRunCodesignTests 这类门控决定跑不跑。这是第 20 章那三块"最难测的东西"在测试体系里的真实位置。

21.13 原生 addon fixture:一套工具链探测,两个 ABI 世界

spec/fixtures/native-addon/ 下九个目录,每个都是一个 yarn workspace,编译成 .node 后由 spec 加载。它们在 spec/package.json 里以 @electron-ci/<name> 的形式声明为 devDependency。

九个里只有 object-wrap/package.json 带这一行:

"electron:requiresElectronHeaders": true

原因在 21.3.2 引过的那段注释里:N-API addon 是 ABI 稳定的,用系统 Node 的头文件编出来照样能在 Electron 里加载;而用了 Node C++ 模块 API(V8 / node::ObjectWrap)的 addon 会把 NODE_MODULE_VERSION 编进去,必须用 Electron 的 gen/node_headers 重编。object-wrap 正是后者。

installSpecModules() 尾部逐个检查这个标记并对命中者 node-gyp rebuild:

for (const addon of fs.readdirSync(nativeAddonsDir)) {
  const addonPackage = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
  if (!addonPackage['electron:requiresElectronHeaders']) continue;
  if (toolchainEnv === null) {
    console.log(`${warn} No compiler on this host can build Electron's headers, not rebuilding native addon '${addon}'; its specs will be skipped`);
    process.env.ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECS = '1';
    continue;
  }
  const { status } = childProcess.spawnSync(process.execPath, [nodeGyp, 'rebuild'], { env: rebuildEnv, cwd: addonDir, stdio: 'inherit' });
  if (status !== 0) { ... process.exit(1); }
}

toolchainEnv 来自 getNativeAddonToolchainEnv(),这是整个仓库里最能体现"测试基建要自己解决编译器问题"的函数:

Electron's V8 headers do not compile with GCC <= 12 (attribute ordering on deprecated classes, see issue #53284), which is what the Linux CI test image ships. When the Chromium toolchain from the source checkout is available (CI restores it into the test job's src_artifacts) build the addons with clang and Electron's libc++, mirroring script/nan-spec-runner.js. Without it fall back to the system compiler.

三条分支:

  1. Chromium 工具链齐全 → 用 third_party/llvm-build/Release+Asserts/bin/clang{,++,lld} 加 Electron 的 libc++ headers/libs,拼出与 21.12.2 相同的 -nostdinc++ / -D_LIBCPP_ABI_NAMESPACE=Cr 等标志。
  2. 工具链不齐 → required 五项里任一不存在就打日志并用系统编译器(返回 {})。
  3. 工具链存在但跑不起来 → 返回 null,触发上面那段 ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECS 门控。

第三种不是假想:

const { error: clangError, status: clangStatus } = childProcess.spawnSync(
  path.join(clangDir, 'clang++'), ['--version'], { stdio: 'ignore' });
if (clangError || clangStatus !== 0) {
  console.log(`${warn} Chromium clang cannot run on this ${process.arch} host (...)`);
  return null;
}

注释指明场景:"the linux-arm64 test job runs on an arm64 host but restores the x64 clang of the (cross-compiling) build job, and the system compiler there is the same GCC that rejects the headers, so nothing on that host can build the fixtures." 也就是 arm64 测试机拿到的是交叉编译构建产出的 x64 clang,既跑不动 clang,系统 GCC 又编不了 V8 头文件——两条路都断,只能让相关 spec 跳过。

跨架构编译时还会查 sysroots.json:

const target = {
  arm: ['arm-linux-gnueabihf', 'bullseye_armhf'],
  arm64: ['aarch64-linux-gnu', 'bullseye_arm64'],
  ia32: ['i686-linux-gnu', 'bullseye_i386'],
  x64: ['x86_64-linux-gnu', 'bullseye_amd64']
}[targetArch];
const [triple, sysrootName] = target;
const sysroot = path.resolve(BASE, 'build', 'linux', require('./sysroots.json')[sysrootName].SysrootDir);
targetFlags.push(`--target=${triple}`, `--sysroot="${sysroot}"`);

最后还有一个 sanitizer 专属分支:

const ldflags = ['-stdlib=libc++', '-fuse-ld=lld', `-L"${libcxxLibDir}"`];
if (fs.existsSync(path.join(libcxxabiLibDir, 'libc++abi.a'))) {
  ldflags.push(`-L"${libcxxabiLibDir}"`, '-lc++abi');
}

注释解释:sanitizer 构建把 libc++abi 编进 electron 可执行文件并从中导出符号(Chromium 的 export_libcxxabi_from_executables),不产静态库;此时 addon 加载时符号由主程序提供,链接 -lc++abi 反而会找不到文件。所以判据是".a 存不存在",不是"是不是 sanitizer 构建"——直接看产物比推断构建类型可靠。

把 21.3.1 的 --skipYarnInstall、21.3.2 的 workspace 重编、21.10 的 ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECS 门控串起来,是一条完整的降级链:

头文件 / 编译器不可用
  → runner 不装依赖,或 toolchainEnv 返回 null
    → 设 ELECTRON_SKIP_ELECTRON_HEADER_ADDON_SPECS=1
      → spec/node.spec.ts:687 的 ifit(...) 把对应用例 skip
        → CI 绿,但那部分 ABI 覆盖为零

这是"能力不足时显式跳过"的第三次出现(前两次是虚拟打印机、isTestingBindingAvailable)。它诚实,但也意味着CI 绿不能反推出原生 ABI 被验证过——要看日志里有没有 Rebuilding native addon ... against Electron's node headers。


21.14 环境替身:显示服务器、D-Bus 服务、日志通道

spec/CLAUDE.md 说的"机器独占性",还有另一半工作:给进程外的全局状态造一个可控替身。这三类替身全部在 Electron 启动之前由 shell / Python 铺好。

21.14.1 D-Bus:一次启动,包住整个 CLI

script/dbus_mock.py:22-29 只有 30 行:

def start():
    with sys.stdout if is_verbose_mode() else open(os.devnull, 'w', encoding='utf-8') as log:
        DBusTestCase.start_system_bus()
        DBusTestCase.spawn_server_template('logind', None, log)
        DBusTestCase.start_session_bus()
        DBusTestCase.spawn_server_template('notification_daemon', None, log)
        DBusTestCase.spawn_server_template(
            os.path.join(os.path.dirname(os.path.abspath(__file__)),
                         'dbusmock_xdg_file_chooser_portal.py'), None, log)

if __name__ == '__main__':
    start()
    try:
        subprocess.check_call(sys.argv[1:])
    finally:
        stop()

四条服务分在两条总线上:系统总线起 logind(powerMonitor 的休眠/锁屏事件、api-power-monitor.spec.ts),会话总线起 notification_daemon(api-notification-dbus.spec.ts)和一个仓库自己写的 XDG 文件选择 portal(xdg-helpers.ts 与 api-dialog.spec.ts 的 portal 分支)。

stop() 兼容两代 python-dbusmock API:有 stop_dbus 就分别按 system_bus_pid / session_bus_pid 停,否则退回 tearDownClass()。finally 保证即使 vitest 崩了总线也会被收掉。

21.2 里那行 commandArgs = [dbus_mock.py, command, ...commandArgs] 的意义现在清楚了:不是把 mock 起在 Electron 里,而是把 vitest CLI 整个包进 mock 进程的环境。这样 DBUS_SESSION_BUS_ADDRESS 等变量由 CLI 继承,再由 CLI spawn 的每一个 Electron worker 继承。spec/CLAUDE.md 里把 "talks to the mocked D-Bus services" 列进 serial 类别,正因为这些服务是所有 worker 共享的一份状态,不能并发戳。

21.14.2 显示服务器:Xvfb 与 weston 两条完全不同的路

# script/actions/run-tests.sh
set -euo pipefail
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x16 -ac &
XVFB_PID=$!
node "$@"

固定 :99、固定 1024x768x16。尺寸不是随便定的:窗口几何、屏幕坐标、capturePage 的像素尺寸等断言都依赖一个确定的虚拟屏。-ac 关掉访问控制。

Wayland 版(run-tests-wayland.sh:4-11)复杂得多:

export XDG_SESSION_TYPE=wayland
export WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-99}"
if [[ -z "${XDG_RUNTIME_DIR:-}" ]]; then
  XDG_RUNTIME_DIR="$(mktemp -d)"; chmod 700 "$XDG_RUNTIME_DIR"; export XDG_RUNTIME_DIR
  trap 'kill "$WESTON_PID" ...; rm -rf "$XDG_RUNTIME_DIR"' EXIT
fi
weston --backend=headless-backend.so --socket="$WAYLAND_DISPLAY" --idle-time=0 ... &
for _ in {1..100}; do
  if [[ -S "$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY" ]]; then break; fi
  sleep 0.1
done
node "$@" --ozone-platform=wayland

XDG_RUNTIME_DIR 权限必须是 0700(Wayland 协议要求),用自己的临时目录时还要在 trap 里连目录一起删。-S 检查 socket 文件是否出现,最多等 10 秒。--idle-time=0 防止合成器自己把屏保/空闲逻辑引进来。最后那个 --ozone-platform=wayland 会进入 process.argv,正是 21.10 isWayland 的第三个判据。

第 18 章讲过 Wayland 上 screen.getCursorScreenPoint() 恒返回 (0,0);script/wayland-test-allowlist.txt 只留 7 个文件,也是这条显示后端差异的直接后果。

21.14.3 日志与 sanitizer:CI 里三层不同的处理

CI 步骤按平台分叉:

场景处理
Windows--enable-logging=file --log-file=<spec/artifacts/electron_debug.log> + ELECTRON_ALSO_LOG_TO_STDERR=1
macOS / Linux 普通--enable-logging 直接进 stderr
ASan输出管道接 asan_symbolize.py --executable-path=.../electron,symbolize=1 必开
UBSanUBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1:external_symbolizer_path=...

Windows 那条的注释值得抄下来:

Child processes can't write to our stderr pipe on Windows, and with plain --enable-logging each one opens a console window that can cover the test windows. Log to a file (uploaded with the test artifacts) and mirror the main process to stderr.

"控制台窗口盖住测试窗口"会直接破坏所有依赖窗口焦点 / 屏幕捕获的 spec——这是日志配置影响测试结果的一个实例,不是单纯的排查便利。CI 里还有一个 Print minimized WSL terminals 步骤(always() 且 continue-on-error),是在超时后把 WSL 控制台日志打出来。

ASan 分支的注释解释了一个容易被当成迷信的配置:

symbolize=1 is required for leak suppressions to work: LSan can only match leak: entries against function and file names, and with symbolization off it has neither, which silently disables both Chromium's built-in list and lsan_suppressions.txt:10-23.

关掉符号化会让泄漏抑制规则静默失效,于是 CI 突然冒出一批与本次改动无关的泄漏失败。另外 G_SLICE=always-malloc、NSS_DISABLE_ARENA_FREE_LIST=1、NSS_DISABLE_UNLOAD=1 是为了让 glib/NSS 的池化分配不干扰 LSan。sanitizer 构建统一把 ELECTRON_SPEC_TIMEOUT 提到 180000(21.6.5 的默认 30 s 的 6 倍)。

Linux 还多一层权限准备:chown :builduser .. && chmod g+w ..、chmod 4755 ../out/Default/chrome-sandbox(setuid sandbox 必须这个模式)、runuser -u builduser -- git config --global --add safe.directory ...,然后所有测试命令都走 runuser -u builduser -- xvfb-run ...。测试不能以 root 跑,否则 Chromium sandbox 的行为与真实用户不同。

整个 job timeout-minutes: 60,超时或取消时还有一步截图(screenshot-timeout-<时间戳>.png)写进产物目录。

21.14.4 三类替身的共同点

替身造出来的全局状态谁消费独占方式
Xvfb / weston显示、屏幕几何、焦点所有窗口类 spec整个 job 一份;焦点类进 serial
dbus mock两条总线上的四个服务notification / power / dialog spec整个 run 一份;相关 suite 进 serial
日志文件 / printerOS 级设备与文件print()、断言输出每 worker 独立文件名 / 启动前预置

它们都不是"mock 一个 JS 模块",而是在进程外造一份真实的 OS 状态。这正是 21.0 那条判据的极端形式:当被测对象就是运行时本身,连"环境"都必须由测试基建亲自搭建。

21.15 L5:真实签名包、真实更新器、真实包注册

第 20 章末尾说过,fuses、autoUpdater、crashReporter 三块是测试里最难覆盖的。这一节把"怎么覆盖"补齐——答案是在测试里克隆一个真的 .app、签上真的证书、起真的更新服务器。

21.15.1 codesign-helpers.ts:克隆、改身份、签名、去符号

export const shouldRunCodesignTests =
  process.platform === 'darwin' && !process.mas && !features.isComponentBuild();

export function defaultAppBundlePath() {
  return path.resolve(process.execPath, '../../..');
}
function cloneTree(source, destParent) {
  let result = cp.spawnSync('cp', ['-cR', source, destParent]);   // APFS clone
  if (result.status !== 0) {
    cp.spawnSync('rm', ['-rf', dest]);
    result = cp.spawnSync('cp', ['-R', source, destParent]);       // 跨卷回退
  }
  return dest;
}

cp -cR 是 APFS 的 clone(写时复制,几乎瞬时);跨卷或不支持时回退到逐字节 cp -R。不这么做的话,每个 updater 用例都要复制几百 MB 的 Electron Framework。

copyMacOSFixtureApp() 在克隆出来的 bundle 上做四件事:

  1. 删掉 Contents/Resources/app,把 spec/fixtures/auto-update/<fixture>/ 拷进去(initial、update 等版本);
  2. 可选地给 fixture 的 package.json 的 name 加后缀 —— 因为 userData 路径由 app name 派生,不同 slot 必须不同;
  3. 往 Info.plist 注入 NSAppTransportSecurity,允许 localhost 的 HTTP 明文(更新服务器是本地 HTTP);用 <key>BuildMachineOSBuild</key> 作为插入锚点,并先检查 NSExceptionAllowsInsecureHTTPLoads 是否已存在(源码注释 "The source may be a template that already went through here once");
  4. 可选地正则替换 CFBundleIdentifier。

第 4 条是整套 harness 的关键:Squirrel 的 ShipIt launchd job 名、XPC 服务名、缓存目录全部由 CFBundleIdentifier 派生,两个并发更新的 app 用同一个 bundle id 会互相顶掉。

export function stripFrameworkSymbols(appPath: string) {
  const frameworksDir = path.resolve(appPath, 'Contents', 'Frameworks');
  for (const entry of fs.readdirSync(frameworksDir)) {
    if (!entry.endsWith(' Framework.framework')) continue;
    // strip -x <binary>
  }
}

注释点明动机:"Testing builds carry a full symbol table and every codesign/zip/ditto pass scales with it. Run before signing." 测试构建带全符号表,不 strip -x 的话每次 codesign / 打 zip / ditto 都要处理几倍的数据量。这是纯性能优化,但直接决定测试能否在 CI 超时内跑完。

21.15.2 autoupdater-darwin-helpers.ts:32-37:SlotPool 与七个时间常量

Squirrel.Mac 的 spec 被拆成两个文件(api-autoupdater-darwin.spec.ts、api-autoupdater-darwin-policy.spec.ts),注释直说目的:"split across files so that shards can run them in parallel on separate runners; this is the harness they share." 这直接呼应 21.9 的分片——两个文件各 418 / 379 秒,是全表最重的几个之一,必须能分到不同 shard。

并发度:

const CONCURRENCY = (() => {
  const fromEnv = parseInt(process.env.ELECTRON_SPEC_UPDATER_CONCURRENCY || '', 10);
  if (fromEnv > 0) return fromEnv;
  if (process.arch === 'x64') return 1;
  return os.availableParallelism() >= 8 ? 4 : 2;
})();

注释解释了为什么 Intel 机器上硬编码 1:"The Intel CI runners have three cores and each run saturates them, so running two at once there gained under a minute per file and made every run slower and less predictable. The parallelism comes from the files landing on different shards instead." 也就是文件级分片已经提供了并行度,文件内再并发只会互相抢核。这和 21.8.3 的 cpus/3 是同一套容量推理。

每个 slot 是一个四元组隔离单元:

type Slot = {
  index: number;
  bundleId: string;       // com.github.Electron.spec<N>
  shipItLabel: string;    // <bundleId>.ShipIt
  cacheDir: string;       // ~/Library/Caches/<bundleId>.ShipIt
  nameSuffix: string;     // -spec<N>,决定 userData
  zips: Record<string, string>;   // 每个 slot 各缓存自己 bundleId 的更新包
};

SlotPool 有三个不寻常的方法:

  • retire(slot):一个 run 无法被干净停止时,不再复用它的 bundle id / ShipIt job / 缓存目录,直接换新的,防止后面的 run 撞上残留状态;
  • acquireNow():重试时立刻给一个瞬态 slot(transient Set),不排队等空闲 slot。注释:"For a retry, which is the test the runner is blocked on; queueing it behind lookahead runs for tests that come later only adds their time to the failure."
  • 瞬态 slot 用完即弃,"so a retry never raises the concurrency for the rest of the file"。

时间预算:

常量值防的是
RUN_BUDGET_MULTIPLIER2 × testTimeout一个 run 从拿到 slot 起最多占多久(排队时间不计);ELECTRON_SPEC_UPDATER_RUN_BUDGET_MS 可覆盖以测 abort 路径
ABORT_GRACE_MS20 s被停掉的 run 自行收尾的时间
KILL_WAIT_MS5 s等被 SIGKILL 的进程组消失
CLEANUP_WAIT_MS5 s等更新目录变得可删(SIGKILL 的 app 可能还开着文件,ShipIt 是 launchd job、不受我们控制,按自己的节奏退出)

注释里那句 "ShipIt (a launchd job, not our child) exits on its own schedule" 是第 20 章 Squirrel.Mac 状态机在测试侧的投影:更新器进程不属于测试进程树,killGroup 也管不到它,只能靠 bundle id 隔离 + 等待。

21.15.3 msix-helpers.ts:证书、稀疏包、以及 hook 不重试

export const powershellSetupTimeout = 120_000;

注释把这个 120 秒的来历写得很具体:

Installing the test certificate and registering the sparse package run in the suite's beforeAll hook, and unregistering it in its afterAll hook, while other spec files keep the CI host busy. On windows-arm64 they regularly overrun 30s there, though they finish in time when the suite runs on its own, and vitest does not retry a failed hook.

21.11 讲过 retry: 3 只作用于 test,不作用于 hook;hook 失败直接让整个文件红,重跑也没用。所以这里的解法是把 hook 的超时从 30 s 抬到 120 s,而不是靠重试。

runPowerShell 把每个子进程都注册进 defer()(21.6.2),超时若仍在跑就 SIGKILL;installMsixCertificate() 跑 install_test_cert.ps1 把自签名证书装进 Trusted People store(不装就无法安装自签名 MSIX);registerExecutableWithIdentity() 把 ElectronDevAppxManifest.xml 拷到可执行文件旁,用 Add-AppxPackage -Register ... -ForceUpdateFromAnyVersion 注册稀疏包,让一个普通构建获得包身份(process.windowsStore 那条路径,见第 20 章 20.4)。

artifacts.ts 是这一层的产物出口,只有一行判断值得记:

const IS_CI = !!process.env.CI;
if (!IS_CI) return;   // createArtifact() 在本地什么都不写

本地跑测试不会生成 artifact,避免污染工作区;CI 里才写进 spec/artifacts/,随后被 test_artifacts_* 上传。

L5 的三套 helper 共同说明一件事:第 20 章那些"只能在真实安装包上验证"的行为,不是没测,而是被塞进了 L1 的 spec 里,用一堆门控和一堆 OS 级资源准备换来的。代价是它们只在 macOS 非 MAS 非 component build、Windows、以及有证书的环境里跑;其余构建下整片是 skip。

21.16 静态检查与文档即测试

npm run lint 是一个七段链:

lint = node ./script/lint.js && npm run lint:fmt && npm run lint:docs && npm run lint:chromium-roller

script/lint.js(621 行)按 key 分七类 linter:

key覆盖范围工具
cppshell/ 下 .cc / 非 mac 目录的 .hrun-clang-format.py + cpplint
objc.mm 与 /(mac|cocoa)/ 下的 .hclang-format + cpplint(多关掉 readability/braces)
pythonscript/ 下 .pypylint-2.17
javascriptlib/、spec/、script/ 等oxlint(CI 里 --format=github 直接出 PR 注解)
gn*.gn / *.gnign format + 自定义检查
patchespatches/补丁头格式与顺序
mddocs/、README 等markdownlint

CPPLINT_FILTERS 分两组,注释标明分别来自 Chromium presubmit_canned_checks.py 的 OFF_BY_DEFAULT_LINT_FILTERS 与 OFF_UNLESS_MANUALLY_ENABLED_LINT_FILTERS——也就是说 Electron 的 C++ lint 规则是对齐上游 presubmit 的,不是自己另立一套。IGNORELIST 只有三项(Windows resource.h、node_includes.h、fixture 里的 jQuery)。cpplint.py 把状态信息也写进 stderr,所以 cpplint() 要逐行过滤掉 Done processing ... 与 Total errors found: 0 才不刷屏。

lint:docs 是八条并列:

lint:js-in-markdown         (lint-roller-markdown-oxlint)
lint:fmt-in-markdown        (lint-roller-markdown-oxfmt)
create-typescript-definitions
lint:ts-check-js-in-markdown
lint:docs-fiddles           (oxlint docs/fiddles)
lint:docs-relative-links
lint:markdown
lint:api-history            (schema + breaking-changes + placement + strings)

其中 lint:ts-check-js-in-markdown 会把文档里的 JS 代码块拿去类型检查;lint:api-history 用 docs/api-history.schema.json 校验每个 API 的变更记录格式、出现位置与字符串,还要和 docs/breaking-changes.md 对得上。加上 21.3.3 那条 docs/api/*.md → electron-api.json → electron.d.ts → ts-smoke 的回路,改文档会触发类型生成失败,改 API 签名不改文档会触发 api-history 检查失败。文档在这里不是说明书,是编译输入。

其余:format 用 oxfmt、lint:clang-tidy 用 run-clang-tidy.mts、precommit 是 lint-staged + husky、prepack = check-for-leaks、lint:chromium-roller 检查 Chromium roll 相关的变更。script/doc-only-change.js 用 GitHub API 拉 PR 文件列表,若全部在 docs/ 下就以退出码 0 短路,配 pipeline-electron-docs-only.yml 跳过整条构建链——这是对"文档改动不需要编译"这一事实的工程化利用。

21.17 十五个"以为是这样"的点

#常见理解实际情况依据
1npm test 跑 spec/ 下所有 .ts只有 *.spec.ts(90 个);ambient.d.ts / pipe-transport.ts 不是测试;-spec.ts 会启动期硬报错vitest.config.ts:34-36 的 misnamed
2vitest worker 是 Node 子进程是真实 Electron 浏览器进程;pool 里强制 delete env.ELECTRON_RUN_AS_NODEelectron-pool.ts
3--electronVersion 能跑任意 runnerrunners Map 只有 main,传别的直接 exit(1)spec-runner.js:40-48
4自定义 scheme 随便什么时候注册全在 app.whenReady() 之前,14 个 scheme + 6 条 DNS 规则一次性装好spec/index.js(第 17 章 17.5)
5maxWorkers: 1 就能独占机器vitest 不等待上一个 worker 退出,必须靠 exclusive + liveWorkerselectron-pool.ts 注释
6带 serial 标签的文件只跑一次27 个文件同时进两个 project,起两次 Electron,耗时累加SpecTimingsReporter 注释
7tags: ['serial'] 靠 vitest 的 tag 系统分流配置阶段用正则读文件文本粗分,运行时才用 tagsFilter 细分;把 tag 写成变量会静默不跑serialTagPattern
8retry: 3 是唯一重试另有 runner 层 --enableRerun=3,读 JUnit XML 重新起进程逐条重跑21.11
9重跑会保留第一次的失败记录runner 先把 XML 复制成 .save,最后 rename 回来;日志被覆写rerunFailedTests
10CI 分片按文件数均分LPT 按每个 job 实测秒数装箱,权重表从 spec-timings.json 反推split-tests.js / gen-spec-weights.js
11CI 绿说明所有行为都测过分片 → allowlist → ifdescribe 三层过滤,外加 native header / codesign / testing binding 等门控21.9.6 / 21.10
12九个原生 addon 都要用 Electron 头文件重编只有 object-wrap 标了 electron:requiresElectronHeaders;其余 N-API ABI 稳定spec-runner.js:709-730 注释
13在 'data'/'exit' 监听器里 expect() 失败会正常报红抛在框架调用栈外,runner 无汇总、无 JUnit、整个 shard 红且无法重跑spec/CLAUDE.md
14虚拟打印机可以在测试里临时加macOS PrintCore 在进程启动时拍设备快照,必须在 Electron 起来前挂好setupVirtualPrinter 注释(第 19 章 19.1)
15electron.d.ts 是手写维护的从 docs/api/*.md 解析生成,文档改动会进 ts-smoke 编译检查create-api-json.mjs / lint:docs

还有三条不算误解但同样容易踩:--log-file 有 .rerun-N 与 .worker-N 两级后缀(Chromium 每次启动清空日志);global-setup.js:55 按可执行文件路径杀孤儿进程,所以故意对同一 build 起两个 invocation 必须设 ELECTRON_SPEC_KEEP_RUNNING_INSTANCES;SpecTimingsReporter 只在 CI 且没有 -t/--testNamePattern 时启用,否则一次过滤运行会覆盖全量耗时表。

21.18 小结:测试体系的复杂度,等于运行时边界的复杂度

把这一章收束成三条链和一个出口:

第一条链是进程链。 npm test → CLI 的宿主 Node → vitest CLI → 自定义 pool → electron spec/ --vitest-worker → index.js 的 ready 前配置 → worker.ts 把主进程交给测试框架。这条链上每一跳都在做身份切换,于是需要 WORKER_READY_MESSAGE 握手、需要自己写 IPC 编码器(因为两端 V8 不同)、需要在 hook 之间插 setImmediate()(因为 Chromium 消息泵和测试共用线程)、需要在 stop() 里杀整个进程组(因为 fixture app 会逃逸)。这些代码没有一行是"框架配置",全是把一个为 Node 设计的测试框架塞进 Electron 主进程所必须的适配。

第二条链是构建链。 docs/api/*.md → electron-api.json → electron.d.ts → ts-smoke;out/<outDir>/gen/node_headers → 原生 addon → object-wrap 重编;mksnapshot.zip → blob → snapshot-items-available fixture;gn-asar-hash / verify-chromedriver / check-patch-diff 直接对产物下手。测试在这里验证的不是"API 返回值是否正确",而是"这份二进制是不是我们以为的那份"。第 20 章那些编译期开关、fuse、构建身份,只能在这条链上被验证。

第三条链是机器链。 Xvfb / weston、两条 D-Bus 总线上的四个服务、一台虚拟打印机、代码签名证书、稀疏 MSIX 包、按 bundle id 隔离的 ShipIt slot。它们共同的特点是不属于任何进程,所以只能由测试基建在进程外造一份,并用 serial 标签、exclusive pool、cwd/权限/日志分身来避免并发踩踏。

一个出口是"能力不足时显式跳过"。 打印机挂不上、clang++ 跑不起来、没有证书、不是 testing build、Wayland 不给全局坐标——每一种都对应一个环境变量、一个 ifit()、一条 skip,而不是一个被改弱的断言或一次假装通过。这是整个体系最值得学的一点:它把"这次没测到什么"写进了代码和日志,让 CI 的绿色可以被正确解读。

回头看前二十章,几乎所有"文档里没有、只能从源码读出来"的行为,都能在这五层里找到对应的验证方式或对应的空白。第 17 章的 CORS 补丁有 14 个特权 scheme 组成的对照矩阵;第 18 章的菜单 role 表有专门的 spec;第 19 章的打印路径需要一台真打印机;第 20 章的 fuse 需要一个能被翻转字节的真实可执行文件。测试体系的形状,就是运行时边界的形状——理解了这一点,再看到 spec/vitest/ 里那段循环引用编码器,就不会觉得它是过度设计了。