Ruby运行selenium-webdriver时rspec加载spec_helper报错如何解决

Ruby环境下运行基于selenium-webdriver的RSpec测试，执行rspec -fd命令时触发spec_helper加载错误，控制台输出如下：

λ rspec -fd

An error occurred while loading spec_helper.
Failure/Error: require "selenium-webdriver"

TypeError:
  unable to resolve type 'intptr_t'
# ./spec/spec_helper.rb:3:in `<top (required)>'
# ------------------
# --- Caused by: ---
# LoadError:
#   cannot load such file -- selenium-webdriver
#   ./spec/spec_helper.rb:3:in `<top (required)>'
No examples found.
No examples found.


Finished in 0.00007 seconds (files took 1.87 seconds to load)
0 examples, 0 failures, 1 error occurred outside of examples

Finished in 0.00007 seconds (files took 1.87 seconds to load)
0 examples, 0 failures, 1 error occurred outside of examples

错误定位到./spec/spec_helper.rb第3行的require "selenium-webdriver"语句，先抛出TypeError: unable to resolve type 'intptr_t'，根因提示LoadError: cannot load such file -- selenium-webdriver，最终无测试用例被加载，在示例执行外抛出1个错误，搭配Firefox、Chrome浏览器运行时问题均可复现。

该错误发生在依赖加载阶段，和浏览器类型、驱动版本无关：intptr_t类型解析失败是selenium-webdriver的底层依赖ffi gem编译异常、缺少系统对应类型定义导致的，ffi加载失败会直接连带selenium-webdriver无法被正常引入，才会抛出后续的LoadError。

按顺序执行以下操作即可定位修复问题：

• 确认项目依赖安装正常
  进入项目根目录，执行bundle list | grep selenium-webdriver检查selenium-webdriver是否已经在当前bundle环境中安装。如果未查询到对应gem，先在Gemfile中添加依赖后执行bundle install，避免全局gem和项目bundle环境的版本冲突：

  # Gemfile中添加
  gem 'selenium-webdriver'
  

• 修复ffi gem编译异常（核心修复步骤）
  • Windows环境：该报错90%以上是Ruby对应的MSYS2 Devkit组件缺失、头文件不全导致。执行ridk install 3重新安装完整编译工具链，安装完成后执行gem uninstall ffi -aIx && gem install ffi卸载重装ffi，触发重新编译即可。
  • macOS环境：先执行xcode-select --install安装系统命令行编译工具，完成后执行gem pristine ffi重新编译已安装的ffi gem。
  • Linux（Debian/Ubuntu系）环境：先执行sudo apt update && sudo apt install -y build-essential libffi-dev安装基础编译依赖和ffi开发库，完成后执行gem pristine ffi重新编译ffi。
• 检查版本兼容性
  selenium-webdriver 4.x及以上版本要求Ruby版本不低于2.7，如果当前使用Ruby 2.6及更早版本，要么升级Ruby到兼容版本，要么在Gemfile中锁定兼容的老版本selenium-webdriver：

  # 老版本Ruby使用3.x版本的selenium-webdriver
  gem 'selenium-webdriver', '~> 3.142.7'
  

• 修复验证
  完成以上操作后，先在项目根目录执行bundle exec ruby -e "require 'selenium-webdriver'; puts Selenium::WebDriver::VERSION"，如果命令能正常输出版本号、无报错，再执行rspec -fd运行测试即可。

修复完成前不需要提前调整geckodriver、chromedriver的路径或版本配置——当前错误发生在代码加载阶段，根本没有走到浏览器驱动初始化的流程，等selenium-webdriver可以正常require后，再处理驱动相关配置即可。

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