skip to content

System Tests & Capybara

System tests drive a real browser through Capybara against a server thread, set up with driven_by. Interviewers probe auto-waiting versus sleeps, data visibility across threads and flakiness.

part ofRuby on Railsread it →
on this pageshow

explore

questions

5

In a Rails 8.1 app, how do you add and run a system test, and what does ApplicationSystemTestCase with driven_by set up?

level: juniorimportance: must knowfreq 56%

answer

  1. a real browser against a real server
  2. bin/rails generate system_test
  3. ActionDispatch::SystemTestCase plus Capybara::DSL
  4. headless_chrome, 1400 by 1400
  5. bin/rails test skips test/system

basics

~10 s

A system test subclasses ApplicationSystemTestCase, which inherits ActionDispatch::SystemTestCase and calls driven_by :selenium, using: :headless_chrome. bin/rails generate system_test creates both files in Rails 8.1, and bin/rails test:system runs them; plain bin/rails test skips them.

solid answer

~40 s

A system test drives a real browser through Capybara against the app served by Puma inside the test process. `ApplicationSystemTestCase` inherits `ActionDispatch::SystemTestCase`, which mixes in `Capybara::DSL` and Capybara's Minitest assertions, and its one line, `driven_by :selenium, using: :headless_chrome, screen_size: [ 1400, 1400 ]`, picks the driver, browser and window size. Tests live in `test/system` and use `visit`, `fill_in`, `click_on` and waiting assertions such as `assert_selector` and `assert_text`. In Rails 8.1, scaffolds stopped generating system tests (8.1.0) and `rails new` stopped writing `test/system` and the base class unless a dev container is generated (8.1.2); `bin/rails generate system_test seat_selections` creates the base class if missing plus `test/system/seat_selections_test.rb`. `bin/rails test` leaves system tests out; run them with `bin/rails test:system`.

code

bash · 4 lines
bash
bin/rails generate system_test seat_selections
bin/rails test:system                       # only test/system
bin/rails test test/system/seat_selections_test.rb
bin/rails test:all                          # unit, integration and system

go deeper

for a junior

Recall the base class, the driven_by line, the generator and bin/rails test:system, and write a test with visit, fill_in, click_on and assert_text.

for a middle

Explain what SystemTestCase mixes in, what driven_by's keywords mean and the fallback when it is missing, plus the 8.1 changes to what generators write.

for a senior

Decide how many system tests a feature deserves and how CI runs them separately, given their cost and fragility compared with integration tests.

for a principal

Set the suite's policy for browser coverage across teams: which flows get system tests, which stay at integration level, and how CI time is budgeted for them.

## What a system test is A **system test** is Rails' name for a browser test. It starts the application on a real HTTP server, opens a browser through a **driver**, and drives the pages as a user would: visiting URLs, filling in fields, clicking buttons and checking what appears. Rails builds this on **Capybara**, the Ruby library that provides the browser-driving vocabulary, and on **Selenium WebDriver** for controlling Chrome or Firefox. The class hierarchy is short: | Class | Comes from | Role | |---|---|---| | `ActiveSupport::TestCase` | Rails | Minitest base with fixtures and Rails assertions | | `ActionDispatch::SystemTestCase` | Rails | includes `Capybara::DSL`, `Capybara::Minitest::Assertions`, screenshot and teardown helpers | | `ApplicationSystemTestCase` | your app, `test/application_system_test_case.rb` | calls `driven_by` once for every system test | | `SeatSelectionsTest` | your app, `test/system/` | the actual tests | ## The generated base class ```ruby require "test_helper" class ApplicationSystemTestCase < ActionDispatch::SystemTestCase driven_by :selenium, using: :headless_chrome, screen_size: [ 1400, 1400 ] end ``` `driven_by` takes the Capybara driver name first, then keywords: - `using:` the browser, `:chrome` by default; `:headless_chrome`, `:firefox` and `:headless_firefox` are the other built-in choices. - `screen_size:` the window size, `[1400, 1400]` by default. - `options:` extra driver options, and an optional block that receives the browser options object for flags such as device emulation. If a test class never calls `driven_by`, `SystemTestCase` falls back to `driven_by(:selenium)`, which opens a visible Chrome window. Rails also tells Capybara to use Puma as the server, with the port always included in generated URLs. ## Rails 8.1 changes to what you get Two releases changed the starting point, which is why an interviewer may hear "my new app has no system tests folder": 1. **8.1.0:** the scaffold generator no longer writes system tests unless you pass `--system-tests=true`. 2. **8.1.2:** `rails new` no longer writes `test/system` or `test/application_system_test_case.rb`, except when it also generates a dev container. The Gemfile still gets `capybara` and `selenium-webdriver` in the `:test` group unless the app is API-only or skips system tests. The way in is the generator: ```bash bin/rails generate system_test seat_selections # creates test/application_system_test_case.rb (if missing) # creates test/system/seat_selections_test.rb ``` ## Writing the first test ```ruby require "application_system_test_case" class SeatSelectionsTest < ApplicationSystemTestCase test "picking a seat for an evening screening" do visit screening_url(screenings(:evening)) click_on "B7" fill_in "Email", with: "[email protected]" click_on "Book seat" assert_text "Seat B7 booked" end end ``` The pieces worth naming: - `visit` loads a URL in the browser; route helpers ending in `_url` include the test server's host and port. - `fill_in "Email", with: ...` finds a field by label, name, id or placeholder. - `click_on` clicks a link or a button with that text; it is an alias of `click_link_or_button`. - `assert_text` and `assert_selector` **wait** for the expected content, up to Capybara's `default_max_wait_time` of 2 seconds, which is what makes them safe after a click. ## Running them - `bin/rails test` runs everything except system tests. - `bin/rails test:system` runs only `test/system`. - `bin/rails test:all` runs both. The generated CI workflow file has a separate system-test job that keeps failure screenshots, while `config/ci.rb` for `bin/ci` leaves its system-test step commented out. Both choices reflect the same trade-off: system tests are the slowest and most fragile layer, so they run separately and are kept few. ## What it inherits from test_helper `application_system_test_case.rb` starts with `require "test_helper"`, and `ActionDispatch::SystemTestCase` is a subclass of `ActiveSupport::TestCase`. Everything the generated `test_helper.rb` configures there therefore applies to system tests as well: - `fixtures :all`, so `screenings(:evening)` and `seats(:b7)` are available by label. - `parallelize(workers: :number_of_processors)`, so system tests are spread over worker processes, each with its own Capybara session and browser. - Any helper methods added to `ActiveSupport::TestCase`, such as a sign-in helper. ## What belongs in a system test System tests are the slowest and most timing-sensitive tests in a Rails suite, so they are kept for what only a browser can show: - flows that depend on JavaScript, such as a Stimulus seat picker or a Turbo Frame; - confirm dialogs, focus and visibility that the server cannot judge; - one happy-path check of a critical journey, such as booking a seat end to end. Validation rules, authorisation and JSON responses are cheaper and more precise in model and integration tests. ## Common slips - Inheriting from `ActionDispatch::IntegrationTest` and wondering why `visit` is missing. - Expecting `bin/rails test` to have run the browser tests. - Assuming a fresh 8.1 app already has `test/system`.

  • What happens if a system test class never calls driven_by?
    `ActionDispatch::SystemTestCase` calls `driven_by(:selenium)` for it when the first test is instantiated. That means Selenium with Chrome, not headless, at 1400 by 1400. On a CI machine without a display this usually fails, which is why the generated base class asks for `:headless_chrome` explicitly.
  • Why does a new Rails 8.1 app have capybara in the Gemfile but no test/system folder?
    Rails 8.1.2 stopped writing the system-test files during `rails new` unless a dev container is generated, but the Gemfile template still adds `capybara` and `selenium-webdriver` when system tests are not skipped. Running `bin/rails generate system_test` creates the missing base class and the first test file.

  • bin/rails test runs the system tests along with everything else
  • System tests inherit from ActionDispatch::IntegrationTest
  • Every new Rails 8.1 app already has test/application_system_test_case.rb
  • driven_by :selenium with no using: opens Firefox
  • The 8.1 scaffold generator writes a system test for each resource

Assumes Rails 8.1.4: since 8.1.0 scaffolds skip system tests by default, and since 8.1.2 rails new writes no test/system folder or ApplicationSystemTestCase unless it also generates a dev container.

open as a page

With Capybara in a Rails system test, which finders and assertions wait for the page, and which read it once and race the browser?

level: middleimportance: must knowfreq 55%

basics

~20 s

Capybara's find, assert_selector, assert_text, assert_no_selector and assert_current_path retry for up to default_max_wait_time, 2 seconds. Plain reads such as page.current_path, element.text compared with ==, refute has_css? or counting all(...) do not wait for the expected state.

open as a page

In a Rails system test, when would you use driven_by :rack_test instead of driven_by :selenium, using: :headless_chrome, and what stops working?

level: middleimportance: should knowfreq 42%

basics

~20 s

driven_by :rack_test drives the app through Rack in the test process, with no browser, server thread or JavaScript, so it is fast for server-rendered pages. Anything needing JavaScript, such as Stimulus, Turbo, confirm dialogs or screenshots, needs Selenium with headless Chrome.

open as a page

A Rails system test that releases a held cinema seat behind a confirm dialog fails one CI run in ten; how do you diagnose and fix it?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Wrap the click in accept_confirm("Release seat B7?") so Capybara handles the dialog, then assert the outcome with a waiting matcher such as assert_selector before touching the database. Read the failure screenshot and HTML in tmp/screenshots, and remove sleeps.

open as a page

In a Rails system test, where does the application run, and what follows from the test and the Puma server sharing one process?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Capybara 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.

open as a page