Principle:Teamcapybara Capybara Server And Options Configuration

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

Overview

A configuration pattern for setting the embedded test server, wait times, and other global options that control Capybara's testing behavior.

Description

Server and Options Configuration covers the global settings that affect how Capybara runs tests beyond driver selection. This includes:

• Server selection — Which Rack server boots the application under test (Puma by default)
• Wait times — How long Capybara auto-retries before failing (default_max_wait_time, default 2 seconds)
• App host — A base URL for remote testing
• Other options — Selector defaults, visibility rules, error handling, etc.

These settings exist at two levels: global (Capybara::Config) and per-session (Capybara::SessionConfig). Per-session settings are only available when threadsafe mode is enabled.

Usage

Use this principle at application startup to configure the test environment. Set server to control which Rack server boots, default_max_wait_time for async wait tolerance, and app_host for external application testing.

Theoretical Basis

Configuration follows a two-tier delegation pattern:

# Abstract configuration layers (not actual code)
Capybara.configure do |config|
  # Config::OPTIONS (global-only)
  config.server = :puma
  config.default_driver = :rack_test
  config.threadsafe = true

  # SessionConfig::OPTIONS (per-session when threadsafe)
  config.default_max_wait_time = 5
  config.default_selector = :css
  config.ignore_hidden_elements = true
end

Related Pages

Implemented By

• Implementation:Teamcapybara_Capybara_Capybara_Server_Configuration

Uses Heuristic

• Heuristic:Teamcapybara_Capybara_Animation_Disabling_For_Tests