Integration testing in Bike Index
Browser specs (type: :system, :js) live in two places: feature flows under spec/integration/ and component-level interaction specs at spec/components/**/*_system_spec.rb. Both drive a real Chromium session through capybara-playwright-driver (spec/support/capybara.rb) and pay a browser boot cost per example, so the same conventions apply to both: optimize for fewer, denser examples and high-level Capybara helpers. Always tag new specs with :js, type: :system.
The general context/let style and "what to test" rules are in the rspec-testing skill — the rules below extend it for the system-spec case.
Always follow the real user path
If a user does it in the UI, the spec does it in the UI — every step, including setup. FactoryBot.create(:bike, …) to skip a complicated form turns the spec back into a model test and passes silently when the form is broken.
If the UI path is hard, that's a real signal — usually a production bug (stale asset cache, missing seed data, wrong API URL). Fix the root cause; don't execute_script or factory around it. When it's intermittent rather than hard, the same principle applies with sharper teeth — see fixing-flaky-failures, which owns flake diagnosis and the rule that coverage is never what gives way.
form.requestSubmit() and clicking the submit button aren't the same event either: Turbo re-enables the submitter when a submission finishes, so a programmatically submitted form has no button to re-enable and looks correctly disabled, while the same code under a real click leaves the button live. This bites hardest when verifying rather than setting up.
Legitimate exceptions: reference data that exists in production via migrations, admin accounts outside the user flow, and stubs for genuinely external services (third-party APIs, Stripe, geocoders).
A step the browser never performs — a server-to-server token exchange, a webhook callback — goes over real HTTP to Capybara's own server rather than through the page: Net::HTTP.post_form(URI.join(Capybara.current_session.server.base_url, "/oauth/token"), params). VCR's ignore_hosts covers localhost, so it isn't blocked. spec/integration/oauth_spec.rb is the pattern.
One it per setup; many assertions per it
The rspec-testing skill's "One example per distinct setup" rule, with the browser boot cost on top: a long, sectioned-with-comments example pays one boot, four short examples pay four.
Combine same-setup work, even when scenarios feel independent. Before writing a new describe/context/it, read the existing file and find an example whose fixtures and initial visit match what you need — then append your clicks/assertions to it. It's tempting to leave a separate it for things that feel like different concerns ("button-state test", "filter-persistence test", "URL-param test", "mobile-layout test"). Don't. Failure attribution is fine — the failed line number tells you exactly which phase broke. Only add a new block when the setup genuinely differs.
Measure before consolidating — a fixed sleep usually outweighs the boots
Browser boot is real, but it is rarely what makes a slow file slow. Time the file before
merging anything: a wait_for_timeout/sleep sized to cover the slowest case is typically
most of the runtime, and merging examples doesn't touch it. Consolidating the two
ui/button* specs saved ~2s of the 44s they took; replacing one 400ms
settle saved the other ~32s.
Wait on the condition instead, capped so a cancelled or infinite animation can't hang the
example. settle_animations in spec/support/integration_spec_helpers.rb is the one to reach for
when a measurement follows a state change — it awaits the element's own transitions and races
them against the cap as a ceiling. Prove the wait is load-bearing before trusting it — drop the
cap to 1ms and the assertions it protects should fail.
element.evaluate_script may return a Promise; the driver awaits it before handing back.
A negative matcher can't wait for a state to settle
have_no_css/have_no_link match the instant the condition holds, so a state that arrives
late — a class an orphaned setTimeout re-adds — never gets asserted, and the example
passes against the bug it was written for. Wait on a positive signal the sequence drops last,
then assert the absence: spec/integration/mobile_nav_menu_spec.rb waits out
nav.primary-header-nav.enabled before asserting menu-in is gone.
Carry state forward, don't reset between phases
You know what state the page is in after each click — write the next assertion against that state. Don't click a "Reset" / "Clear" between phases just to get a clean slate; resets cost a click (often two — clear, then re-establish), obscure what's actually happening, and tempt you to think of each phase as an isolated scenario rather than as one continuous user flow.
If a carried-over state makes the next assertion awkward, that's information: usually you can reorder or rephrase phases so the previous phase's end state is exactly what the next phase needs to start from. Treat the example as a flow with state advancing through it, not a sequence of independent scenarios each demanding a pristine baseline.
visit page.current_url is a reload, not a reset — use it specifically to verify URL persistence across a fresh page load. Otherwise, prefer letting state flow.
Navigate by clicking, not re-visiting
After the initial visit in before, prefer clicking to get to the next state. Re-visiting bypasses the very thing system specs exist to verify (client-side state, JS handlers, history, ARIA wiring).
Re-visit only when you specifically want to verify URL persistence / reload behavior — and make that intent explicit (visit page.current_url with a comment, or a context named "after reload").
# Good — drive the flow with clicks
visit "/search/marketplace"
fill_in "Manufacturer", with: "Yuba"
click_button "Search"
# Good — explicit reload to verify URL persistence
visit page.current_url
# Bad — re-rendering that should have been a click/form submit
visit "/search/marketplace?manufacturer=Yuba"
Prefer named matchers over CSS selectors and JS
Capybara's high-level helpers find elements by visible role + text. They are more readable, more accessible (they only see what a real user can interact with), and less brittle than scraping selectors. Reach for low-level tools only when the high-level ones can't express what you need.
Order of preference:
- Named-element helpers:
click_button("Search"), click_link("Next"), find_button(...), have_button(...), fill_in("Manufacturer", with: ...).
- Role-scoped Capybara finders:
find(:button, "..."), within(:section, "Filters") { ... }.
- ARIA / data attributes when there is no visible text:
find('[aria-label="..."]'), find('[data-test-id="..."]').
- CSS selectors as a last resort.
page.execute_script only when the browser fundamentally cannot otherwise do what the test needs (synthesizing custom events, scrolling for IntersectionObserver, etc.).
If a button has no visible text (icon-only, etc.), add an aria-label to the component rather than scraping a selector in the test.
Good
click_button("Search")
expect(find_button("Sort")["aria-pressed"]).to eq "true"
expect(page).to have_link("Next")
Bad
find('[data-action="click->search#submit"]').click
expect(page).to have_css('button[aria-pressed="true"]')
page.execute_script("document.querySelector('.search-btn').click()")
Clicking a top-nav link by its label is ambiguous — the footer repeats Marketplace, Blog, Donate and most of the rest, so scope it: within("#primary-main-menu") { click_link "Marketplace" }. The navbar renders each of those twice more, mobile and desktop, but only one is visible at a given width, so that isn't what the Ambiguous names.
When repeated assertions get noisy, define small DSL-style helpers in the file (def listing_for(item), def thumbnail_selector(...)) — they read better than scattered selectors and keep you out of page.execute_script. Check spec/support/integration_spec_helpers.rb before writing one, and move it there once a second spec wants the same one.
Component system specs must assert accessibility
A component system spec (spec/components/**/*_system_spec.rb) exists to verify a component renders and behaves correctly in a real browser — and "correctly" includes being accessible. Every component system spec must call expect_axe_clean at least once, after the component has rendered (and after any state change that swaps in new markup — a new field, an opened menu, an added row). The axe audit catches missing accessible names, bad ARIA, and broken label associations that no CSS-selector assertion would.
Treat an axe failure as a real bug in the component, not noise to silence: fix the markup (add the aria-label, associate the <label>, correct the role) rather than narrowing the audit. The shared helper disables a handful of rules (spec/support/axe.rb) — preview artifacts plus colour contrast — so a remaining violation is almost always genuine.
visit "/rails/view_components/ui/forms/text_editor/component/default"
expect(page).to have_css("lexxy-editor lexxy-toolbar", wait: 10)
expect_axe_clean
# ...and again after anything that swaps in new markup - an opened menu, a cloned row
expect_axe_clean
A preview is not the page
A preview renders the component alone, so everything the surrounding page
contributes is absent: autofocus on the form, sibling Stimulus controllers,
Turbo, the rest of the layout. Behaviour that depends on any of those can pass
against the preview while the real page stays broken — the preview spec isn't
wrong, it just can't see the condition.
The layout is component_preview, which loads Tailwind and the importmap but
not application_revised — no jQuery, no bootstrap — and includes the legacy
stylesheet only when the URL carries Lookbook's display option
(?lookbook%5Bdisplay%5D%5Blegacy_stylesheet%5D=true, see the
frontend-screenshots skill). So anything
driven by legacy JS can't be exercised from a preview at all, and anything styled
by a legacy stylesheet renders unstyled without that parameter — which makes every
visibility and responsive assertion meaningless. Cover both on a real page.
A combobox fix keyed off the focus event passed
spec/components/ui/forms/combobox/component_system_spec.rb while step 1 of the
register flow was still mangling its manufacturer field: that form is
autofocus, so the input already held focus and the rider's entering click
brought no focus event to hang the selection on. Keep the preview spec for what
the component does on its own, and cover page-level behaviour in the flow's own
spec under spec/integration/ — where the autofocus, the Turbo frame and the
other controllers are all present.
A component system spec drives the preview route, so the preview template is
that spec's fixture — editing one changes what the spec starts from. Making the
parking-notification preview open its panel on load broke
spec/components/pages/registrations/show/org_top_actions/parking_notification_form/component_system_spec.rb,
which asserts the submit is disabled before the accordion is touched; the failure
named the button, not the preview. Give the preview a param for the state the
spec needs (ComponentPreview#default takes panel:) rather than dropping the
assertion.
ActionCable broadcasts: do the real thing
The test cable adapter is :async, so broadcasts in the test process do round-trip to the browser. Don't synthesize turbo:morph-element events with execute_script to fake an ActionCable refresh — call the real broadcaster (Component.broadcast_replace_to, broadcast_refresh_later_to, etc.) and let Capybara's wait do the synchronization.
The pattern is: prepare the data the broadcast will render → call the real broadcaster → assert on an unambiguous post-morph element with a wait: (e.g. expect(page).to have_css(some_new_selector, wait: 5)). The trailing wait is the synchronization barrier — the test proceeds only once the morph has actually rendered.
Failing a request on purpose: Playwright routes
page.driver.with_playwright_page { |pw| pw.route(pattern, handler) } is how a spec makes the
server 429, 500 or hang for one request — the app never sees it, so nothing half-saves. Four
things that cost real time when they go wrong:
- The handler runs on a Playwright thread, and a raising handler hangs the request. Nothing
fulfills or continues it, so the page just sits there and the failure surfaces a step later as
a confusing "expected to find …". Keep handlers boring: no
Enumerator#next ([429, 500].cycle
raises fiber called across threads), nothing that assumes the RSpec thread. Derive what varies
from state you can read, e.g. failures.length.odd? ? 429 : 500.
- Every Rails form submission is a POST over the wire, so the HTTP method can't tell
create
from update — Rails' _method override lives in the body, and a multipart body (any form with
a file input) turns Rack::Utils.parse_query(request.post_data) into garbage. Key on the page the
request came from instead: request.headers["referer"] carries the step in its query string.
- Collect what you intercepted and assert on it at the end. A list of the requests you failed,
compared against the exact list you expected, is what proves each one was hit — and hit once.
Without it a key collision quietly means half your interceptions never happened.
- A client-side timer you lengthen outruns Capybara's default wait.
default_max_wait_time is
2 seconds here, so a retry/debounce stretched to 3s needs an explicit wait: on the next
assertion. Use wait_for { ... } (in IntegrationSpecHelpers) to block on something only the browser
knows — a route handler's record of a request it answered — that no Capybara matcher can see.
Build Tailwind before running system specs
Without a current app/assets/builds/tailwind.css, tw:hidden silently doesn't apply and visibility assertions fail in ways that read as flakes. bin/setup builds it; otherwise bin/rails tailwindcss:build (the sandbox-test-setup skill has the rest); see frontend-conventions for the tw: prefix.