Implementation:Teamcapybara Capybara Cucumber Integration

Knowledge Sources	Teamcapybara_Capybara
Domains	Testing, Web_Automation
Last Updated	2026-02-12 06:00 GMT

Overview

The Capybara Cucumber integration file wires Capybara's DSL and RSpec matchers into the Cucumber test framework and configures Before/After hooks for driver management and session cleanup.

Description

This integration module performs four key actions: it injects Capybara::DSL into the Cucumber World context via World(Capybara::DSL), giving step definitions access to methods like visit, find, and fill_in; it injects Capybara::RSpecMatchers via World(Capybara::RSpecMatchers), enabling RSpec-style expectations such as have_selector and have_text within Cucumber steps; it registers an After hook that calls Capybara.reset_sessions! to ensure each scenario starts with a clean session state; and it registers Before hooks that manage driver selection -- resetting to the default driver at the start of each scenario, switching to the JavaScript driver for scenarios tagged @javascript, and dynamically selecting a registered driver when a scenario is tagged with a matching driver name (e.g., @selenium, @rack_test).

Usage

Require this file in your Cucumber support directory (e.g., features/support/env.rb) to automatically configure Capybara for use with Cucumber. No additional setup is needed beyond the require statement -- all hooks and world inclusions are applied immediately.

Code Reference

Source Location

Repository: Teamcapybara_Capybara
File: lib/capybara/cucumber.rb
Lines: 1-27

Signature

World(Capybara::DSL)
World(Capybara::RSpecMatchers)

After do
  Capybara.reset_sessions!
end

Before do
  Capybara.use_default_driver
end

Before '@javascript' do
  Capybara.current_driver = Capybara.javascript_driver
end

Before do |scenario|
  scenario.source_tag_names.each do |tag|
    driver_name = tag.sub(/^@/, '').to_sym
    Capybara.current_driver = driver_name if Capybara.drivers[driver_name]
  end
end

Import

require 'capybara/cucumber'
# Which internally requires:
# require 'capybara/dsl'
# require 'capybara/rspec/matchers'
# require 'capybara/rspec/matcher_proxies'

I/O Contract

Inputs

Name	Type	Required	Description
scenario	Cucumber::RunningTestCase	Yes (in Before hook)	The current Cucumber scenario object, used to inspect source tag names for driver selection.
@javascript tag	Cucumber Tag	No	When present on a scenario, triggers the switch to Capybara.javascript_driver.
@<driver_name> tag	Cucumber Tag	No	When a scenario tag matches a registered Capybara driver name, that driver is selected for the scenario.

Outputs

Name	Type	Description
Capybara::DSL methods	Mixed	Step definitions gain access to all Capybara DSL methods (visit, find, fill_in, click_link, etc.).
Capybara::RSpecMatchers	Mixed	Step definitions gain access to RSpec-style matchers (have_selector, have_text, have_current_path, etc.).
Session reset	nil	After each scenario, all Capybara sessions are reset to a clean state.
Driver selection	nil	Before each scenario, the appropriate driver is selected based on tags.

Usage Examples

Basic Usage

# features/support/env.rb
require 'capybara/cucumber'

Capybara.app = MyRackApp
Capybara.default_driver = :rack_test
Capybara.javascript_driver = :selenium_chrome_headless

# features/step_definitions/homepage_steps.rb
Given('I visit the homepage') do
  visit '/'
end

Then('I should see the welcome message') do
  expect(page).to have_text('Welcome')
end

# features/login.feature
@javascript
Scenario: User logs in with JavaScript-enabled browser
  Given I visit the homepage
  Then I should see the welcome message

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment