Implementation:Teamcapybara Capybara Capybara Server Configuration

Knowledge Sources	Capybara
Domains	Testing, Configuration
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for configuring Capybara's server, wait times, and global options via Capybara.configure and direct attribute setters.

Description

Capybara.configure yields a Capybara::Config object. Config::OPTIONS (:app, :server, :default_driver, :javascript_driver, :threadsafe, etc.) are global settings. SessionConfig::OPTIONS (:default_max_wait_time, :default_selector, :ignore_hidden_elements, :app_host, etc.) are delegated through Config and can be per-session when threadsafe is true.

Capybara.server= accepts a Symbol (registered server name), an Array of [name, options], or a callable Proc.

Usage

Call Capybara.configure in your test helper to set options in a block, or set individual options directly (e.g., Capybara.default_max_wait_time = 5).

Code Reference

Source Location

Repository: capybara
File: lib/capybara.rb (L114-116 for configure), lib/capybara/config.rb (L59-68 for server=), lib/capybara/session/config.rb (L7-11 for SessionConfig::OPTIONS)

Signature

# Block-based configuration
Capybara.configure { |config| ... }  # -> nil

# Server setter
Capybara.server = :puma              # Symbol name
Capybara.server = [:puma, { Silent: true }]  # [Symbol, Hash]
Capybara.server = ->(app, port, host) { ... }  # Proc

# Key session options
Capybara.default_max_wait_time = seconds  # Numeric (default: 2)
Capybara.default_selector = :css          # :css or :xpath
Capybara.app_host = 'http://example.com'  # String URL or nil
Capybara.run_server = true                # Boolean

Import

require 'capybara'

I/O Contract

Inputs

Name	Type	Required	Description
server	Symbol/Array/Proc	No	Server to boot the app under test (default: :default which uses Puma)
default_max_wait_time	Numeric	No	Seconds to wait for async operations (default: 2)
app_host	String/nil	No	Base URL for remote testing
run_server	Boolean	No	Whether to boot an embedded server (default: true)

Outputs

Name	Type	Description
Configuration state	Config/SessionConfig	Updated global configuration affecting all subsequent Capybara operations

Usage Examples

Full Configuration

Capybara.configure do |config|
  config.run_server = true
  config.server = :puma
  config.default_max_wait_time = 5
  config.default_selector = :css
  config.app_host = nil
  config.always_include_port = false
  config.automatic_label_click = true
  config.enable_aria_label = true
  config.raise_server_errors = true
  config.test_id = 'data-testid'
end

Puma with Silent Mode

Capybara.server = :puma, { Silent: true }

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment