Browserless interaction tests for Rails apps built with Stimulus, Turbo and importmap.
rails-jsdom lets you write tests that read like system tests — visit, click_on, fill_in, assert_selector, assert_text — without Capybara, a test server or a browser. Your real pages render through Rails, your real Stimulus controllers and Turbo run in jsdom, and every request the page makes is answered by Rails in the same test process. Tests run deterministically, fail on JavaScript errors, and in 37signals' open-source apps ran 1.8x to 16.5x faster than the same tests as system tests.
Using a coding agent? Point it at the instructions for coding agents, also published as Markdown at https://jakehow.github.io/rails-jsdom/agents.md. They cover setting the gem up, writing interaction tests, and converting a system test suite.
class CartInteractionTest < RailsJsdom::TestCase
test "adding an item updates the cart through its Turbo Stream" do
sign_in_as users(:shopper)
visit product_path(products(:mug))
fill_in "Quantity", with: 2
click_on "Add to cart"
assert_dom "#cart-count", text: "2"
assert_text "Added to your cart"
end
end- How it works
- Results on 37signals' open-source apps
- Trade-offs compared with system tests
- Requirements
- Installation
- Writing tests
- API
- Action Cable and Turbo Stream broadcasts
- Timers and time
- Continuous integration
- Troubleshooting
- Limitations
- Contributing
- License
- Each test worker starts one persistent Node process running jsdom.
- Node bundles your importmap's
applicationmodule and your Stimulus controllers once with esbuild, from your app's own importmap, so the versions under test are the ones your app ships. visitmakes a real Rails request and loads the response into a jsdom window. Yourapplicationmodule runs, Turbo and Stimulus boot, and controllers connect in the same order as withstimulus-loadingin a browser.- Every
fetchandXMLHttpRequestthe page makes, including Turbo visits, form submissions, frames and direct uploads, is answered by Rails in the same process, with the test's session. - After every action, the page settles: timers run on a virtual clock, Action Cable messages are delivered, and pending requests finish. Assertions then read the live DOM, so there is nothing to wait for.
- JavaScript errors, unhandled rejections, Stimulus errors and unexpected dialogs fail the action that caused them.
We moved the system tests of Campfire, Fizzy and Writebook to interaction tests wherever possible. The times compare only the tests that moved, each as a system test against the interaction test that replaced it, in one process on one machine.
| App | System tests | Moved | Moved tests as system tests | As interaction tests | Speedup |
|---|---|---|---|---|---|
| Campfire | 30 | 28 | 317.7s | 19.3s | 16.5x |
| Fizzy | 47 | 18 | 21.5s | 9.6s | 2.2x |
| Writebook | 3 | 3 | 6.8s | 3.7s | 1.8x |
Campfire gains the most because its system tests spend most of their time in Capybara calls that block until a timeout. The tests that stay system tests need layout, a canvas, screenshots or other things a browser engine does. The full results (source) cover how we measured, the bugs found, the changes each app needed, and why each remaining system test stays.
What you gain
- Speed. No browser, no test server, no Chrome.
- Determinism. Ruby and the page share one virtual clock and Action Cable runs in the test's thread, so there are no sleeps, waits or retries, and a slow machine does not change what a test sees.
- Real code paths. Real controllers, views, Stimulus controllers, Turbo and session; only the browser engine is replaced.
- Clear failures. A JavaScript error or an unexpected dialog fails the test instead of being swallowed.
What you lose
jsdom runs the DOM and JavaScript but does not lay out or paint pages. Keep a few system tests for:
- Computed CSS, responsive breakpoints and themes that only change CSS.
- Layout and geometry. Every element measures 0x0 at 0,0. If a page waits for a real measurement, such as a menu placed at the caret, the action fails with an error that says so. When position does not matter to the test, give the elements a box with
stub_layout. - Drag and drop, which finds drop targets from element positions.
- Screenshots and other visual evidence.
Partly supported
- Keyboard input.
send_keysperforms the common browser actions: typing, Backspace, Enter, Space, Tab, and the arrow keys, Home and End in range and number fields. In a contenteditable each key firesbeforeinputandinputand edits at the caret. Moving the caret with keys, selecting text and OS shortcuts are not supported. - Several users. Each
using_sessionhas its own cookies, page and storage, but pages do not run at the same time: a page receives what happened while it was in the background when the test returns to it.
Not supported yet
- Third-party scripts from a CDN. Remote importmap pins load as empty modules. Pins vendored with
bin/importmap pin --downloadwork. - iframes and new windows. Turbo Frames work. Check a
target="_blank"link withassert_link, thenvisitit.
- Ruby 3.3, 3.4 or 4.0
- Rails 8.1 with
importmap-rails,propshaft,turbo-railsandstimulus-rails - Stimulus controllers under
app/javascript/controllers, named*_controller.js - Node.js 22.22.2+, 24.15+ or 26+, the supported LTS lines that jsdom 31 runs on
CI also runs the suite against edge Rails.
group :test do
gem "rails-jsdom"
endbundle install
bin/rails generate rails_jsdom:installThe install generator adds require "rails_jsdom" to test/test_helper.rb, creates test/interactions/, adds jsdom and esbuild to package.json and runs npm install (pass --skip-npm to run it yourself). Running it again changes nothing that is already set up.
It also protects you from compromised npm releases:
package.jsonallows newer minor and patch releases of jsdom and esbuild, never a new major version..npmrcgetsmin-release-age=7, so npm skips versions published in the last 7 days. This needs npm 11.10 or later, and the generator warns if yours is older.- Commit
package-lock.jsonand usenpm ciin CI, so new versions only arrive when someone updates and commits them.
Inherit from RailsJsdom::TestCase, which is an ActionDispatch::IntegrationTest, so fixtures, sign_in helpers that post to your session controller, perform_enqueued_jobs and all Rails assertions work as usual.
class ProjectFilterInteractionTest < RailsJsdom::TestCase
setup do
sign_in_as users(:owner)
visit projects_path
end
test "filtering by name leaves one card visible" do
fill_in "search", with: "Billing"
assert_dom "[data-project-filter-target=card]:not([hidden])", count: 1
end
endTurbo forms and Turbo Stream responses are applied before the action returns. Requests to other hosts fail like a network error, so a page cannot reach the internet.
The full API reference is at jakehow.github.io/rails-jsdom. Every helper is documented in RailsJsdom::TestHelper, with the locator rules, filters, scoping, dialogs and settling.
| System test method | Status | Notes |
|---|---|---|
visit |
✅ | |
refresh |
✅ | Requests the current URL again, without a history entry |
go_back, go_forward |
✅ | Across Turbo Drive visits and full page loads |
using_session |
✅ | Each session has its own cookies and page; broadcasts reach a session's page when the test returns to it |
click_on, click_link_or_button |
✅ | A button also matches by its name, as in system tests. Without a locator, clicks the only link or button in the current within scope |
click_link |
✅ | Without a locator, clicks the only link in the current within scope |
click_button |
✅ | Without a locator, clicks the only button in the current within scope, as in system tests |
fill_in |
✅ | Text-like fields only, as in system tests |
check, uncheck |
✅ | |
choose |
✅ | |
select, unselect |
✅ | |
attach_file |
✅ | Forms submit files to Rails as multipart requests. The block form, attach_file(paths) { click_on "Upload" }, answers the file chooser a script opens. Hidden file fields work, so make_visible: raises an error that says to remove it |
send_keys |
✅ | Keys perform the common browser default actions; typing happens at the end of the value, with no caret or selection. Key names are the system test ones, including :arrow_down and :return |
within |
✅ | CSS selector or an element from find; also scopes assert_dom |
within_fieldset, within_table |
✅ | |
find, all, first |
✅ | text:, exact_text:, visible:, id:, class: (a list, with "!name" excluding a class) and the field filters; without a selector they match any element |
find_field, find_button, find_link |
✅ | with:, checked:, unchecked:, disabled:, href:, type: |
Element .click, .set, .text, .value, .[], .checked?, .selected?, .disabled?, .visible?, .send_keys, .select_option, .hover |
✅ | Plus the finders and assertions inside the element; using an element that left the page raises |
page |
✅ | Every helper, plus body and title |
assert_text, assert_no_text, refute_text |
✅ | String or Regexp |
assert_selector, assert_css |
✅ | Counts visible elements, as in system tests; count:, minimum:, maximum: |
assert_no_selector, assert_no_css, refute_selector |
✅ | |
assert_field, assert_no_field |
✅ | |
assert_checked_field, assert_unchecked_field |
✅ | |
assert_button, assert_no_button |
✅ | Disabled buttons match only with disabled: |
assert_link, assert_no_link |
✅ | |
assert_current_path, assert_no_current_path |
✅ | ignore_query:, url:, Regexp |
assert_title, assert_no_title |
✅ | |
has_text?, has_content?, has_no_text?, has_no_content? |
✅ | |
has_selector?, has_css?, has_no_selector?, has_no_css? |
✅ | |
has_field?, has_no_field?, has_checked_field?, has_unchecked_field? |
✅ | |
has_button?, has_no_button?, has_link?, has_no_link? |
✅ | |
has_current_path?, has_no_current_path?, has_title?, has_no_title? |
✅ | |
current_path, current_url |
✅ | |
evaluate_script |
✅ | Awaits a returned promise; extra arguments arrive as arguments, elements as DOM elements, and an element's own evaluate_script runs with this set to it |
execute_script |
✅ | Extra arguments as in evaluate_script; also on an element |
accept_alert |
✅ | An unexpected alert fails the test |
accept_confirm, dismiss_confirm |
✅ | An unexpected confirm fails the test |
accept_prompt, dismiss_prompt |
✅ | An unexpected prompt fails the test |
hover, double_click, right_click |
✅ | Element methods in system tests; here they also take a locator. CSS :hover styles do not apply |
within_frame |
❌ | Not planned: real iframes are mostly cross-origin; Turbo Frames already work |
within_window, switch_to_window |
❌ | Not planned: check a target="_blank" link with assert_link, then visit it |
drag_to |
❌ | Never: drag-and-drop needs layout, which jsdom does not have |
take_screenshot |
❌ | Never: jsdom does not render pages |
Waiting (default_max_wait_time, retrying assertions) |
— | Not needed: the page settles before every action and assertion. A wait: option raises an error that says to remove it, and any other option a method does not support raises an ArgumentError that names it |
| Method | What it does |
|---|---|
click |
Clicks any element by locator, including Stimulus action shorthand (click "dropdown#toggle") |
mount_partial |
Renders a partial and loads it as a page, with no route |
mount_html |
Loads an HTML fragment as a page |
stub_fetch |
Answers a page request without Rails |
stub_layout |
Gives elements matching a selector, and ranges inside them, a box instead of 0x0, for a test whose page waits for a real measurement |
page_text |
The visible text of the page or the current within scope |
assert_dom, assert_select and css_select work as in any Rails test and read the live page.
A page's WebSocket connects to your app's real Action Cable server, in the test process, with the test session's cookies. Your ApplicationCable::Connection and channels run as in production, and pages that use turbo_stream_from or your own consumers receive what the server sends:
test "a new comment appears for everyone watching the task" do
visit task_path(tasks(:open))
perform_enqueued_jobs { Comment.create!(task: tasks(:open), body: "Looks good") }
assert_text "Looks good"
end- Action Cable runs in the test's thread. Every message, including each broadcast, is ready for the page before the call that caused it returns, and arrives before the page's next timer.
assert_broadcastsandassert_broadcast_onkeep working.- Broadcasts must come from the test, from a request the page makes, or from
perform_enqueued_jobs. A broadcast from another thread fails the test with an explanation. - An error in connection or channel code that no
rescue_fromhandles fails the test, with the error and its backtrace. Action Cable would only log it.
setTimeout,setIntervalandrequestAnimationFramerun on a virtual clock. After each action, timers due within one second run; timers further out, such as polling, stay pending.- Ruby and every page share the clock. Ruby's time is frozen at the start of each test, the page's
Dateandperformance.now()follow the clock, and timestamps the server writes agree with the page. travelandtravel_tomove the pages too, running the timers due on the way in order.- Action Cable's heartbeat and channels'
periodicallytimers run on the same clock.
CI needs Node and your app's npm packages before the tests run:
- uses: actions/setup-node@v7
with:
node-version: 26
- run: npm ci
- run: bin/rails test- Node output and page console messages go to
Rails.logger, prefixed with[rails_jsdom](by default inlog/test.log). Cannot find module 'jsdom': runnpm install --save-dev jsdom esbuildin the app, andnpm ciin CI.- "The RailsJsdom Node process exited" or a page that never stops: see the
[rails_jsdom]lines in your log. A command that gets no answer withinRailsJsdom.command_timeoutseconds (default 30) fails, and the next command starts a new Node process. - An exception in your Rails code while answering a page request fails the test with that exception.
- An element is not found: check the locator rules, or scope with
within.
See what you lose. In addition:
- jsdom lacks some browser APIs, so the runtime stubs the common ones to keep controllers working:
matchMedianever matches,IntersectionObserverandResizeObservernever report, scrolling does nothing, stylesheets and images fireloadwithout being fetched, and the clipboard, Fullscreen API,DataTransferand form-associated custom elements are provided. The page behaves as a desktop browser without touch. A page that needs another missing API needs a small stub in your controller or test. - On a page loaded with
mount_html, a link or form that leads to a full app page fails. Start such tests from a real page withvisit. - Stimulus outlets are not tested yet.
MIT — see LICENSE.