In a Rails 8.1 app, how do you add and run a system test, and what does ApplicationSystemTestCase with driven_by set up?
answer
- a real browser against a real server
- bin/rails generate system_test
- ActionDispatch::SystemTestCase plus Capybara::DSL
- headless_chrome, 1400 by 1400
- bin/rails test skips test/system
basics
~10 sA 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 sA 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 linesbin/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 systemgo deeper
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.
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.
Decide how many system tests a feature deserves and how CI runs them separately, given their cost and fragility compared with integration tests.
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.