Implementation:Teamcapybara Capybara Capybara Driver Configuration

Knowledge Sources	Capybara
Domains	Testing, Configuration
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for configuring which browser driver Capybara uses, provided by the Capybara module-level configuration API.

Description

Capybara exposes driver configuration through Capybara.default_driver=, Capybara.javascript_driver=, and Capybara.current_driver=. These are delegated from Capybara to Capybara::Config which stores them as instance variables (or thread variables when threadsafe mode is enabled). The getters return :rack_test and :selenium respectively when no explicit value has been set.

Usage

Set these in your test configuration block. Use default_driver for the baseline driver and javascript_driver for JS-dependent tests. current_driver is typically set automatically by RSpec hooks but can be set manually for one-off tests.

Code Reference

Source Location

• Repository: capybara
• File: lib/capybara.rb (delegators at L44-46), lib/capybara/config.rb (writers at L16, getters at L74-76, L82-84)
• Lines: lib/capybara.rb:L261-276 (current_driver/current_driver=)

Signature

# In Capybara module (delegated to Config)
Capybara.default_driver = name          # -> Symbol
Capybara.default_driver                 # -> Symbol (default: :rack_test)

Capybara.javascript_driver = name       # -> Symbol
Capybara.javascript_driver              # -> Symbol (default: :selenium)

Capybara.current_driver = name          # -> Symbol/nil
Capybara.current_driver                 # -> Symbol (falls back to default_driver)

Capybara.use_default_driver             # -> nil (resets current_driver to nil)

Import

require 'capybara'

I/O Contract

Inputs

Name	Type	Required	Description
name	Symbol	Yes	Name of a registered driver (e.g., :rack_test, :selenium, :selenium_chrome_headless)

Outputs

Name	Type	Description
Driver selection	Symbol	The driver name that will be used for the next session creation

Usage Examples

Configure Drivers

# In spec_helper.rb or rails_helper.rb
Capybara.default_driver = :rack_test
Capybara.javascript_driver = :selenium_chrome_headless

# Or via configure block:
Capybara.configure do |config|
  config.default_driver = :rack_test
  config.javascript_driver = :selenium_chrome_headless
end

Per-Test Override

# Temporarily use a specific driver
Capybara.using_driver(:selenium_chrome) do
  visit '/heavy-js-page'
  expect(page).to have_content('Loaded')
end

Related Pages

Implements Principle

• Principle:Teamcapybara_Capybara_Driver_Selection_Configuration