Implementation:Teamcapybara Capybara Capybara Server Boot

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

Overview

Concrete tool for booting an embedded Rack server for browser-based testing provided by Capybara::Server.

Description

Capybara::Server.new initializes with the Rack app, port, host, reportable errors, and extra middleware. Server#boot starts the registered server handler in a Thread.new, then polls responsive? (which hits the /__identify__ endpoint) until the server confirms readiness or 60 seconds elapse. The middleware wraps the app with error capture and request tracking. Port reuse is managed via Capybara::Server.ports keyed by app object_id.

Usage

Automatically managed by Capybara sessions. Access server.base_url for the running server's URL.

Code Reference

Source Location

Repository: capybara
File: lib/capybara/server.rb
Lines: L21-39 (initialize), L72-89 (boot)

Signature

class Capybara::Server
  def initialize(app,
                 *deprecated_options,
                 port: Capybara.server_port,
                 host: Capybara.server_host,
                 reportable_errors: Capybara.server_errors,
                 extra_middleware: [])
    # @param app [Rack::App] The application to serve
    # @param port [Integer, nil] Server port (nil = find available)
    # @param host [String] Bind address (default: '127.0.0.1')
    # @param reportable_errors [Array<Class>] Errors to propagate
    # @param extra_middleware [Array] Additional Rack middleware
  end

  def boot
    # @return [Capybara::Server] self
    # Starts server in background thread, waits for responsiveness
  end

  def base_url
    # @return [String] "http(s)://host:port"
  end
end

Import

require 'capybara'
# Server is created internally by Session

I/O Contract

Inputs

Name	Type	Required	Description
app	Rack::App	Yes	The Rack application to serve
port	Integer/nil	No	Server port (default: random available)
host	String	No	Bind address (default: '127.0.0.1')
reportable_errors	Array<Class>	No	Error classes to propagate (default: [Exception])

Outputs

Name	Type	Description
self	Capybara::Server	The booted server instance
base_url	String	URL of the running server (e.g., http://127.0.0.1:4567)

Usage Examples

Default Server Configuration

# Capybara boots server automatically when a session needs it
# Configure the server handler:
Capybara.server = :puma

# Or with options:
Capybara.server = :puma, { Silent: true }

# Access in tests (rarely needed):
# page.server.base_url -> "http://127.0.0.1:PORT"

Related Pages

Implements Principle

Principle:Teamcapybara_Capybara_Server_Boot

Requires Environment

Page Connections

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

Principle

Implementation

Heuristic

Environment