Karma 接入 Travis CI 持续集成完全指南：从 .travis.yml 配置到 Firefox 无头浏览器测试

本文以 Karma 项目官方文档 docs/plus/02-travis.md 为主体，结合仓库源码与真实配置，系统讲解如何将 Karma 测试接入 Travis CI，实现代码推送后自动运行 JavaScript 单元测试，并在 Pull Request 与 CI 面板中展示测试结果。读完本文，你将掌握 .travis.yml 的最小可用配置、通过 npm test 驱动 Karma 的完整姿势、在 Travis 上运行真实 Firefox 浏览器的两种虚拟屏幕方案，以及 CI 环境下常见坑的规避方法。

一、Travis CI 与 Karma 的集成原理

Travis CI 是一种与 GitHub 仓库深度集成的持续集成服务：当代码被推送到仓库时，Travis 会自动拉取代码、安装依赖、执行你指定的测试命令。Karma 作为 JavaScript 测试运行器（本仓库 package.json 中的描述为 "Spectacular Test Runner for JavaScript."），正是 Travis 上跑前端单元测试的核心载体。

整个集成链路非常简单：

1. 在项目根目录新增一个 YAML 格式的 .travis.yml 文件，声明语言环境与 Node 版本；
2. 在 package.json 中提供 npm test 脚本，脚本内部调用 karma start 并传入 CI 所需参数；
3. 代码推送后，Travis 自动执行 npm install（安装包括 Karma 在内的全部依赖）与 npm test，测试结果回传 GitHub，显示在 Pull Request 与 Travis 控制面板中。

从 Karma 源码看，这一过程对应 lib/cli.js 中 karma start 命令的完整参数体系：--single-run（浏览器捕获完成后运行测试并退出）、--browsers（指定要启动的浏览器，如 --browsers Chrome,ChromeCanary,Firefox）、--reporters、--port、--log-level 等，全部可以在 CI 命令行中直接使用。

二、第一步：创建最小可用的 .travis.yml

在项目根目录创建 .travis.yml，写入如下内容：

language: node_js
node_js:
  - "4"

这告诉 Travis 两件事：

• language: node_js：使用 Node.js 构建环境；
• node_js 列表：指定要测试的 Node 版本，可以写多个版本让 Travis 并行跑多组构建。

需要说明的是，该配置示例取自仓库文档撰写时期的写法。从当前仓库 package.json 可以看到，Karma 自身要求的 Node 版本为 >= 10（当前仓库版本为 6.4.4），因此你在实际项目中应根据自己依赖的 Karma 版本与 Node 运行时选择 node_js 版本，而不是机械照抄旧版号。node_js 直接对应 Travis 提供的 Node 运行时，同时也会自动注入到构建环境的 PATH 中，供后续 npm 与 karma 命令使用。

三、第二步：通过 npm test 告诉 Travis 如何跑测试

如果项目根目录还没有 package.json，需要先创建。Travis 通过执行 npm test 来触发你的测试，因此 scripts.test 是 Travis 与 Karma 之间的"命令接口"。

最小配置如下：

{
  "devDependencies": {
    "karma": "~0.12"
  },
  "scripts": {
    "test": "karma start --single-run --browsers PhantomJS"
  }
}

3.1 依赖声明：Karma 必须出现在 devDependencies 中

Travis 在每次构建前都会自动执行 npm install，这是你声明 Karma 及其插件的地方。只要把 Karma 写进 devDependencies，Travis 就能在安装阶段自动拉取——这也是官方文档强调"specify any modules your app needs that Travis does not know about like Karma"的原因。

3.2 命令行参数逐个拆解

--single-run 与 --browsers 是 CI 场景下的关键参数：

• --single-run：Karma 捕获到指定浏览器后执行一轮测试，随后退出进程。在 lib/cli.js 中，CLI 层会把字符串参数规范化为布尔值（'true' 之外的任何字符串都会被当作 false）；而在 lib/config.js 中，配置层还有一条联动规则：singleRun 为 true 时 autoWatch 会被强制关闭，这正是 CI 需要的"跑完就退出"行为，避免测试进程常驻导致 Travis 构建挂起。
• --browsers PhantomJS：指定本次运行使用哪个浏览器启动器。Karma 通过 lib/launchers/base.js 中定义的启动器状态机（BEING_CAPTURED → CAPTURED → FINISHED）来管理浏览器进程生命周期，CI 构建的成败直接取决于浏览器能否在 captureTimeout（默认 60000ms，见 lib/config.js）内完成捕获。

3.3 配置文件的默认加载顺序

即使不显式传配置文件，Karma 也会自动探测项目根目录下的 karma.conf.js、karma.conf.coffee、karma.conf.ts 或 .config/ 子目录下的同名文件（见 lib/cli.js）。CI 场景中通常会保留一份 karma.conf.js，把 singleRun: true 等设置直接写进配置文件，命令行只需 karma start。

四、第三步：在 Travis 上运行真实浏览器（Firefox + 虚拟屏幕）

CI 服务器没有物理显示器，但 Travis 支持通过 Xvfb（X Virtual Framebuffer）为真实浏览器提供虚拟屏幕。官方文档给出了两种方案，按 Travis 构建环境的镜像版本区分。

4.1 方案 A：Xenial 及更新镜像——使用 services 声明 xvfb

language: node_js
node_js:
  - "4"
dist: xenial
services:
  - xvfb

在较新的 Travis 镜像中，Xvfb 已被封装成系统服务，只需在 services 中声明 xvfb 即可，无需手写启动脚本。

4.2 方案 B：Trusty 及更旧镜像——手动启动 Xvfb

language: node_js
node_js:
  - "4"
before_script:
  - export DISPLAY=:99.0
  - sh -e /etc/init.d/xvfb start

before_script 阶段在安装依赖之后、执行测试命令之前运行：export DISPLAY=:99.0 把虚拟屏幕的显示号告诉 Firefox，sh -e /etc/init.d/xvfb start 则启动 Xvfb 守护进程。注意 sh -e 会在启动失败时立即中止构建，避免后续测试在一个不可用的显示环境中空跑。

4.3 切换测试命令到 Firefox

虚拟屏幕就绪后，把 npm test 命令改为：

karma start --browsers Firefox --single-run

至此，Travis 会在虚拟屏幕上拉起真实 Firefox，执行 Karma 测试后退出，构建结果随 GitHub 集成展示在 Pull Request 上。

五、实战印证：Karma 仓库自身的 CI 配置思路

虽然当前仓库已迁移到 GitHub Actions（仓库根目录未再保留 .travis.yml），但 test/client/karma.conf.js 完整保留了 CI 环境的配置范式，可作为你编排 CI 配置的直接参考：

• reporter 选择：注释明确写着 "use dots reporter, as travis terminal does not support escaping sequences"，CI 环境采用 reporters: ['dots'] 而不是默认的 progress，避免颜色转义序列在 CI 日志中产生乱码；
• singleRun 与 autoWatch：配置 singleRun: true、autoWatch: false，正是"跑完即退"的 CI 模式，与 lib/config.js 中的强制联动逻辑一致；
• 无头浏览器兜底：browsers: useBrowserStack ? Object.keys(launchers) : ['ChromeHeadless']，本地/CI 默认用 ChromeHeadless，配置了 BrowserStack 凭证时才切换云真机——这是"无显示器环境优先无头浏览器"的通用思路；
• JUnit 报告预留：配置中保留 junitReporter: { outputFile: 'test-results.xml' }，为 Jenkins 等平台消费统一格式的测试报告做准备（参见 docs/plus/03-jenkins.md）。

此外，docs/config/01-configuration-file.md 中关于 browserNoActivityTimeout 的说明也提到，该选项默认值即参考了 Travis 官方对 Karma + Firefox 的建议，可见 Karma 在设计上就充分考虑了 CI 场景下的浏览器无响应问题。

六、注意事项与常见坑

官方文档在末尾给出了三条 CI 环境下的关键经验，值得逐条落实：

1. 依赖清单必须完整：Travis 的 Node 环境非常精简。如果启动过程报"找不到模块"（module not found），首先检查对应模块是否已写入 package.json 的 dependencies 或 devDependencies。Travis 不会替你补装任何未知依赖，只有 npm install 能拉到的东西才是可用的。
2. 外部资源必须打桩：Travis 运行在云端，不在你的本地网络内。任何试图连接本地服务、内网资源或外部 API 的测试代码，都应该用 Nock 之类的库在 HTTP 层打桩（stub），否则测试必然失败。这一点在 Karma 的 e2e 测试体系里也有印证：仓库 test/e2e/support/proxy 与 test/e2e/upstream-proxy.feature 专门覆盖了代理场景，说明 CI/网络受限环境下如何处理请求依赖是官方持续关注的问题。
3. 充分利用 Travis 生命周期钩子：.travis.yml 还支持更多选项，例如在 before_install、install、before_script 阶段插入自定义脚本。官方对 GUI/无头浏览器（GUI apps）场景有专门的配置指南，before_script 启动 Xvfb 就是其中的典型用法。

七、总结

把 Karma 接入 Travis CI 只需要三步：写好 .travis.yml 声明 Node 环境、把 karma start --single-run 挂到 npm test、视镜像版本用 services: xvfb 或 before_script 脚本搭建 Firefox 虚拟屏幕。深入源码可以看到，singleRun 与 autoWatch 的联动、browsers 参数的解析、启动器的状态机设计，都是为"CI 上跑完一轮就干净退出"这一目标服务的。参考 test/client/karma.conf.js 的既有范式（dots reporter、ChromeHeadless 兜底、JUnit 报告预留），可以少踩很多 CI 环境的坑。