TestCafe本地运行e2e测试间歇性挂起、浏览器断连问题求助

这类半概率触发、进入错误状态后持续复现、重启IDE可临时恢复的故障，根因基本逃不过三类：残留进程占用端口、浏览器配置锁残留、被测服务启动竞态，按以下顺序排查即可定位解决：

端口残留排查 #

TestCafe运行时会启动本地代理服务完成脚本注入和请求拦截，异常终止测试（强制中断任务、Ctrl+C未等进程完全退出）时，代理进程会残留在后台占用默认端口，后续启动的TestCafe实例不会主动抛出端口占用错误，会直接卡在代理注入环节，表现为一直停在TestCafe加载页、等待超时后报浏览器断连。

• 每次运行测试前先执行进程清理，杀掉残留的TestCafe、Chrome进程以及被占用的默认代理端口：

# macOS环境执行
lsof -ti:1337,1338 | xargs kill -9 2>/dev/null
pkill -f "testcafe" 2>/dev/null
pkill -f "Google Chrome" 2>/dev/null

1337、1338为TestCafe默认代理端口，若自定义过代理端口可替换为对应值。

• 可在TestCafe配置文件中显式指定固定端口范围，避免随机端口被本地其他服务（IDE插件、本地开发服务）抢占。

Chrome配置锁残留排查 #

TestCafe启动Chrome时默认创建临时用户目录，异常退出时临时目录下的SingletonLock锁文件不会被自动清理，后续启动的Chrome实例读取到锁文件会卡在用户配置加载环节，无法完成TestCafe脚本注入。

• 运行测试时给Chrome传入启动参数，指定固定的测试专用用户目录，禁用默认的首次运行引导和配置锁检查：

// .testcaferc.js 配置
module.exports = {
  browsers: [{
    path: 'chrome',
    arguments: ['--no-first-run', '--no-default-browser-check', '--user-data-dir=./.testcafe-chrome-profile', '--disable-translate']
  }]
}

• 在测试启动脚本中加入预清理逻辑，每次启动前删除专用用户目录下的锁文件：

rm -rf ./.testcafe-chrome-profile/SingletonLock

启动竞态排查 #

从仓库结构看，integration-tests目录执行测试时需要先启动本地客户端、API服务，再启动TestCafe执行用例。如果启动脚本中并行拉起被测服务和TestCafe，没有等待服务完全就绪就发起页面访问，TestCafe代理会持续收到未就绪的响应，卡在页面加载环节；这类异常会因为残留的半开连接持续触发，直到重启IDE清理掉所有子进程才恢复。

• 不要用并行命令同时启动被测服务和TestCafe，改用端口检测逻辑等待服务完全返回正常响应后，再启动TestCafe。可以借助wait-on工具实现：

# 后台拉起被测服务
yarn start:client &
yarn start:api &
# 等待对应服务端口就绪后再执行测试
wait-on http://localhost:3000 http://localhost:4000 && yarn testcafe chrome ./tests

• 调整TestCafe超时配置，避免服务冷启动较慢时直接触发断连错误：

{
  "pageLoadTimeout": 30000,
  "ajaxRequestTimeout": 15000
}

故障定位辅助手段 #

复现挂起问题时不需要直接终止进程，可通过以下操作快速定位根因：

• 执行lsof -i -P | grep LISTEN查看TestCafe默认代理端口是否被残留进程占用
• 打开Chrome任务管理器，检查TestCafe注入脚本页面是否处于无响应状态
• 直接访问TestCafe默认代理地址http://localhost:1337，如果无法正常打开说明代理进程启动异常

内容的提问来源于stack exchange，提问作者c.m.olson