Instructions for coding agents

This page is for an AI coding agent working in a Rails app that uses, or is moving to, rails-jsdom. It covers setting the gem up, writing interaction tests, and converting an existing system test suite. The full API reference is at jakehow.github.io/rails-jsdom/. This page is also published as Markdown at jakehow.github.io/rails-jsdom/agents.md.

What rails-jsdom is

• Interaction tests for Rails apps that use importmap, Turbo and Stimulus, without a browser or a test server.

• Rails renders the real pages. The real Stimulus controllers and Turbo run in jsdom, in one Node process per test worker.

• Every request the page makes (fetch, Turbo Drive visits, form submissions) is answered by Rails inside the test process, in the test’s session.

• The helpers use the system test method names: visit, click_on, fill_in, within, accept_confirm, assert_selector, find and so on.

Set up an app

1. Add gem "rails-jsdom" to the :test group of the Gemfile and run bundle install.

2. Run bin/rails generate rails_jsdom:install. It:

3. requires the library in test/test_helper.rb;

4. creates test/interactions/;

5. adds jsdom and esbuild to package.json and runs npm install;

6. sets min-release-age=7 in .npmrc;

7. ignores node_modules;

8. warns if config/cable.yml does not use the test adapter in the test environment.

9. Make CI install the Node packages before the tests, with npm ci after setting up Node 22 or later.

10. Commit package.json, package-lock.json and .npmrc.

Write an interaction test

require "test_helper"

class CartInteractionTest < RailsJsdom::TestCase
  setup do
    sign_in_as users(:shopper)
    visit product_path(products(:mug))
  end

  test "adding an item updates the cart" do
    fill_in "Quantity", with: 2
    click_on "Add to cart"

    assert_selector "#cart-count", text: "2"
    assert_text "Added to your cart"
  end
end

• Put the test in test/interactions/ and subclass RailsJsdom::TestCase. It is an ActionDispatch::IntegrationTest, so fixtures, perform_enqueued_jobs and Rails assertions work.

• Sign in the way the app’s integration tests do, usually by posting to the session controller.

• Every action settles the page before it returns: timers up to one second ahead have run, no request is pending, and Turbo Stream broadcasts have been applied. Never add sleep, waits or retries.

• A JavaScript error, an unhandled promise rejection or an unexpected alert, confirm or prompt fails the action. Wrap actions that show a dialog in accept_alert, accept_confirm, dismiss_confirm, accept_prompt or dismiss_prompt.

• assert_selector and find count only visible elements unless you pass visible: false. assert_dom and assert_select see every element.

• Requests to other hosts fail like a network error. Answer them with stub_fetch after the page loads.

• Broadcasts made with broadcast_*_later arrive when the test performs the jobs, for example perform_enqueued_jobs { click_on "Post" }.

• using_session(:name) { ... } runs a block as another user with their own cookies and page.

Convert a system test suite

Work through test/system/ one file at a time.

1. Sort each test. Convert it if it checks behaviour: what the page shows, what is hidden, where it navigates, what Rails receives. Keep it as a system test, or delete it, if it needs what jsdom cannot do:

2. computed CSS, layout or geometry;

3. CSS media-query breakpoints;

4. screenshots;

5. drag and drop;

6. real iframes or new windows;

7. custom ActionCable channels;

8. third-party scripts from a CDN.

9. Move the file from test/system/ to test/interactions/, and change the test class’s superclass from ApplicationSystemTestCase to RailsJsdom::TestCase.

10. Remove browser setup: driven_by, using_wait_time, Capybara.* settings, sleep, wait_for_* helpers, take_screenshot and window-size code.

11. Replace sign-in. System tests often sign in by filling in the login form. That still works. A faster equivalent is the app’s integration-test helper that posts to the session controller.

12. Translate the methods with the table below. Most methods keep their names. The common changes:

13. CSS or layout assertions become behaviour assertions (assert_selector ".panel[hidden]", not checks of display or position);

14. page.driver and browser-specific calls are removed;

15. send_keys is limited to the keys listed in the table notes.

16. Run the converted file with bin/rails test test/interactions/<file> and fix any failure before moving on. Typical failures:

17. an unexpected dialog: wrap the action in the matching accept_* or dismiss_*;

18. a request to another host: stub it with stub_fetch;

19. a missing browser API: stub it in the test with execute_script;

20. an element found more than once: scope it with within or pass match: :first.

21. When test/system/ is empty, remove ApplicationSystemTestCase, the capybara and selenium-webdriver gems, and the CI steps that installed a browser.

Interaction tests are faster than system tests, so do not merge tests to save time. Keep one behaviour per test. Group checks of the same result into one test only when they would otherwise repeat the same steps.

System test methods in rails-jsdom

✅ works in rails-jsdom. ❌ does not. Each link goes to the method’s reference.

Limits

• No layout or painting. Computed CSS, geometry, breakpoints, screenshots and drag and drop cannot be tested.

• Stubbed browser APIs. jsdom lacks some browser APIs, so rails-jsdom stubs these: matchMedia never matches, IntersectionObserver and ResizeObserver never report, scrolling does nothing, and navigator.clipboard drops writes. A page that needs another missing API needs a stub in the test.

• Remote importmap pins load as empty modules. Vendor a pin with bin/importmap pin --download to test it.

• Requirements: Ruby 3.3, 3.4 or 4.0, and Rails 8.1 with importmap, Propshaft, Turbo and Stimulus. Stimulus controllers must live under app/javascript/controllers.