Overview
Capybara::RackTest::Driver is the built-in Rack-based test driver that provides fast, headless browser simulation without JavaScript support.
Description
RackTest::Driver extends Capybara::Driver::Base and serves as Capybara's default driver for non-JavaScript tests. It defines DEFAULT_OPTIONS with respect_data_method: false, follow_redirects: true, and redirect_limit: 5. The constructor requires a valid Rack application and merges user-provided options with the defaults. Internally, it lazily instantiates a Capybara::RackTest::Browser object that handles all HTTP interaction. The driver delegates visit, refresh, submit, follow, current_url, html, dom, and title to the browser. Element finding is provided through find_xpath and find_css, with find_css catching Nokogiri::CSS::SyntaxError to raise a descriptive ArgumentError when case-insensitive attribute selectors are used (which this driver does not support). The reset! method discards the browser instance, clearing all state. HTTP verb forwarding methods (get, post, put, delete) and header are delegated directly to the browser using Ruby's (...) forwarding syntax.
Usage
RackTest::Driver is used as Capybara's default driver for tests that do not require JavaScript execution. Register it explicitly or rely on the default configuration. It is ideal for fast integration tests against Rack applications (Rails, Sinatra, etc.).
Code Reference
Source Location
Signature
class Capybara::RackTest::Driver < Capybara::Driver::Base
DEFAULT_OPTIONS = {
respect_data_method: false,
follow_redirects: true,
redirect_limit: 5
}.freeze
attr_reader :app, :options
def initialize(app, **options)
def browser
def follow_redirects?
def redirect_limit
def response
def request
def visit(path, **attributes)
def refresh
def submit(method, path, attributes)
def follow(method, path, **attributes)
def current_url
def response_headers
def status_code
def find_xpath(selector)
def find_css(selector)
def html
def dom
def title
def reset!
def get(...)
def post(...)
def put(...)
def delete(...)
def header(key, value)
def invalid_element_errors
end
Import
require 'rack/test'
require 'rack/utils'
require 'mini_mime'
require 'nokogiri'
require 'capybara/rack_test/driver'
I/O Contract
| initialize(app, **options)
|
| Parameter |
Type |
Required |
Description
|
app |
Rack application |
Yes |
A valid Rack app; raises ArgumentError if nil
|
options[:respect_data_method] |
Boolean |
No |
Honor data-method attributes on links (default: false)
|
options[:follow_redirects] |
Boolean |
No |
Automatically follow HTTP redirects (default: true)
|
options[:redirect_limit] |
Integer |
No |
Maximum number of redirects before raising InfiniteRedirectError (default: 5)
|
options[:headers] |
Hash |
No |
Custom HTTP headers merged into every request
|
Returns: Capybara::RackTest::Driver instance
|
| visit(path, **attributes)
|
| Parameter |
Type |
Required |
Description
|
path |
String |
Yes |
URL or path to visit
|
**attributes |
Hash |
No |
Additional request parameters
|
Returns: (void) -- delegates to browser.visit
|
| find_xpath(selector) / find_css(selector)
|
| Parameter |
Type |
Required |
Description
|
selector |
String |
Yes |
XPath or CSS selector string
|
Returns: Array<Capybara::RackTest::Node> -- matching node elements
|
Raises: ArgumentError if find_css receives a case-insensitive attribute selector ( i])
|
| reset!
|
| Parameter |
Type |
Required |
Description
|
| (none)
|
Returns: (void) -- sets @browser to nil, discarding all session state
|
| current_url / html / title / dom
|
| Parameter |
Type |
Required |
Description
|
| (none)
|
Returns:
- current_url:
String -- the full current URL
- html:
String -- raw response body
- title:
String -- page title from the parsed DOM
- dom:
Nokogiri::HTML::Document -- the parsed document
|
| response_headers / status_code
|
| Parameter |
Type |
Required |
Description
|
| (none)
|
Returns:
- response_headers:
Hash -- HTTP response headers
- status_code:
Integer -- HTTP status code
|
Usage Examples
# Register the RackTest driver (this is the default):
Capybara.register_driver :rack_test do |app|
Capybara::RackTest::Driver.new(app,
follow_redirects: true,
redirect_limit: 10,
respect_data_method: true,
headers: { 'Accept-Language' => 'en' }
)
end
# Use in a test:
Capybara.current_driver = :rack_test
visit '/login'
fill_in 'Email', with: 'user@example.com'
fill_in 'Password', with: 'secret'
click_button 'Sign In'
expect(page).to have_current_path('/dashboard')
expect(page).to have_text('Welcome')
# Direct driver usage (internal):
driver = Capybara::RackTest::Driver.new(MyApp)
driver.visit('/users')
driver.find_css('table.users tr').length # => 10
driver.html # => "<html>..."
driver.current_url # => "http://www.example.com/users"
driver.status_code # => 200
driver.response_headers['Content-Type'] # => "text/html"
# Reset session state:
driver.reset!
driver.current_url # => ""
Related Pages
