Workflow:Teamcapybara Capybara Selenium Driver Configuration
| Knowledge Sources | |
|---|---|
| Domains | Testing, Web_Automation, Browser_Configuration |
| Last Updated | 2026-02-12 06:00 GMT |
Overview
End-to-end process for configuring Capybara to use Selenium WebDriver for browser-based testing, including driver registration, browser selection, and browser-specific customization.
Description
This workflow covers how to configure Capybara's Selenium driver for real browser testing. It starts from installing the Selenium WebDriver dependency, understanding the pre-registered driver configurations, creating custom driver registrations with browser-specific options, and activating drivers for test execution. Capybara's Selenium driver dynamically extends itself with browser-specific specializations (Chrome, Firefox, Edge, Safari) that handle each browser's unique capabilities and workarounds.
Usage
Execute this workflow when you need to test JavaScript-dependent behavior, interactions that require a real browser rendering engine, or when testing against visual layout. Also use this when the default RackTest driver is insufficient because your application uses JavaScript, requires access to external URLs, or needs real browser behavior.
Execution Steps
Step 1: Install_Selenium_Dependency
Add the selenium-webdriver gem to the project's Gemfile and install it. Ensure the target browser and its corresponding driver binary (chromedriver, geckodriver, etc.) are available on the system PATH.
Key considerations:
- Capybara requires Selenium 3.5 or later
- The browser binary and driver binary must both be installed
- For CI environments, headless browser configurations are typically required
- Docker-based setups may use Selenium Grid for remote browser execution
Step 2: Understand_Pre_Registered_Drivers
Capybara pre-registers four Selenium driver configurations out of the box. These are ready to use without any additional configuration for local development environments.
Available pre-registered drivers:
- :selenium — Firefox with default settings
- :selenium_headless — Firefox in headless mode
- :selenium_chrome — Chrome with default settings
- :selenium_chrome_headless — Chrome in headless mode
Key considerations:
- These registrations are defined in registrations/drivers.rb
- They work for local desktop environments but may need customization for CI
- Each registration creates a Capybara::Selenium::Driver instance with the appropriate browser option
Step 3: Register_Custom_Driver
Use Capybara.register_driver to define a custom driver with specific browser options. The registration block receives the Rack app and must return a driver instance. Browser-specific options (window size, headless mode, proxy, capabilities) are configured through Selenium's Options classes.
Pseudocode:
Register a named driver with a block In the block, create browser Options with desired settings Instantiate Capybara::Selenium::Driver with the app and options Return the driver instance
Key considerations:
- Driver registrations are global and lazy — the block is only evaluated when the driver is first used
- The driver name is a Symbol used to reference the registration
- Browser options (:args, :prefs) are passed via the browser's Options class
- Additional Selenium capabilities can be specified for remote WebDriver connections
Step 4: Activate_Driver
Set the registered driver as the current, default, or JavaScript driver. Drivers can be activated globally, per-test, or temporarily via block-scoped switching.
Key considerations:
- Capybara.default_driver = :my_driver sets the default for all tests
- Capybara.javascript_driver = :my_driver sets the driver used when js: true is specified
- Capybara.current_driver = :my_driver temporarily switches (reverted by use_default_driver)
- In RSpec, driver: :my_driver metadata on a spec overrides the driver for that spec
- Switching drivers creates a new session — cannot switch mid-test
Step 5: Configure_Server_For_Selenium
When Selenium is active, Capybara automatically boots an embedded HTTP server to serve the Rack application. Configure the server settings to ensure compatibility with the Selenium driver's requirements.
Key considerations:
- Capybara defaults to Puma for the embedded server
- Capybara.server = :puma, { Silent: true } suppresses server log output
- The server runs in a separate thread from the test
- Capybara.server_port and Capybara.server_host control binding
- For remote browsers, the server host must be accessible from the browser's network
Step 6: Handle_Browser_Specializations
Capybara's Selenium driver dynamically extends itself with browser-specific modules at runtime. These specializations handle each browser's unique capabilities, workarounds, and features (CDP for Chrome/Edge, log retrieval, file download handling).
Key considerations:
- Chrome/Edge specializations provide CDP (Chrome DevTools Protocol) access
- Firefox specializations include geckodriver-specific workarounds
- Safari specializations handle Safari's unique permission model
- Browser-specific node implementations override element interaction behavior
- File download, modal handling, and screenshot behavior may vary by browser