Rails应用启用Headless Chrome测试时出现空白白屏及元素查找失败问题

我之前也碰到过几乎一模一样的场景，结合你给出的Capybara（2.15.1）、Selenium Webdriver（3.11.0）和Docker Selenium环境，给你几个针对性的排查和解决方向：

1. 补全Headless Chrome的必要启动参数 #

Headless模式下的Chrome需要额外配置一些参数，尤其是在Docker环境里，缺少这些参数很容易导致页面无法正常渲染：

Capybara.register_driver :selenium_chrome_headless do |app|
  options = Selenium::WebDriver::Chrome::Options.new
  # 核心Headless参数
  options.add_argument('--headless')
  options.add_argument('--disable-gpu') # 部分环境（如Windows）需要，Linux/Docker下也可加上保险
  # 关键：设置窗口大小，Headless默认窗口极小，会导致布局异常或元素不在可视区域
  options.add_argument('--window-size=1280,1024')
  # Docker环境必备参数：避免权限沙箱问题
  options.add_argument('--no-sandbox')
  # 解决Docker下/dev/shm空间不足导致的Chrome崩溃问题
  options.add_argument('--disable-dev-shm-usage')
  
  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
end

其中--window-size是最容易被忽略的点——没有设置窗口大小时，Headless Chrome的视口极小，页面可能会因为响应式布局完全不渲染内容，或者元素被挤到不可见区域，自然会出现找不到元素的情况。

2. 确保Docker Selenium镜像与Webdriver版本匹配 #

你的Selenium Webdriver是3.11.0，一定要使用对应版本的Docker Selenium镜像，比如selenium/standalone-chrome:3.11.0，而不是最新版。

Selenium Server和Webdriver的版本必须尽量一致，版本不匹配会导致通信协议不兼容，出现页面加载失败、命令无响应等问题，最终表现就是空白页。

3. 延长等待时间，添加显式等待 #

Headless模式下Chrome的页面加载速度可能和正常浏览器有差异，默认的Capybara等待时间可能不足以让页面完全渲染：

# 全局调整默认等待时间，从默认的2秒改成10秒
Capybara.default_max_wait_time = 10

或者针对特定元素使用显式等待，确保元素加载完成后再操作：

wait = Selenium::WebDriver::Wait.new(timeout: 10)
wait.until { page.find('#target-element').displayed? }

4. 检查页面的JavaScript错误 #

有时候正常模式下没问题，但Headless模式可能对某些JS特性的支持有差异，或者Docker环境的网络问题导致资源加载失败。你可以在测试中添加代码输出浏览器的JS日志：

# 输出浏览器控制台的所有日志
puts page.driver.browser.manage.logs.get(:browser)

如果看到JS报错，比如某个静态资源加载失败、某个脚本执行出错，那就是页面无法渲染的根源，针对性修复即可。

额外排查点：确认Docker网络连通性 #

确保你的Rails应用容器和Selenium容器在同一个网络下，并且Capybara的app_host设置正确，让Selenium能正常访问到你的应用服务。比如：

Capybara.app_host = 'http://your-rails-app-container:3000'

如果Selenium容器无法请求到你的Rails应用，自然会显示空白页。

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