Environment:Teamcapybara Capybara Ruby And Gem Dependencies

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

Overview

Ruby 3.2+ environment with Nokogiri, Rack, XPath, and supporting gems required to run the Capybara integration testing framework (version 3.40.0).

Description

This environment defines the core Ruby runtime and gem dependency stack required for Capybara. The library is a Rack-based integration testing framework that simulates user interactions with web applications. It requires Ruby 3.2.0 or higher and depends on a set of runtime gems for HTML parsing (Nokogiri), XPath evaluation, Rack middleware integration, MIME type detection, and regular expression parsing. The CI matrix tests against Ruby 3.2, 3.3, and 3.4.

Usage

This environment is the base prerequisite for all Capybara functionality. Every workflow, implementation, and test in the Capybara ecosystem requires these dependencies. It applies to both the RackTest driver (headless) and the Selenium driver (browser-based) execution paths.

System Requirements

Category	Requirement	Notes
Language	Ruby >= 3.2.0	CI tests on 3.2, 3.3, 3.4
OS	Linux, macOS, Windows	Cross-platform; macOS has port-binding edge cases
Disk	Minimal	No large dataset or model storage required

Dependencies

Runtime Gems

`addressable` — URI parsing (no version constraint)
`matrix` — Matrix operations (no version constraint)
`mini_mime` >= 0.1.3 — MIME type detection
`nokogiri` ~> 1.11 — HTML/XML parsing
`rack` >= 1.6.0 — Web server interface (supports Rack 2.x and 3.x)
`rack-test` >= 0.6.3 — Rack testing utilities
`regexp_parser` >= 1.5, < 3.0 — Regular expression analysis
`xpath` ~> 3.2 — XPath expression generation

Development/Test Gems (Key)

`rspec` >= 3.5.0 — Test framework
`selenium-webdriver` ~> 4.8 — Browser automation (see Selenium environment page)
`puma` — Default application server (minimum 3.8.0 at runtime)
`sinatra` >= 1.4.0 — Test application framework
`cucumber` >= 2.3.0 — BDD test framework
`rackup` — Required for Rack 3 compatibility

Platform-Specific Dependencies

JRuby: Excludes `byebug` development dependency
Rubinius (rbx): Requires additional gems: `json`, `racc`, `rubysl`

Credentials

No credentials or environment variables are required for the core dependency stack. See the Selenium environment page for browser-specific environment variables.

Quick Install

# Install Capybara and core dependencies
gem install capybara

# Or add to Gemfile
# gem 'capybara', '~> 3.40'

# For development/testing with full stack
bundle install

Code Evidence

Ruby version constraint from `capybara.gemspec:11`:

s.required_ruby_version = '>= 3.2.0'

Runtime dependency declarations from `capybara.gemspec:33-40`:

s.add_runtime_dependency('addressable')
s.add_runtime_dependency('matrix')
s.add_runtime_dependency('mini_mime', ['>= 0.1.3'])
s.add_runtime_dependency('nokogiri', ['~> 1.11'])
s.add_runtime_dependency('rack', ['>= 1.6.0'])
s.add_runtime_dependency('rack-test', ['>= 0.6.3'])
s.add_runtime_dependency('regexp_parser', ['>=1.5', '<3.0'])
s.add_runtime_dependency('xpath', ['~>3.2'])

Platform-specific handling from `capybara.gemspec:42,67-71`:

s.add_development_dependency('byebug') unless RUBY_PLATFORM == 'java'

if RUBY_ENGINE == 'rbx'
  s.add_development_dependency('json')
  s.add_development_dependency('racc')
  s.add_development_dependency('rubysl')
end

Common Errors

Error Message	Cause	Solution
`Gem::MissingSpecError: Could not find 'nokogiri'`	Nokogiri not installed or native extensions failed	`gem install nokogiri` — may need system libxml2/libxslt packages
`Capybara requires puma version 3.8.0 or higher`	Puma gem too old or missing	`gem install puma` or upgrade version in Gemfile
`Capybara is unable to load puma for its server`	Puma not in bundle	Add `gem 'puma'` to Gemfile or use `Capybara.server = :webrick`

Compatibility Notes

Rack 2.x vs 3.x: Capybara supports both. Rack 3 requires the `rackup` gem separately. WEBrick handler loading differs between versions (falls back from `rack/handler/webrick` to `rackup/handler/webrick`).
Sinatra 4.x: Required for Rack 3 compatibility in test applications.
Bundler: Must be < 3.0 (specified in Gemfile).
JRuby: Float checking and some platform-specific code paths differ. The `byebug` debugger is excluded.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment