Workflow:Teamcapybara Capybara RSpec Integration Setup
| Knowledge Sources | |
|---|---|
| Domains | Testing, Web_Automation, RSpec |
| Last Updated | 2026-02-12 06:00 GMT |
Overview
End-to-end process for integrating Capybara with RSpec to enable feature and system testing of Rack-based web applications.
Description
This workflow covers the complete setup required to use Capybara within an RSpec test suite. It starts from adding the gem dependency, configuring the test framework integration, selecting an appropriate driver, writing feature specs using Capybara's DSL, and properly managing session cleanup between tests. The workflow applies to both Rails and non-Rails Rack applications, with the Rails path providing automatic configuration via capybara/rails.
Usage
Execute this workflow when you have a Rack-based web application (Rails, Sinatra, etc.) and need to set up integration or acceptance tests using RSpec. This is the foundational setup workflow that must be completed before any Capybara-based testing can occur.
Execution Steps
Step 1: Add_Gem_Dependency
Add the Capybara gem to the project's Gemfile in the test group and install it via Bundler. This makes the Capybara library and all its modules available to the test suite.
Key considerations:
- Place the gem in the :test group (or :test, :development if needed for debugging)
- If using Selenium for JS tests, also add the selenium-webdriver gem
- Run bundle install to resolve and lock dependencies
Step 2: Require_Integration_Module
Load the appropriate Capybara integration module in the spec helper file. For Rails apps, require capybara/rails which auto-configures the Rack app. For non-Rails apps, require capybara/rspec and manually set Capybara.app to the Rack application.
Key considerations:
- capybara/rails auto-sets Capybara.app to Rails.application
- capybara/rspec includes the DSL and matchers for feature/system spec types
- This require also installs proxy methods to resolve naming conflicts between Capybara's all/within and RSpec's built-in matchers
Step 3: Configure_Driver_Selection
Choose the default driver and JavaScript driver for the test suite. The default driver (:rack_test) is fast but does not support JavaScript. For specs that require JS execution, configure :selenium, :selenium_chrome, or :selenium_chrome_headless as the JavaScript driver.
Key considerations:
- :rack_test is the default — fastest option, no browser process needed
- Use js: true metadata on individual specs to switch to the JavaScript driver
- Pre-registered Selenium drivers include :selenium, :selenium_headless, :selenium_chrome, and :selenium_chrome_headless
- For Rails 5.0+ without system tests, configure Puma as the server
Step 4: Configure_Server_And_Options
Set global Capybara configuration options including the embedded server, wait times, and matching strategy. The server boots automatically when a driver that needs it (e.g., Selenium) is active, running the Rack app in a separate thread.
Key considerations:
- Capybara.server = :puma, { Silent: true } for cleaner test output
- Capybara.default_max_wait_time controls auto-wait duration (default 2 seconds)
- Capybara.match controls ambiguity resolution (:smart by default)
- Consider Capybara.threadsafe = true for parallel test execution
Step 5: Write_Feature_Specs
Create feature specs using Capybara's DSL. Place specs in spec/features or spec/system (Rails) or tag example groups with type: :feature or type: :system. The feature DSL provides aliases like feature, scenario, background, and given for readable acceptance tests.
Key considerations:
- feature is an alias for describe ..., type: :feature
- scenario is an alias for it
- background is an alias for before
- given/given! are aliases for let/let!
- Use the Capybara DSL methods (visit, fill_in, click_button, etc.) directly
Step 6: Verify_Session_Cleanup
Ensure proper session reset between tests. When capybara/rspec is required, after hooks are automatically installed that call Capybara.reset_sessions! and Capybara.use_default_driver after each example. Verify this is functioning correctly to prevent test pollution.
Key considerations:
- The automatic after hook resets sessions and reverts to the default driver
- For non-RSpec frameworks, these cleanup methods must be called manually in teardown
- Session reset clears cookies, cache, and navigates to a blank page
- The before hook auto-switches to the JavaScript driver when js: true or :driver metadata is present