In a Rails system test, where does the application run, and what follows from the test and the Puma server sharing one process?
answer
- Capybara boots Puma in a Thread
- one pinned connection, both threads
- Ruby-side stubs reach the app, browser clock does not
- reset_sessions! waits for pending requests
- served_by host: for a remote browser
basics
~20 sCapybara boots the app on Puma in a thread of the test process, and the browser reaches it over HTTP. Test and server share the database connection, stubs and time travel, but run concurrently, so tests must wait for the server.
solid answer
~50 sFor a Selenium-driven test, Capybara starts Puma (Rails selects it as the server) in a `Thread` inside the test process on a random port, and Chrome connects to it. Consequences: with transactional tests the server thread uses the same pinned database connection, so it sees fixtures and records the test created; process-wide changes made in Ruby, such as a stubbed class method or `travel_to`, also affect the app, while the browser's own JavaScript clock is untouched; the two threads run concurrently, so the test must use waiting assertions before reading results; an exception in the app is re-raised in the test because `Capybara.raise_server_errors` is true; and after each test `Capybara.reset_sessions!` waits for in-flight requests before the next test starts. When the browser runs elsewhere, for example in a container, `served_by host: "0.0.0.0", port: 3001` makes the server reachable.
code
ruby · 16 linesclass ClosingTimeTest < ApplicationSystemTestCase
test "booking closes 30 minutes before the screening" do
screening = screenings(:evening) # visible to the Puma thread
travel_to screening.starts_at - 20.minutes # Ruby time, process-wide
visit screening_url(screening)
click_on "B7"
assert_text "Booking has closed" # wait for the server's answer
end
end
# Browser in another container
class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
served_by host: "0.0.0.0", port: 3001
endgo deeper
Know that the app runs on a test server inside the test process and that the browser connects to it over HTTP.
Explain what the shared process means for database visibility, stubs and time travel, and why the test must wait before checking side effects.
Diagnose leaks and races between the test and server threads, including errors re-raised from the app and requests still running at teardown.
Decide how to run browser tests in containerised CI, including remote browsers and served_by, while keeping the in-process data guarantees.
## Where the app runs A Rails system test with a browser driver has three participants: 1. The **test thread**, running Minitest and Capybara commands. 2. The **server thread**, running the Rails app on Puma, started by Capybara inside the same Ruby process. 3. The **browser**, a separate Chrome process controlled through WebDriver, which sends HTTP requests to the server thread. Capybara boots the server lazily the first time a driver that needs one is used. Rails' system-testing setup tells Capybara to use Puma, optionally silenced, and to always include the port in URLs, so route helpers like `screening_url` point at the test server. The `rack_test` driver needs no server at all and skips this whole arrangement. ## Shared: the database connection With transactional tests on, Active Record pins one connection per database for the whole test and shares it across threads, serialising access. The Puma thread therefore reads and writes inside the same uncommitted transaction as the test: - Fixtures and records created before `visit` are visible to the app. - Records the app creates during the test are visible to the test, and are rolled back afterwards. The fixture transaction itself is configured elsewhere; what matters here is that it only works because the server is a thread in the same process. ## Shared: everything else in Ruby Because it is one process, Ruby-level changes made by the test apply to the app too: | Change in the test | Seen by the server thread? | Seen by the browser? | |---|---|---| | `travel_to Time.zone.local(2026, 12, 24, 19)` | yes, Ruby time is stubbed process-wide | no, JavaScript `Date` uses the real clock | | stubbing a class method, such as a payment gateway | yes | not applicable | | `Current` attributes set in the test thread | no, they are per thread or fiber | no | | an environment variable changed with `ENV[]=` | yes | no | This is why a "seats close 30 minutes before the screening" rule can be tested by time travel on the server side, while a JavaScript countdown in the page still shows the real time. ## Concurrent: the two threads race The server thread works while the test thread continues. After `click_on "Hold B7"`: - the test thread returns once the browser has dispatched the click; - the request, the update and the Turbo response happen later in Puma. So the test must wait for evidence on the page, with `assert_selector` or `assert_text`, before reading the database or asserting side effects. Reading first is the classic race. ## Errors cross the boundary An exception raised in the app does not just produce an error page in the browser. Capybara's server middleware records it, and because `Capybara.raise_server_errors` defaults to true, it re-raises it in the test thread: when a following Capybara query fails, on the next `visit`, or at the latest when the session is reset in teardown. The test therefore reports the real exception rather than only a confusing "element not found". ## Clean-up between tests Rails' system-test teardown takes a failure screenshot and then calls `Capybara.reset_sessions!`, before the test's database transaction is rolled back. Resetting returns the browser to a blank page, then waits for requests still running in Puma to finish (raising if they take more than 60 seconds) and re-raises any server error. Without that wait, a request still running could write after the rollback and leak into the next test. ## Remote browsers When Chrome runs in another container or machine, it cannot reach `127.0.0.1` inside the test process. `served_by host: "0.0.0.0", port: 3001` sets `Capybara.server_host` and `Capybara.server_port` so the server listens where the browser can reach it, and the app's URLs must use a host name the browser can resolve. rspec-rails 8 added `served_by` support for system specs too. ## Summary - One process, two threads, plus an external browser. - Shared: DB connection, Ruby stubs, time travel, ENV. - Not shared: thread-local state and the browser's own clock. - Concurrent: always wait on the page before checking results.
- Why does travel_to in a system test not change a JavaScript countdown on the page?`travel_to` stubs Ruby's time methods inside the test process, which includes the Puma thread, so server-rendered times move. The countdown runs in Chrome, a separate process with its own clock, so `Date.now()` there is unaffected; render the deadline from the server or control the clock in JavaScript.
- Why does an exception in a controller surface in a system test as that exception rather than only a missing-element error?Capybara's server middleware records errors from the app. With `Capybara.raise_server_errors` set to true, its default, the test thread re-raises the recorded error when a following query fails, on the next `visit`, or during session reset in teardown, so the failure names the real error and backtrace.
- The browser test talks to a separately deployed server process
- travel_to also moves the clock in the browser's JavaScript
- The Puma thread cannot see records created before visit
- click_on blocks until the server has committed the change
- rack_test also starts Puma in a background thread