Principle:Teamcapybara Capybara Server Boot

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

Overview

A server lifecycle pattern that boots an embedded Rack server in a background thread, making the application under test accessible via HTTP for browser-based drivers.

Description

Server Boot manages the lifecycle of the embedded HTTP server that serves the application under test. Browser-based drivers (Selenium) need a real HTTP server to connect to, unlike RackTest which operates in-process. The pattern:

1. Creates a Capybara::Server instance with the Rack app
2. Wraps the app in middleware for error tracking and request counting
3. Starts the server in a background thread using the registered server handler (Puma by default)
4. Polls a /__identify__ endpoint until the server responds, confirming it's ready
5. Provides a base_url for the driver to navigate to

Server ports are reusable (tracked per-app) when reuse_server is enabled, avoiding port exhaustion during test suites.

Usage

This is handled automatically by Capybara when a session boots. Manual interaction is rarely needed unless implementing a custom driver or server configuration.

Theoretical Basis

# Abstract server boot flow (not actual code)
server = Server.new(app, port: find_available_port, host: '127.0.0.1')
server.boot:
  thread = Thread.new { server_handler.call(middleware, port, host) }
  poll until server.responsive?  # checks /__identify__ endpoint
  return server  # server.base_url -> "http://127.0.0.1:PORT"

Related Pages

Implemented By

• Implementation:Teamcapybara_Capybara_Capybara_Server_Boot