Environment:Teamcapybara Capybara Selenium WebDriver Environment

Knowledge Sources	Capybara Selenium WebDriver capybara.gemspec
Domains	Infrastructure, Browser_Automation, Testing
Last Updated	2026-02-12 06:00 GMT

Overview

Selenium WebDriver 4.8+ environment with Chrome, Firefox, or Edge browser binaries required for Capybara's JavaScript-capable driver.

Description

This environment defines the browser automation stack required when using Capybara with the Selenium driver for JavaScript-enabled integration testing. It requires `selenium-webdriver` gem version 4.8 or higher, plus a compatible browser binary (Chrome, Firefox, Edge, or Safari) and its corresponding driver binary (ChromeDriver, geckodriver, etc.). The Selenium driver supports multiple browser specializations with browser-specific workarounds for Chrome, Firefox, Edge, IE, and Safari.

Usage

Use this environment when running any Capybara test that requires JavaScript execution, browser rendering, or real HTTP interactions. It is the mandatory prerequisite for the `:selenium`, `:selenium_chrome`, `:selenium_chrome_headless`, and `:selenium_headless` built-in drivers. Tests that only need the RackTest driver do not require this environment.

System Requirements

Category	Requirement	Notes
Language	Ruby >= 3.2.0	Same as base Capybara environment
Browser	Chrome 75+, Firefox, Edge, or Safari	ChromeDriver 76.0.3809.25+ recommended for Chrome
OS	Linux, macOS, Windows	Windows adds `--disable-gpu` flag for headless Chrome
Network	Localhost HTTP server	Capybara boots an embedded Puma/WEBrick server

Dependencies

Gem Dependencies

`selenium-webdriver` ~> 4.8 — Browser automation protocol
`puma` >= 3.8.0 — Default embedded application server (or `webrick` as alternative)

Browser Binaries

Chrome: Google Chrome or Chromium, version 75+ (for file input clear support). ChromeDriver >= 76.0.3809.25 for `isDisplayed` endpoint support, >= 76.0.3809.68 for fixed actions key state.
Firefox: Mozilla Firefox with geckodriver. Capybara patches geckodriver 0.x pause duration bug.
Edge: Microsoft Edge (Chromium-based) with Edge WebDriver.
Safari: Safari with SafariDriver (macOS only).
Internet Explorer: IE with IEDriverServer (Windows only, limited support).

Credentials

The following environment variables control Selenium behavior:

`DISABLE_CAPYBARA_SELENIUM_OPTIMIZATIONS` — When set, disables Chrome/Firefox CSS selector optimizations in element finding
`HEADLESS` — When set, runs browsers in headless mode (used in CI)
`WD_CACHE_TIME` — Controls WebDriver binary cache duration (set to `0` in CI)

Quick Install

# Add to Gemfile
# gem 'selenium-webdriver', '~> 4.8'
# gem 'puma'

# Install Chrome and ChromeDriver (Ubuntu/Debian)
# apt-get install -y chromium-browser chromium-chromedriver

# Or use selenium-webdriver's built-in driver management
bundle install

Code Evidence

Selenium version check and warning from `lib/capybara/selenium/driver.rb:15,37-46`:

CAPS_VERSION = Gem::Requirement.new('< 4.8.0')

@selenium_webdriver_version =
  if Gem.loaded_specs['selenium-webdriver']
    Gem.loaded_specs['selenium-webdriver'].version
  else
    Gem::Version.new(Selenium::WebDriver::VERSION)
  end

unless Gem::Requirement.new('>= 4.8').satisfied_by? @selenium_webdriver_version
  warn "Warning: You're using an unsupported version of selenium-webdriver, please upgrade to 4.8+."
end

Puma version check from `lib/capybara/registrations/servers.rb:33-34`:

unless puma_rack_handler.respond_to?(:config)
  raise LoadError, 'Capybara requires `puma` version 3.8.0 or higher, please upgrade `puma` or register and specify your own server block'
end

Puma SSL patch conditional from `lib/capybara/registrations/servers.rb:46-47`:

puma_ver = Gem::Version.new(Puma::Const::PUMA_VERSION)
require_relative 'patches/puma_ssl' if Gem::Requirement.new('>=4.0.0', '< 4.1.0').satisfied_by?(puma_ver)

Selenium load error handling from `lib/capybara/registrations/servers.rb:29`:

raise LoadError, 'Capybara is unable to load `puma` for its server, please add `puma` to your project or specify a different server via something like `Capybara.server = :webrick`.'

Common Errors

Error Message	Cause	Solution
`Warning: You're using an unsupported version of selenium-webdriver, please upgrade to 4.8+.`	selenium-webdriver gem < 4.8	`gem update selenium-webdriver` or set `~> 4.8` in Gemfile
`Capybara requires puma version 3.8.0 or higher`	Puma gem too old	Upgrade puma: `gem install puma`
`Capybara is unable to load puma for its server`	Puma not installed	Add `gem 'puma'` to Gemfile or use `Capybara.server = :webrick`
`Rack application timed out during boot`	Server failed to start within 60 seconds	Check server configuration; ensure port is available
`Selenium::WebDriver::Error::ObsoleteElementError`	Element removed from DOM during interaction	Normal in async apps; Capybara retries automatically via `synchronize`

Compatibility Notes

Windows: Automatically adds `--disable-gpu` flag for headless Chrome (detected via `Gem.win_platform?`).
Chrome < 77: Does not maintain mouse button state across W3C Actions API calls.
ChromeDriver < 76.0.3809.68: Actions key state not properly tracked.
Puma 4.0.0 to 4.0.x: Requires SSL monkey-patch for `read_nonblock` method.
Rack 3: Handler loading falls back from `rack/handler/puma` to `rackup/handler/puma` (requires `rackup` gem).
macOS: Port binding workaround — Capybara binds twice to verify port availability on all IP addresses.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment