用真实外部仓库验证 Cypress 新构建产物：`test-binary-against-repo` 作业与二进制系统测试解析

Cypress 仓库（cypress 项目本身）在每次 CI 中构建出全新的 Cypress 二进制与 npm 包之后，不会只跑自家的单测，还会克隆一批真实世界的示例仓库，用刚构建好的 Cypress 去运行它们的测试，以此验证新版本在"外部项目"里的真实兼容性与端到端体验。本文基于仓库内的 guides/testing-other-projects.md 及其对应的 CI 流水线源码，完整拆解这套"用外部项目反哺测试"的验证体系：包括 test-binary-against-repo 本地 CI 作业、Remote CI 策略，以及针对已构建 App 的 binary-system-tests 二进制系统测试。读完你将掌握 Cypress 如何在发布前用真实仓库做回归验证、其版本对齐与产物安装机制，以及如何在本地复现或扩展这一类"测试测试工具本身"的实践。

为什么要在"其他项目"上测试 Cypress 自身

Cypress 是"用于测试的软件"，而它自身的质量又依赖大量测试来保障。常规的单元测试、组件测试只能验证内部实现，无法回答一个最实际的问题：当外部用户在自己的真实项目里 npm install 一个全新构建的 Cypress，并执行 cypress run 时，体验是否一切正常？

为此，仓库在 CI 中设计了一条"产物验证"链路（见 guides/testing-other-projects.md）：

1. 在 develop 分支（以及 CircleCI 配置 中约定的其他分支）上，先构建出完整的 Cypress 二进制和 npm 包；
2. 将构建产物上传到 cdn.cypress.io；
3. 随后用一批真实世界的示例仓库（kitchensink、recipes、real-world app 等）作为被测对象，分别运行测试，验证这批刚出炉的产物。

从仓库当前目录结构看，CircleCI 配置采用"动态 workflow 打包"体系：.circleci/config.yml 是入口，真正承载 test-binary-against-repo、clone-repo-and-checkout-branch、run-binary-system-tests 等命令与作业定义的是其源码目录 .circleci/src/pipeline/@pipeline.yml，.circleci/README.md 对此做了说明。

文档明确归纳出两种并行的外部项目验证策略：

1. test-binary-against-repo 作业（在 cypress 自己的 CI 管道中克隆外部仓库并跑测试）；
2. Remote CI（由外部仓库侧的 CI 承接验证）。

其中，可以在当前仓库源码中完整追踪到实现细节的是第一种。

策略一：test-binary-against-repo 本地 CI 作业

作业的运行模式

一批 CI 作业位于 cypress 的 CircleCI 流水线中，它们克隆示例测试项目，并作为 cypress-io/cypress 自身 CI 管道的一部分去运行测试。要列出当前有哪些测试项目采用了这种方式，可直接在 .circleci/src/pipeline/@pipeline.yml 中搜索对 test-binary-against-repo 这一可复用 step/命令的引用。

该 step 的核心工作，源码注释写得很清楚：

Takes the built binary and NPM package, clones given example repo and runs the new version of Cypress against it.

即：拿已构建的二进制 + npm 包，克隆指定示例仓库，然后用"新版本的 Cypress"去运行它的测试。 每个作业的基本执行链如下（节选自 test-binary-against-repo 定义 及其配套命令）：

1. 调用 clone-repo-and-checkout-branch 克隆示例仓库并切换到与当前版本匹配的分支；
2. 用指向本次构建产物的方式强制安装 Cypress；
3. 按需构建被测项目、启动其开发服务器；
4. 执行项目内的 Cypress 测试命令，并观察是否通过。

产物安装：如何让外部仓库"用上"刚构建的 Cypress

test-binary-against-repo 与 test-binary-against-staging、test-binary-against-rwa 等作业共同依赖 restore_workspace_binaries 将 CI workspace 中的构建产物（cypress.zip 与 cypress.tgz）恢复出来，随后强制安装本地产物而非去 npm registry 拉取发布版。典型命令如下（见 test-binary-against-staging 作业）：

CYPRESS_INSTALL_BINARY=~/cypress/cypress.zip npm i --legacy-peer-deps ~/cypress/cypress.tgz

其中：

• cypress.tgz 是刚打包出的 npm 包本体，通过 npm i <tgz路径> 直接安装；
• CYPRESS_INSTALL_BINARY 指向本机已构建的 cypress.zip，用于让 Cypress 安装后跳过下载、直接使用这份"新鲜出炉"的二进制（源码注释称之为 "force installing the freshly built binary"）。

在 test-binary-against-rwa 作业中，clone 完 cypress-realworld-app 后执行的则是 CYPRESS_INSTALL_BINARY=~/cypress/cypress.zip npm i --legacy-peer-deps ~/cypress/cypress.tgz && [[ -f yarn.lock ]] && yarn，即先装 Cypress 产物、再按项目锁文件补齐其余依赖。

版本对齐：检出与"下一版本号"同名的分支

这一步是整个机制里最巧妙的设计。它回答了一个问题：示例仓库如何知道该配合哪个尚未发布的 Cypress 版本？ 答案是"看版本号分支"。

在本地 CI 与 Remote CI 的测试项目中，都会尝试在测试项目自身的 git 仓库里，检出以 next version（下一版本号，形如 X.Y.Z）命名的分支（如果该分支存在的话）。实现位于 clone-repo-and-checkout-branch 命令（见 @pipeline.yml）：

git clone --depth 1 --no-single-branch https://github.com/cypress-io/<repo>.git .

# 计算下一个版本号
NEXT_VERSION=$(node ./cypress/scripts/get-next-version.js)

# 优先检出 release/<version> 分支（当前约定），
# 回退到裸 <version> 分支以兼容老版本约定，都不存在则留在默认分支
git checkout "release/$NEXT_VERSION" || git checkout "$NEXT_VERSION" || true

也就是说：假设 Cypress 即将发布的下一版本是 14.5.0，示例仓库里维护者们会提前准备好一个名为 release/14.5.0 的分支，把针对新版 Cypress 的适配（新 API、新配置）提交上去。Cypress 的 CI 在验证时克隆该仓库并自动检出这个分支，于是测试双方就"对齐"到了同一版本。若 NEXT_VERSION 需要被临时覆盖，可设置环境变量 NEXT_VERSION=1.2.3（详见 guides/next-version.md）。

此外，该命令还支持通过 pull_request_id 参数检出外部仓库的某个 PR（git fetch origin pull/<id>/head:pr-<id>），从而允许在示例仓库的未合并 PR 上提前验证新功能——这正是下文注释掉的 test-binary-against-recipe-pull-request 作业想做的事情。

可复用 step 的参数清单

以 .circleci/src/pipeline/@pipeline.yml 中的命令定义为准，test-binary-against-repo 支持以下关键参数：

参数	类型/默认值	说明
repo	string，必填	要克隆的 GitHub 仓库名，例如 cypress-example-kitchensink
browser	enum ["", "electron", "chrome", "firefox"]，默认 ""	运行测试时使用的浏览器
command	string，默认 npm run e2e	在克隆项目内启动 Cypress 测试的命令
build-project	boolean，默认 true	是否先执行被测项目的构建脚本
folder	string，默认 ""	被测仓库是 monorepo 时，指定在其中运行测试的子目录
pull_request_id	integer，默认 0	是否检出外部仓库的指定 PR 后再安装与测试
wait-on	string，默认 ""	是否使用 wait-on 等待开发服务器就绪
server-start-command	string，默认 npm start --if-present	被测项目的服务器启动命令
executor	executor，默认 cy-docker	该作业使用的执行器（Windows 等场景可覆盖）

可复用 command 的通用执行流程是：安装 yarn → clone-repo-and-checkout-branch 克隆并切分支 → 依据被测仓库的 .node-version 等环境安装对应 Node → 构建项目 → 以 background: true 方式启动服务器 → 在指定 folder（或仓库根）下执行 command（当传了 browser 时追加 --browser <browser> --record false）。

真实存在的"用外部仓库验证"作业

在流水线中搜索 step 引用即可看到以下现役作业（@pipeline.yml）：

• test-binary-against-recipes / -chrome / -firefox：克隆 cypress-example-recipes 仓库，分别用 electron（parallelism: 4，跨 4 台机器按 --chunk/--total-chunks 切分 spec）、chrome、firefox 运行 npm run test:ci；
• test-binary-against-kitchensink / -firefox / -chrome：克隆 cypress-example-kitchensink 仓库，用 electron/firefox/chrome 运行其 e2e 测试，其中 electron 版前置了 maybe_skip_binary_jobs（无 CIRCLE_TOKEN 的外部 PR 会直接跳过，避免未经授权触发二进制构建）；
• test-binary-against-staging：克隆极简项目 cypress-test-tiny，安装产物后设置 CYPRESS_INTERNAL_ENV=staging、带上 CYPRESS_PROJECT_ID/CYPRESS_RECORD_KEY 向 staging API 执行 cypress run --record，验证产物与真实 Cloud/API 的集成；
• test-binary-against-rwa：克隆 cypress-realworld-app（真实世界示例应用），默认用 CI=true yarn start 拉起后端 + Vite 开发服务器，再执行 CYPRESS_RECORD_KEY=$MAIN_RECORD_KEY CYPRESS_PROJECT_ID=ypt4pf yarn cypress:run 运行全套测试，并提供 --browser 与 pull_request_id 扩展能力；
• test-binary-against-recipe-pull-request：处于注释状态的"特殊作业"，用于让新功能在 cypress-example-recipes 的某个 PR（如 pull_request_id: 515、folder: examples/fundamentals__typescript）上提前试跑。

本地 CI 策略的核心优势

文档明确指出本地 CI 相对 Remote CI 的一个重要优势：

One advantage to local CI is that it does not require creating commits to another repo.

也就是说，验证动作全部发生在 cypress 仓库自己的流水线内——克隆、切分支、装产物、跑测试都在本次 CI 的临时目录中完成，无需向任何外部仓库提交 commit 或触发分支推送。这既降低了对外部仓库的侵入，也让"构建即验证"的闭环天然地随主流水线一起触发。

策略二：Remote CI（远程 CI）概述

文档将 Remote CI 列为与 test-binary-against-repo 并列的第二种策略。关于它，文档仅给出两点可确认的说明：

• 与本地 CI 的测试项目相似，Remote CI 中的测试项目也会尝试在测试项目自身的 git 仓库里检出以 next version（X.Y.Z）命名的分支；
• 与本地 CI 相比，Remote CI 需要在外部仓库一侧做额外的分支/提交准备。

也就是说，Remote CI 把"用新版本 Cypress 跑外部项目"这件事迁移到外部项目自己的 CI 环境里执行，从而能在更贴近真实用户的环境中暴露问题；代价正是文档所暗示的——需要在别的仓库里维护版本分支甚至创建提交。由于当前仓库的可追踪实现集中在本地 CI 一侧，读者若要了解 Remote CI 的具体编排，需要结合 .circleci 流水线中对 workflow 的调度以及外部示例仓库的 CI 约定来判断，本文不做超出仓库证据的展开。

针对已构建 App 的 binary-system-tests 二进制系统测试

它和普通 system-tests 的区别

仓库中 system-tests/README.md 对二者做了清晰区分：

• system-tests/test 目录下的 spec 直接跑在未构建的 Cypress App 上，追求 CI 中的速度（无需等完整构建）；
• system-tests/test-binary 目录下的 spec 跑在已构建的 Cypress App 上：每个测试都运行在独立的 Docker 容器中，以"空白环境"供 Cypress 运行；每个测试前会用 npm install 安装正式版 CLI 与已构建的 cypress.zip，并调用真实的 cypress run 命令来执行测试。

其设计目标是："在这些测试里运行项目，与在 CI 中运行真实的、面向生产的 Cypress Docker 环境，二者之间不应存在功能差异。" 正因为如此，它特别适合验证常规 system-tests 无法覆盖的场景，例如：不同 Node 版本下的运行、有/无 Xvfb（虚拟显示器）、以及不同操作系统版本（详见 system-tests/README.md 中 "Developing Docker-based tests against built binary" 一节）。

仓库内实际的二进制系统测试

当前仓库的 system-tests/test-binary 目录下包含以下 spec 文件：

• ci_environments_spec.ts
• module_api_spec.ts
• node_versions_node22_spec.ts
• node_versions_node24plus_spec.ts
• typescript_7_spec.ts

这些文件从命名上即可看出其覆盖目标：Node 22 / Node 24+ 等不同 Node 版本、TypeScript 版本兼容、模块 API、以及不同 CI 环境变量下的行为——正是"常规系统测试很难测、Docker 空白环境才方便测"的典型场景。

对应的 CI 作业

在 CI 中，这些测试通过 run-binary-system-tests 命令执行（见 @pipeline.yml）：

# 恢复缓存的工作区与 system-tests 依赖后：
ALL_SPECS=`circleci tests glob "$HOME/cypress/system-tests/test-binary/*spec*"`
SPECS=`echo $ALL_SPECS | xargs -n 1 | circleci tests split --split-by=timings`
yarn workspace @tooling/system-tests test:ci $SPECS

它通过 circleci tests glob 收集所有 *spec* 文件，再按历史耗时（--split-by=timings）在机器间切分，最终交给 @tooling/system-tests 这个 workspace 的 test:ci 脚本运行。这些测试运行在名为 binary-system-tests 的 CI 作业族中。

如何编写一个二进制系统测试

按 system-tests/README.md 给出的模板，编写针对已构建二进制的系统测试只需在 systemTests.it 中组合 dockerImage 与 withBinary 两个选项：

// ./test-binary/node-versions.spec.ts
import systemTests from '../lib/system-tests'
import Fixtures from '../lib/fixtures'

describe('node versions', () => {
    systemTests.it('runs in node 12', {
        dockerImage: 'cypress:node/12',
        project: 'todos',
        withBinary: true,
    })
})

运行 yarn test node-versions 时，helper 会启动对应的 Docker 容器（如 cypress:node/12），在容器内从 ../cypress.zip 和 ../cli/build 安装 Cypress，再调用真实的 cypress run 命令完成测试。systemTests.it 的其它选项（如 onRun、expectedExitCode）在该场景下依然生效。如果你打算在仓库内复现这套验证，还可以像 system-tests/README.md 描述的那样，用 --no-exit 保持浏览器不退出以便调试，或用 --cypress-inspect-brk 调试被测的 Cypress 进程。

底层支撑：next version 的计算逻辑

"检出 release/X.Y.Z 分支"依赖的 X.Y.Z 由 scripts/get-next-version.js 计算得出。guides/next-version.md 给出了完整规则：

1. 若设置了环境变量 NEXT_VERSION，直接输出该值并退出（常用于 release 分支或强制指定某个大版本）；
2. 否则，基于当前分支自上次发布以来的提交（semantic commit 消息）分析并计算出下一个版本号。其中：
   • 只有改动 packages/* 或 cli/* 下文件的提交才会被计入——这样对 npm/ 各包的提交不会无谓地抬升 CLI 与二进制的版本；
   • 提交消息遵循 angular commit 风格：fix: 前缀触发 patch 版本升级，feat: 前缀触发 minor 版本升级，带 BREAKING CHANGE: footer 的提交触发 major 版本升级。

想本地调试该逻辑，可以直接运行 node ./scripts/get-next-version.js，它会分析当前分支上的提交并打印计算出的版本号（详见 guides/next-version.md）。

小结：一套"发布前用真实项目做验收"的可复用方案

把三个环节串联起来，就能看清 Cypress 的完整质量闭环：

环节	位置	验证对象	关键机制
构建与上传	CI 构建作业	产物可构建、可发布	上传 cdn.cypress.io
test-binary-against-repo 作业	.circleci 流水线	新产物在真实示例仓库的兼容性	克隆仓库 + 检出 release/X.Y.Z 分支 + 强制安装本地 cypress.zip/cypress.tgz
Remote CI	外部项目 CI	更贴近真实用户环境	由外部仓库执行验证
binary-system-tests	system-tests/test-binary	已构建 App 在空白 Docker 环境的行为	withBinary + dockerImage + 真实 cypress run

这套实践最大的价值在于：Cypress 从不把"自家测试通过"当作发布依据，而是每次构建后都让真实世界的 kitchensink、recipes、real-world-app 等仓库用新产物完整跑一遍，再配合在独立 Docker 环境中的二进制系统测试，从"真实项目兼容性"与"生产环境行为"两个维度为发布把关。

如果你希望在仓库中继续深入，建议按顺序阅读以下材料：文档正文 guides/testing-other-projects.md、CI 命令与作业实现 .circleci/src/pipeline/@pipeline.yml、版本号计算 scripts/get-next-version.js 与 guides/next-version.md、以及二进制系统测试说明 system-tests/README.md。