如何让RSpec在CircleCI环境中成功连接到Chromedriver？

我之前在CircleCI上跑Rails的RSpec系统测试时，也碰到过完全一样的Selenium::WebDriver::Error::WebDriverError: unable to connect to chromedriver 127.0.0.1:9515错误——明明已经通过官方Orb装了Chrome和Chromedriver，本地运行毫无问题，就是CI上死活连不上。下面是我亲测有效的几个排查和解决步骤：

1. 先确认Chrome和Chromedriver版本完全匹配 #

CircleCI的Chrome Orb有时候会默认安装最新版Chrome，但如果你的项目里通过webdrivers gem或者手动方式锁定了特定版本的Chromedriver，就会出现版本不兼容的情况，直接导致连接失败。

• 登录CircleCI的SSH执行google-chrome --version和chromedriver --version，看两者的主版本号是否一致（比如都是118.x）。
• 如果版本不匹配，要么在CircleCI配置里指定和本地一致的Chrome版本，要么更新项目里的webdrivers gem，让它自动适配CI上的Chrome版本。

2. 检查Chrome是否用了正确的无头模式参数 #

CircleCI没有图形界面，必须让Chrome以无头模式启动，而且还要加上几个CI环境必需的参数。确保你的RSpec配置里有这些设置：

# spec/spec_helper.rb 或 spec/system_helper.rb
Capybara.register_driver :chrome do |app|
  options = Selenium::WebDriver::Chrome::Options.new
  options.add_argument('--headless=new') # 注意是new参数，旧的--headless已经被弃用
  options.add_argument('--no-sandbox') # CircleCI需要绕过安全限制，这个参数不能少
  options.add_argument('--disable-dev-shm-usage') # 解决CI上共享内存不足的问题
  options.add_argument('--window-size=1400,1400')

  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
end

Capybara.javascript_driver = :chrome

我之前就是漏了--no-sandbox参数，导致Chrome根本启动不起来，自然连不上Chromedriver。

3. 验证Chromedriver本身能否正常启动 #

有时候虽然装了Chromedriver，但因为权限或依赖问题启动失败。在CircleCI的SSH里直接运行chromedriver，看是否能输出类似Starting ChromeDriver 118.0.5993.70 ... on port 9515的日志。如果报错提示缺少依赖，可以尝试安装这些基础库：

sudo apt-get install -y libnss3 libgconf-2-4 libxss1 libappindicator1 libindicator7

不过官方Orb安装的Chrome一般会自带依赖，这个步骤可以作为兜底排查。

4. 换用webdrivers gem自动管理版本 #

如果你之前是手动安装Chromedriver，不如改用webdrivers gem，它会自动检测Chrome版本并下载对应的Chromedriver，彻底避免版本不匹配的问题：

• 在Gemfile里添加gem 'webdrivers', group: :test
• 移除spec配置里手动指定Chromedriver路径的代码，让webdrivers自动处理。

我当时的问题就是Chrome版本更新了，但Chromedriver还是旧版本，加上没加--no-sandbox参数，调整之后所有系统测试都正常跑起来了。你可以逐个排查这些点，应该能解决问题。

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