Implementation:Teamcapybara Capybara Spec Server

Knowledge Sources	Teamcapybara_Capybara
Domains	Testing, Test_Specification
Last Updated	2026-02-12 06:00 GMT

Overview

This test suite validates Capybara::Server, covering server booting, port selection, host binding, SSL support, server reuse, request handling, and error conditions.

Description

The file defines an RSpec.describe Capybara::Server block that tests the full lifecycle and configuration of Capybara's embedded test server. Tests verify that a Rack application can be booted and responds to HTTP requests, that a nil application can be booted without error, that the server binds to Capybara.server_host (both 127.0.0.1 and 0.0.0.0), and that ports are configurable via Capybara.server_port or the :port constructor option. It tests automatic port discovery when multiple servers run simultaneously and graceful recovery when TCPServer.new returns a port that is already in use. The suite validates the #base_url method output format, Puma configuration (environment string type via #clamp, no stderr warnings), and SSL support with PEM key/certificate files. Server reuse behavior is tested under both Capybara.reuse_server = true (shared port, joint pending request detection) and Capybara.reuse_server = false (separate ports, independent request tracking). Error handling tests cover server boot errors that raise before timeout, pending request timeout (60-second limit with descriptive error), #responsive? returning false on SystemCallError, and HTTPS fallback when HTTP connections return EOFError or Net::ReadTimeout.

Usage

This spec file is run as part of the Capybara test suite to ensure the embedded test server infrastructure works correctly across different configurations. It is particularly important for validating port management, SSL configuration, server reuse, and request lifecycle behavior that all other Capybara tests depend on.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: spec/server_spec.rb
• Lines: 1-315

Signature

RSpec.describe Capybara::Server do
  it 'should spool up a rack server' do ... end
  it 'should do nothing when no server given' do ... end
  it 'should bind to the specified host' do ... end
  it 'should use specified port' do ... end
  it 'should use given port' do ... end
  it 'should find an available port' do ... end
  it 'should handle that getting available ports fails randomly' do ... end
  it 'should return its #base_url' do ... end
  it 'should call #clamp on the puma configuration' do ... end
  it 'should not emit any warnings when booting puma' do ... end
  it 'should support SSL' do ... end

  context 'When Capybara.reuse_server is true' do
    it 'should use the existing server if it already running' do ... end
    it 'detects and waits for all reused server sessions pending requests' do ... end
  end

  context 'When Capybara.reuse_server is false' do
    it 'should not reuse an already running server' do ... end
    it 'detects and waits for only one sessions pending requests' do ... end
  end

  it 'should raise server errors when the server errors before the timeout' do ... end
  it 'should raise an error when there are pending requests' do ... end
  it 'is not #responsive? when Net::HTTP raises a SystemCallError' do ... end
  it 'should attempt an HTTPS connection if HTTP connection returns EOFError' do ... end
  it 'should attempt an HTTPS connection if HTTP connection returns Net::ReadTimeout' do ... end

  def start_request(server, wait_time) ... end
end

Import

require 'spec_helper'

Key Test Scenarios

• Server boot -- Verifies that a Rack application is booted and responds to HTTP GET requests with expected content
• Nil application handling -- Confirms that booting with nil does not raise an error
• Host binding -- Tests binding to 127.0.0.1 and 0.0.0.0 via Capybara.server_host
• Port configuration -- Tests Capybara.server_port global setting and :port constructor option for explicit port assignment
• Automatic port discovery -- Validates that multiple simultaneously booted servers find distinct available ports
• Port conflict recovery -- Tests graceful handling when TCPServer.new returns a port already in use, using mock doubles
• Base URL format -- Verifies #base_url returns a URI with correct scheme, host, and port components
• Puma configuration -- Ensures #clamp is called so the environment is a String (not a Proc), and that no warnings are emitted to stderr during boot
• SSL support -- Tests HTTPS server boot with PEM key and certificate files, verifies HTTP requests fail while HTTPS requests succeed, and confirms #base_url uses the https scheme
• Server reuse (true) -- Confirms that two servers with the same app share a port, and that wait_for_pending_requests waits for all reused sessions
• Server reuse (false) -- Confirms that two servers with the same app use different ports, and that wait_for_pending_requests only waits for one session's requests
• Server boot errors -- Validates that server errors raised during boot (e.g., RuntimeError 'kaboom') propagate correctly
• Pending request timeout -- Tests that requests completing within 60 seconds succeed while those exceeding 60 seconds raise a descriptive error
• Responsiveness check -- Verifies #responsive? returns false when Net::HTTP raises SystemCallError
• HTTPS fallback -- Tests that after EOFError or Net::ReadTimeout on HTTP, the server reattempts with an HTTPS connection to detect SSL servers

Related Pages

• Environment:Teamcapybara_Capybara_Ruby_And_Gem_Dependencies