Overview
Capybara::RackTest::Browser is the browser abstraction for Rack-based testing, handling HTTP request dispatch, redirect following, URI construction, DOM parsing, and response inspection.
Description
Browser includes ::Rack::Test::Methods to gain HTTP verb methods (get, post, put, delete) and session management. It manages the full request lifecycle: visit issues a GET request and resets the host; submit handles form submissions with configurable HTTP methods and content types; follow processes link clicks with referer tracking. The process_and_follow_redirects method handles redirect chains up to the driver's redirect_limit, preserving the HTTP method for 307/308 status codes and switching to GET for other redirects. It raises Capybara::InfiniteRedirectError when the limit is exceeded. URI construction via build_uri resolves relative paths against the current host, scheme, port, and any <base> href in the document. The dom method lazily parses the response body into a Nokogiri document via Capybara::HTML, and find queries the DOM using either CSS or XPath selectors, wrapping results as Capybara::RackTest::Node objects. Fragment identifiers and javascript: URLs are detected and skipped by follow.
Usage
Browser is not used directly by test authors. It is instantiated internally by Capybara::RackTest::Driver and provides the low-level HTTP and DOM interface that the driver delegates to. Use it when building custom Rack-based driver extensions.
Code Reference
Source Location
Signature
class Capybara::RackTest::Browser
include ::Rack::Test::Methods
attr_reader :driver
attr_accessor :current_host
def initialize(driver)
def app
def options
def visit(path, **attributes)
def refresh
def submit(method, path, attributes, content_type: nil)
def follow(method, path, **attributes)
def process_and_follow_redirects(method, path, attributes = {}, env = {})
def process(method, path, attributes = {}, env = {})
def build_uri(path)
def current_url
def reset_host!
def reset_cache!
def dom
def find(format, selector)
def html
def title
end
Import
# Browser relies on Rack::Test::Methods (included as a mixin).
# It is loaded by the RackTest driver:
require 'rack/test'
require 'capybara/rack_test/browser'
I/O Contract
| initialize(driver)
|
| Parameter |
Type |
Required |
Description
|
driver |
Capybara::RackTest::Driver |
Yes |
The parent driver providing the Rack app, options, and session configuration
|
Returns: Browser instance with @current_fragment set to nil
|
| visit(path, **attributes)
|
| Parameter |
Type |
Required |
Description
|
path |
String |
Yes |
The URL or path to visit
|
**attributes |
Hash |
No |
Additional request parameters
|
| Returns: (void) -- issues a GET request, resets cache and host, follows redirects
|
| submit(method, path, attributes, content_type: nil)
|
| Parameter |
Type |
Required |
Description
|
method |
Symbol or String |
Yes |
HTTP method (:get, :post, :put, :delete, etc.)
|
path |
String |
Yes |
Form action path; falls back to current request path if nil or empty
|
attributes |
Hash |
Yes |
Form field name-value pairs
|
content_type: |
String |
No |
Optional content type header override
|
| Returns: (void) -- submits the form data and follows redirects
|
| follow(method, path, **attributes)
|
| Parameter |
Type |
Required |
Description
|
method |
Symbol or String |
Yes |
HTTP method to use
|
path |
String |
Yes |
Link href to follow; skipped if fragment-only or javascript:
|
**attributes |
Hash |
No |
Additional request parameters
|
| Returns: (void) -- follows the link with referer header set
|
| find(format, selector)
|
| Parameter |
Type |
Required |
Description
|
format |
Symbol (:css or :xpath) |
Yes |
The selector format
|
selector |
String |
Yes |
CSS or XPath selector string
|
Returns: Array<Capybara::RackTest::Node> -- matching nodes wrapped in Capybara node objects
|
| current_url / html / title / dom
|
| Parameter |
Type |
Required |
Description
|
| (none)
|
Returns:
- current_url:
String -- full URL including fragment; empty string if no request made
- html:
String -- raw response body; empty string if no request made
- title:
String -- page title from the DOM
- dom:
Nokogiri::HTML::Document -- lazily parsed document from html
|
Usage Examples
# Browser is used internally by the RackTest driver.
# These examples show the internal API:
driver = Capybara::RackTest::Driver.new(my_rack_app)
browser = driver.browser
# Visit a page:
browser.visit('/dashboard')
# Inspect the response:
browser.current_url # => "http://www.example.com/dashboard"
browser.html # => "<html><head><title>Dashboard</title>..."
browser.title # => "Dashboard"
# Find elements via CSS:
nodes = browser.find(:css, 'a.nav-link')
nodes.first.text # => "Home"
# Find elements via XPath:
nodes = browser.find(:xpath, '//input[@type="submit"]')
# Submit a form:
browser.submit(:post, '/login', { username: 'admin', password: 'secret' })
# Follow a link:
browser.follow(:get, '/about')
# Refresh the page:
browser.refresh
# Access the parsed DOM:
browser.dom.css('h1').text # => "Welcome"
Related Pages
