如何在Docker容器中调试Chrome Headless模式下的Angular测试

一、基础配置改造（打通容器内调试链路） #

• Karma配置调整：打开项目根目录下的karma.conf.js，不要修改原有供CI使用的ChromeHeadless配置，单独新增一个供调试使用的自定义启动器，配置如下：

module.exports = function (config) {
  config.set({
    // 其他原有配置保持不变
    customLaunchers: {
      ChromeHeadlessDebug: {
        base: 'ChromeHeadless',
        flags: [
          '--no-sandbox', // 容器环境下必须关闭沙箱，否则Chrome无法启动
          '--disable-gpu',
          '--remote-debugging-address=0.0.0.0', // 允许外部IP访问调试端口，默认仅绑定127.0.0.1
          '--remote-debugging-port=9222', // 指定调试端口
          '--disable-dev-shm-usage' // 解决容器共享内存不足导致Chrome崩溃的问题
        ]
      }
    },
    singleRun: false, // *必须设为false，测试跑完后Chrome进程不会自动退出
    autoWatch: true,
    restartOnFileChange: true
  })
}

注意这个调试专用的启动器仅用于本地排查问题，不要放到CI流水线配置里，否则测试跑完不会自动退出，会导致流水线任务挂起

• Docker容器端口映射：启动承载测试的容器时，必须把Chrome调试端口映射到宿主机，docker run命令追加参数-p 9222:9222即可；如果用docker-compose编排，在服务的ports配置段新增- "9222:9222"，确保宿主机可以直接访问容器内的9222端口。
• 启动测试服务：容器内执行Angular测试启动命令，指定使用刚才配置的调试版启动器：ng test --browsers ChromeHeadlessDebug --watch=true，等控制台输出Chrome启动成功的日志后，调试端口就已经正常监听了。

二、断点调试实操步骤 #

• 连接调试面板：在宿主机打开桌面版Chrome浏览器，地址栏输入http://localhost:9222，即可看到容器内Chrome Headless实例上打开的所有页面，点击标题带「Karma DEBUG RUNNER」字样的页面入口，就能打开和本地前端调试完全一致的DevTools调试面板。
• 断点设置两种方式：
  • 源码断点：在DevTools的Sources面板，找到webpack://路径下对应的*.spec.ts测试源码（Angular默认开sourcemap，直接搜文件名就能定位），点击行号即可打断点，刷新调试页面后，测试执行到断点位置就会自动暂停，可以查看当前作用域的变量值、调用栈。
  • 硬断点：直接在测试代码的目标位置写debugger;语句，只要调试面板处于打开状态，执行到该语句就会自动断住，适合快速定位逻辑位置。
• Jasmine效率调试技巧：
  • 单个用例调试时，把目标it()块改成fit()，测试运行器只会执行这一个用例，跳过其他所有用例，大幅减少等待时间；如果要暂时跳过某部分无关用例，把对应的describe()/it()改成xdescribe()/xit()即可。
  • 调试时间相关的异步用例，可以在断点状态下直接在控制台调用jasmine.clock()API操作虚拟时钟，不用等真实时间流逝。

三、常见问题排查 #

• 宿主机无法访问9222端口：先进入容器内部执行curl http://localhost:9222/json/version，如果命令无返回，检查Chrome启动参数里有没有加--remote-debugging-address=0.0.0.0，默认配置下Headless Chrome仅允许容器内部本地访问调试端口；如果容器内可以正常访问，检查端口映射配置是否正确、宿主机防火墙是否拦截9222端口。
• 断点不命中：检查angular.json里test配置项的sourceMap是否开启，如果sourceMap被关闭，DevTools无法映射ts源码到打包后的js，断点自然无法命中；另外要关闭测试环境的代码压缩配置，避免代码位置偏移导致断点错位。
• 测试执行过程中Chrome闪退：大概率是容器共享内存不足，要么加上--disable-dev-shm-usage启动参数，要么启动容器时加--shm-size=2g分配更大的共享内存空间。

四、高质量Angular测试编写参考 #

• 调试过程中重点排查三类高频问题：
  • 异步逻辑未等待完成就执行断言：比如HttpClient请求未返回、订阅未取到值、定时器/动画未执行完成就开始判断结果，断住后先看当前变量实际值再调整断言时机，尽量用fixture.whenStable()、fakeAsync/tick()组合控制异步时序，不要写固定等待时间的sleep()逻辑，避免测试偶发失败。
  • 测试上下文污染：比如全局服务的状态、DOM元素在每个用例执行完没有重置，导致单个用例单独跑能通过、全量批量跑就失败，调试时注意观察每个用例执行前的初始状态是否符合预期，必要时在afterEach()块里加重置逻辑。
  • 变更检测未触发：Angular组件测试中，修改了组件属性后没有调用fixture.detectChanges()触发视图更新，就直接断言DOM内容，断住后直接看Elements面板里的实际DOM结构就能快速定位。
• 调试通过的用例要保证断言的确定性，不要写模糊的存在性判断，要明确断言值、状态、交互结果是否符合预期，不要为了覆盖行数写无意义的测试。

内容的提问来源于stack exchange，提问作者Vegeta