rails-jsdom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6e708481667ec3be843dfa039b7c931ee9bfd5c9db36befb76db5a73fc380cd
+  data.tar.gz: 9d83fd3debee83c77246658a30b5ebed04d6d1446bba341422f7aed2f8e584d9
+SHA512:
+  metadata.gz: e7a0d5cd8b4718c00f89213eba27ac26d2deca91b3ffaf63b9ab95c0382635d29d0e964ea8c9c1e3b60ecee715d21463ab538aa80a36a86ca78ebffa21ece825
+  data.tar.gz: c572e6c1c3e090904fa6c09f72552c15be245f8b2d3185e35d389110bd3e25e378d89a0e4459616cf04735c4a4adb87905bc7de04703630d6b213e5c839265eb

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- First release.
+- `bin/rails generate rails_jsdom:install` sets an app up: it requires the library, creates `test/interactions`, adds jsdom and esbuild to `package.json` and installs them, ignores `node_modules`, and checks the ActionCable test adapter. It pins jsdom and esbuild to a major version and sets `min-release-age=7` in `.npmrc`, warning when npm is too old to honour it.
+- `RailsJsdom::TestCase`: interaction tests on `ActionDispatch::IntegrationTest` with the system test methods: navigation (`visit`, `refresh`, `go_back`, `go_forward`, `using_session`), actions (`click_on`, `click_link`, `click_button`, `fill_in`, `check`, `uncheck`, `choose`, `select`, `unselect`, `attach_file`, `send_keys`, `hover`, `double_click`, `right_click`), scoping (`within`, `within_fieldset`, `within_table`), finders and elements (`find`, `all`, `first`, `find_field`, `find_button`, `find_link`, `page`), dialogs (`accept_alert`, `accept_confirm`, `dismiss_confirm`, `accept_prompt`, `dismiss_prompt`), scripts (`evaluate_script`, `execute_script`), and the `assert_*` and `has_*?` assertions for text, selectors, fields, buttons, links, the current path and the title. Plus `click`, `mount_partial`, `mount_html`, `stub_fetch` and `page_text`. `assert_dom` and `assert_select` read the live page.
+- One persistent Node + jsdom process per test worker; Stimulus controllers bundled once per process with esbuild from your importmap.
+- Page `fetch`, Turbo Drive visits and Turbo form submissions are answered by Rails in-process, in the test's session, following redirects.
+- Turbo Stream responses and Turbo Stream broadcasts (`turbo_stream_from`, `broadcast_*`, `broadcast_*_later` performed by the test) reach the page.
+- Deterministic settling on a virtual clock; page errors, unhandled rejections and unexpected alert, confirm and prompt dialogs fail the test.
+- Node output and page console messages are written to `Rails.logger`, prefixed with `[rails_jsdom]`.
+- If Rails raises while answering a page fetch, the exception fails the test and the next command starts a fresh Node process.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Howerton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,351 @@
+# rails-jsdom
+
+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](https://github.com/jsdom/jsdom), and every request the page makes is answered by Rails in the same test process.
+
+Interaction tests written this way can be as much as **4–10x faster** than equivalent Rails system tests, run deterministically, and fail on JavaScript errors. `rails-jsdom` aims to match the API available in system tests that users are already familiar with.
+
+```ruby
+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
+```
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Trade-offs compared with system tests](#trade-offs-compared-with-system-tests)
+- [Requirements](#requirements)
+- [Installation](#installation)
+  - [Supply chain](#supply-chain)
+- [Writing tests](#writing-tests)
+- [API](#api)
+- [Turbo Stream broadcasts](#turbo-stream-broadcasts)
+- [Timers and settling](#timers-and-settling)
+- [Continuous integration](#continuous-integration)
+- [Troubleshooting](#troubleshooting)
+- [Limitations](#limitations)
+- [Development](#development)
+- [License](#license)
+
+## How it works
+
+1. Each test worker starts **one persistent Node process** running jsdom. It stays up for the whole run.
+2. On start, Node bundles every Stimulus controller under `app/javascript/controllers` once with [esbuild](https://esbuild.github.io), resolving `@hotwired/turbo-rails`, `@hotwired/stimulus` and your other pins through your app's importmap and Propshaft load path. The versions under test are exactly the ones your app ships.
+3. `visit` makes a real integration request (`get`), follows redirects, and loads the response HTML into a fresh jsdom window at the request's URL. Turbo and Stimulus boot; controllers connect.
+4. Every `fetch` the page makes — your controllers' own calls, Turbo Drive visits, Turbo form submissions, Turbo Frames — is sent back to Ruby and answered by Rails **in-process**, with the test's cookies and session, following redirects. Turbo then renders the response exactly as it would in a browser, including Turbo Stream responses.
+5. After every action, the runner **settles** the page deterministically: it runs timers on a virtual clock and waits until no Rails request is pending.
+6. Assertions read a snapshot of the live DOM: `assert_dom`, `assert_select` and `css_select` work as in any Rails test because `document_root_element` is the page.
+7. JavaScript errors, unhandled promise rejections, Stimulus errors and unexpected alert, confirm or prompt dialogs fail the action that caused them.
+
+## Trade-offs compared with system tests
+
+**What you gain**
+
+- **Speed.** No browser, no Capybara server, no Puma, no Chrome. A test is a Rails request plus a jsdom page. As much as 4–10x faster than the same behaviour in system tests.
+- **Determinism.** Timers run on a virtual clock and the runner waits for pending requests itself. There are no sleeps, waits or retries to tune.
+- **Real code paths.** Real controllers, real views, real Stimulus controllers, real Turbo, real session — only the browser engine is replaced.
+- **Clear failures.** A JavaScript exception, an unhandled rejection or a dialog you did not expect fails the test instead of being swallowed by the browser.
+- **Parallel-friendly.** Each test worker gets its own Node process; nothing is shared between workers.
+
+**What you lose**
+
+jsdom implements the DOM and runs JavaScript, but it does not lay out or paint pages. These cannot be tested with `rails-jsdom`; if they matter to you, keep a small number of real-browser system tests for them:
+
+- **Computed CSS** — colours, fonts, backgrounds, hover styles.
+- **Layout and geometry** — `getBoundingClientRect`, centring, gaps, overflow, wrapping, "these cards are the same height".
+- **CSS media-query breakpoints** — elements shown or hidden only by responsive CSS at a viewport width (for example Tailwind's `md:hidden`). `matchMedia` is stubbed so controllers don't crash, but CSS does not respond to width. Responsive behaviour driven by JavaScript, such as a mobile menu toggle, is still testable.
+- **Theme switching** where the theme only changes CSS.
+- **Screenshots** and other visual evidence.
+
+Layout assertions are brittle in any case; prefer asserting behaviour — what is in the DOM, what is hidden, what the URL is, what Rails received.
+
+**Not currently supported, but future support or partial support possible**
+
+These are limits of this library, not of jsdom. Support would be an imitation of the browser, so some behaviour stays out of reach:
+
+- **Browser default actions for keys** are partly supported. `send_keys` performs the common ones itself: typing and Backspace at the end of a text field, Enter submitting a form, Space and Enter pressing a focused button, Tab and Shift+Tab moving focus, and arrow keys, Home and End stepping a range or number field. Caret movement, text selection, IME input and OS shortcuts depend on layout or the platform and are not supported.
+- **Third-party scripts loaded from a CDN** — remote importmap pins are replaced by empty modules, and `<script src>` tags are not loaded. Pins vendored with `bin/importmap pin --download` are bundled and work. Remote scripts could be downloaded once and cached, but many of them (payment widgets, maps, charts, analytics) need cross-origin iframes, canvas, layout or their vendor's servers, so they would still need stubs.
+- **Custom ActionCable channels** with their own JavaScript consumers. Turbo Stream broadcasts *are* delivered (see below). Custom channels could be supported in-process by giving the page a fake WebSocket that runs the real channel in Ruby; reconnects, pings, concurrent delivery and several clients at once would stay untested.
+
+**Where the time goes**
+
+The esbuild bundle is built once per test worker. Each `visit` then costs a Rails render, a jsdom parse and a Turbo/Stimulus boot, and each interaction costs whatever Rails requests it makes. If several tests repeat the same visit and interactions only to check different things about the result, each one pays for them again; checking those things in one test pays once.
+
+## Requirements
+
+- Ruby 3.3, 3.4 or 4.0
+- Rails 8.1 with `importmap-rails`, `propshaft`, `turbo-rails` and `stimulus-rails`
+- Stimulus controllers under `app/javascript/controllers`, named `*_controller.js`
+- Node.js supported by jsdom (currently 20.19+, 22.13+ or 24+)
+
+These are the versions CI tests and that issues are fixed for. Ruby 3.2 has reached end of life. Older Rails releases may still work, but they are not tested or supported.
+
+## Installation
+
+Add the gem to the test group and install it:
+
+```ruby
+group :test do
+  gem "rails-jsdom"
+end
+```
+
+```bash
+bundle install
+bin/rails generate rails_jsdom:install
+```
+
+The install generator:
+
+1. Adds `require "rails_jsdom"` to `test/test_helper.rb`, after `require "rails/test_help"`.
+2. Creates `test/interactions/` for your interaction tests. Any test directory works; `bin/rails test` picks them up.
+3. Adds `jsdom` and `esbuild` to the `devDependencies` in `package.json`, creating the file if your app has none. The ranges (`^29.1.1`, `^0.28.2`) allow newer minor and patch releases but never a new major version. The gem loads both from your app's `node_modules`.
+4. Sets `min-release-age=7` in `.npmrc`, unless it is already set, so npm installs only versions published at least 7 days ago. See [Supply chain](#supply-chain).
+5. Warns if your npm is older than 11.10, which ignores `min-release-age`.
+6. Runs `npm install`. Pass `--skip-npm` to run it yourself.
+7. Adds `/node_modules` to `.gitignore`.
+8. Warns if `config/cable.yml` does not use the `test` adapter in the test environment, which [Turbo Stream broadcasts](#turbo-stream-broadcasts) need.
+
+Running it again changes nothing that is already set up.
+
+### Supply chain
+
+jsdom and esbuild run with your test process's access to your machine and CI, so a compromised release of either, or of anything they depend on, could take them over. Compromised npm releases are usually found and removed within days. The install generator sets up three defences:
+
+- **A major-version range.** `npm update` never moves to a new major version without you changing `package.json`.
+- **A release age.** With `min-release-age=7` in `.npmrc`, npm skips any version published in the last 7 days when it resolves a range, and fails with `ETARGET` if no older version fits. It needs npm 11.10 or later; older npm reads the setting and ignores it.
+- **Your lockfile.** Commit `package-lock.json` and install with `npm ci` in CI. `npm ci` installs exactly the locked versions, whatever your npm version, so new releases only arrive when someone runs `npm install` or `npm update` and commits the result.
+
+
+## Writing tests
+
+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.
+
+```ruby
+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
+
+  test "an unknown name shows the empty state instead of the grid" do
+    fill_in "search", with: "no-such-project"
+
+    assert_dom "[data-project-filter-target=noResults]:not([hidden])"
+    assert_dom "[data-project-filter-target=grid][hidden]"
+  end
+end
+```
+
+Patterns:
+
+- **Turbo forms** submit through Turbo and Rails answers in-process; Turbo Stream responses are applied before the action returns.
+- **Dialogs**: `<dialog>` `showModal`/`close` and `method="dialog"` forms work.
+- **Requests to other hosts** fail like a network error (`TypeError`), so a page cannot reach the internet.
+
+## API
+
+The full API reference is at **[jakehow.github.io/rails-jsdom](https://jakehow.github.io/rails-jsdom/)**. Tests inherit from [`RailsJsdom::TestCase`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestCase.html); every helper is documented in [`RailsJsdom::TestHelper`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html), with the locator rules, filters, scoping, dialogs and settling.
+
+### System test methods
+
+| System test method | Status | Notes |
+| --- | --- | --- |
+| [`visit`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-visit) | ✅ |  |
+| [`refresh`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-refresh) | ✅ | Requests the current URL again, without a history entry |
+| [`go_back`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-go_back), [`go_forward`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-go_forward) | ✅ | Across Turbo Drive visits and full page loads |
+| [`using_session`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-using_session) | ✅ | Each session has its own cookies and page; broadcasts reach a session's page when the test returns to it |
+| [`click_on`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-click_on), [`click_link_or_button`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-click_link_or_button) | ✅ |  |
+| [`click_link`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-click_link) | ✅ |  |
+| [`click_button`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-click_button) | ✅ |  |
+| [`fill_in`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-fill_in) | ✅ | Text-like fields only, as in system tests |
+| [`check`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-check), [`uncheck`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-uncheck) | ✅ |  |
+| [`choose`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-choose) | ✅ |  |
+| [`select`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-select), [`unselect`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-unselect) | ✅ |  |
+| [`attach_file`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-attach_file) | ✅ | Forms submit files to Rails as multipart requests |
+| [`send_keys`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-send_keys) | ✅ | Keys perform the common browser default actions; typing happens at the end of the value, with no caret or selection |
+| [`within`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-within) | ✅ | CSS selector or an element from `find`; also scopes `assert_dom` |
+| [`within_fieldset`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-within_fieldset), [`within_table`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-within_table) | ✅ |  |
+| [`find`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-find), [`all`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-all), [`first`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-first) | ✅ | `text:`, `exact_text:`, `visible:` and the field filters |
+| [`find_field`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-find_field), [`find_button`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-find_button), [`find_link`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-find_link) | ✅ | `with:`, `checked:`, `unchecked:`, `disabled:`, `href:`, `type:` |
+| Element [`.click`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-click), [`.set`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-set), [`.text`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-text), [`.value`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-value), [`.[]`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-5B-5D), [`.checked?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-checked-3F), [`.selected?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-selected-3F), [`.disabled?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-disabled-3F), [`.visible?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-visible-3F), [`.send_keys`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-send_keys), [`.select_option`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-select_option), [`.hover`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Element.html#method-i-hover) | ✅ | Plus the finders and assertions inside the element; using an element that left the page raises |
+| [`page`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-page) | ✅ | Every helper, plus [`body`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Page.html#method-i-body) and [`title`](https://jakehow.github.io/rails-jsdom/RailsJsdom/Page.html#method-i-title) |
+| [`assert_text`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_text), [`assert_no_text`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_text), [`refute_text`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-refute_text) | ✅ | String or Regexp |
+| [`assert_selector`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_selector), [`assert_css`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_css) | ✅ | Counts visible elements, as in system tests; `count:`, `minimum:`, `maximum:` |
+| [`assert_no_selector`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_selector), [`assert_no_css`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_css), [`refute_selector`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-refute_selector) | ✅ |  |
+| [`assert_field`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_field), [`assert_no_field`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_field) | ✅ |  |
+| [`assert_checked_field`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_checked_field), [`assert_unchecked_field`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_unchecked_field) | ✅ |  |
+| [`assert_button`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_button), [`assert_no_button`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_button) | ✅ | Disabled buttons match only with `disabled:` |
+| [`assert_link`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_link), [`assert_no_link`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_link) | ✅ |  |
+| [`assert_current_path`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_current_path), [`assert_no_current_path`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_current_path) | ✅ | `ignore_query:`, `url:`, Regexp |
+| [`assert_title`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_title), [`assert_no_title`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-assert_no_title) | ✅ |  |
+| [`has_text?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_text-3F), [`has_content?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_content-3F), [`has_no_text?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_text-3F), [`has_no_content?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_content-3F) | ✅ |  |
+| [`has_selector?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_selector-3F), [`has_css?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_css-3F), [`has_no_selector?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_selector-3F), [`has_no_css?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_css-3F) | ✅ |  |
+| [`has_field?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_field-3F), [`has_no_field?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_field-3F), [`has_checked_field?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_checked_field-3F), [`has_unchecked_field?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_unchecked_field-3F) | ✅ |  |
+| [`has_button?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_button-3F), [`has_no_button?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_button-3F), [`has_link?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_link-3F), [`has_no_link?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_link-3F) | ✅ |  |
+| [`has_current_path?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_current_path-3F), [`has_no_current_path?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_current_path-3F), [`has_title?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_title-3F), [`has_no_title?`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-has_no_title-3F) | ✅ |  |
+| [`current_path`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-current_path), [`current_url`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-current_url) | ✅ |  |
+| [`evaluate_script`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-evaluate_script) | ✅ | Awaits a returned promise |
+| [`execute_script`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-execute_script) | ✅ |  |
+| [`accept_alert`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-accept_alert) | ✅ | An unexpected alert fails the test |
+| [`accept_confirm`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-accept_confirm), [`dismiss_confirm`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-dismiss_confirm) | ✅ | An unexpected confirm fails the test |
+| [`accept_prompt`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-accept_prompt), [`dismiss_prompt`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-dismiss_prompt) | ✅ | An unexpected prompt fails the test |
+| [`hover`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-hover), [`double_click`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-double_click), [`right_click`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-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 |
+
+### Only in rails-jsdom
+
+| Method | What it does |
+| --- | --- |
+| [`click`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-click) | Clicks any element by locator, including Stimulus action shorthand (`click "dropdown#toggle"`) |
+| [`mount_partial`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-mount_partial) | Renders a partial and loads it as a page, with no route |
+| [`mount_html`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-mount_html) | Loads an HTML fragment as a page |
+| [`stub_fetch`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-stub_fetch) | Answers a page request without Rails |
+| [`page_text`](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html#method-i-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.
+
+## Turbo Stream broadcasts
+
+Pages that subscribe with `turbo_stream_from` receive broadcasts made during the test:
+
+```ruby
+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
+```
+
+After each action (and before each assertion), the runner finds the page's `<turbo-cable-stream-source>` elements, verifies each signed stream name with `Turbo::StreamsChannel.verified_stream_name`, reads the broadcasts recorded by the ActionCable `test` adapter, and applies new Turbo Stream messages with `Turbo.renderStreamMessage`. Broadcasts made before the page subscribed are skipped, forged stream names receive nothing, and each broadcast is applied once. `broadcast_*_later` broadcasts arrive when the test performs the jobs.
+
+Your test environment must use the ActionCable `test` adapter (`config/cable.yml`: `test: adapter: test`), which is the Rails default.
+
+## Timers and settling
+
+`setTimeout`, `setInterval` and `requestAnimationFrame` run on a virtual clock. After each action the runner keeps running due timers and waits for pending Rails requests until nothing is due within a one-second horizon. Timers further out — polling intervals, auto-dismissing flashes — stay pending, so pages never loop forever. A test does not need, and should not use, sleeps or waits.
+
+## Continuous integration
+
+CI needs Node and your app's npm packages before the tests run:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+- run: npm ci
+- run: bin/rails test
+```
+
+Each parallel test worker starts its own Node process the first time it runs an interaction test.
+
+## Troubleshooting
+
+- **Node output and page console messages** go to `Rails.logger` at info level, prefixed with `[rails_jsdom]`, so they appear wherever your test environment logs (by default `log/test.log`).
+- **`Cannot find module 'jsdom'`**: run `npm install --save-dev jsdom esbuild` in the app (and `npm ci` in CI).
+- **"The RailsJsdom Node process exited"**: see the `[rails_jsdom]` lines in your Rails log; the next command starts a new process.
+- **An exception in your Rails code while answering a page request** fails the test with that exception; the Node process is restarted for the next command.
+- **An element is not found**: `assert_dom` your expectation first, check the [locator rules](https://jakehow.github.io/rails-jsdom/RailsJsdom/TestHelper.html), or scope with `within`.
+
+## Limitations
+
+See [what you lose](#trade-offs-compared-with-system-tests). In addition: Stimulus outlets are untested, and pages that depend on browser APIs jsdom does not implement need a small stub in your controller or test.
+
+## Development
+
+```bash
+bundle install
+npm install
+bundle exec rake test
+bundle exec rubocop
+```
+
+`bundle exec rake test` runs, in order:
+
+1. ESLint over all JavaScript (`bundle exec rake lint_js`).
+2. The Node tests for the runtime and the ESLint rule (`bundle exec rake test_runner`).
+3. The Ruby tests.
+
+CI runs the same, plus RuboCop.
+
+This repository's own `.npmrc` sets `min-release-age=7` too, so `npm install` here skips releases from the last 7 days. Use npm 11.10 or later when you change `package.json`.
+
+### How the pieces fit
+
+- The Ruby side (`lib/rails_jsdom`) runs in the test process. The Node side (`lib/rails_jsdom/runtime.js`) runs the pages in jsdom.
+- They talk over a line protocol, documented in **[Runtime protocol](https://jakehow.github.io/rails-jsdom/docs/protocol_md.html)** ([source](docs/protocol.md)). Update that page whenever a command, field or reply changes.
+
+### Tests
+
+The library is tested against a small Rails app in `test/dummy`, with importmap, Turbo and Stimulus.
+
+When you add or change a helper, add its real usage to the dummy app and cover it with interaction tests in `test/interactions`:
+
+- Put the markup it acts on in a dummy page (`test/dummy/app/views`), with a route and controller action if it needs one. Prefer what a real app has: Rails form helpers, Turbo forms and links, Stimulus controllers.
+- Add one variant to the page for each behaviour that differs: each option and filter, each kind of element it matches, Turbo and non-Turbo forms, and the cases that must fail, such as no match, several matches, a disabled field or an unexpected dialog.
+- Write one interaction test per variant against the real page, and check the outcome Rails or the page sees, such as submitted params, the current path or the DOM.
+- Keep the unit tests in `test/rails_jsdom` for code that does not need a page.
+
+The Node runtime has its own unit tests in `test/runner/*.test.js`, written with Node's built-in test runner:
+
+- They drive the runtime only through its public interface, the line protocol. `test/runner/support.js` plays the Ruby side and answers the runtime's requests to Rails.
+- They bundle a small fixture app in `test/runner/fixtures`, with stand-ins for Stimulus and Turbo.
+- Write them in the same style: no reaching into private functions.
+
+### Standards
+
+These are enforced by `rake test` and RuboCop, and CI fails if any of them fails.
+
+- **Coverage:**
+  - The Ruby code is held at 100% of lines and branches (SimpleCov).
+  - `runtime.js` and the ESLint rule are held at 100% of lines, branches and functions (Node's test coverage).
+  - Code that cannot be tested is deleted.
+- **Comments:**
+  - Only API documentation is allowed. In Ruby that means RDoc: a comment block directly above a class, module, method, constant, attribute, alias or delegation, an RDoc directive such as `:nodoc:`, or a `##` block for a generated method. In JavaScript it means a `/** */` doc comment directly above a declaration.
+  - Every other comment fails the build. Put the meaning into a name, a method or a test.
+  - Directives that switch a cop off (`# rubocop:disable`, `// eslint-disable`) are not allowed either.
+- **API documentation:**
+  - Every public class, module, method and constant has RDoc. `bundle exec rdoc -C lib` reports 100%.
+  - The API reference is built with `bundle exec rake rdoc` and published to GitHub Pages.
+- **Readable code (Ruby):**
+  - Implicit returns, with no `return` and no explicit `return nil`.
+  - `unless` only as a one-line modifier with a predicate method.
+  - No boolean flags set more than once. No ternaries with a `nil`, `true` or `false` branch. No `next unless`. No `.nil?` as a condition.
+  - Bang methods start with a verb, and predicate methods return booleans.
+  - Blocks are named (`&block`), not forwarded anonymously.
+  - These cops live in `rubocop/cop/readability`, with their tests in `test/rubocop`.
+- **Size and complexity:**
+  - Ruby: methods up to 10 lines, AbcSize 13, cyclomatic and perceived complexity 5, and one level of block nesting.
+  - JavaScript: complexity 8, 25 lines and 16 statements per function, nesting depth 2, 4 parameters, and no nested ternaries.
+  - When code goes over a limit, remove the complexity: give a concept its own method or class, or split a function by the questions it answers. Never shorten lines with compressed or unusual syntax. A clear method slightly over a limit is better than a contorted one under it.
+- **Style:**
+  - Ruby follows rubocop-rails-omakase and rubocop-minitest, with RuboCop's Lint and Gemspec departments.
+  - Write `case` with each `when` body on its own line.
+  - JavaScript: double quotes, no semicolons, two-space indentation, `const` over `let`, and `===`.
+
+Releases are published to RubyGems from GitHub Actions with trusted publishing when a `v*` tag is pushed.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/generators/rails_jsdom/install/install_generator.rb

@@ -0,0 +1,108 @@
+require "erb"
+require "json"
+require "yaml"
+require "rails/generators"
+
+module RailsJsdom
+  # Rails generators for rails-jsdom.
+  module Generators
+    # Sets an app up for rails-jsdom interaction tests:
+    #
+    #   bin/rails generate rails_jsdom:install
+    #
+    # Pass `--skip-npm` to add the Node packages to `package.json` without
+    # running `npm install`.
+    class InstallGenerator < Rails::Generators::Base
+      # The Node packages the app needs. Each range allows newer minor and patch
+      # releases but never a new major version.
+      PACKAGES = { "jsdom" => "^29.1.1", "esbuild" => "^0.28.2" }.freeze
+
+      # How many days old a package version must be before npm installs it.
+      RELEASE_AGE_DAYS = 7
+
+      # The first npm version that understands `min-release-age`.
+      RELEASE_AGE_NPM = Gem::Version.new("11.10.0")
+
+      class_option :skip_npm, type: :boolean, default: false, desc: "Add jsdom and esbuild to package.json without running npm install"
+
+      # Requires the library in `test/test_helper.rb`, after `rails/test_help`.
+      def require_library
+        inject_into_file "test/test_helper.rb", "require \"rails_jsdom\"\n", after: %r{require ["']rails/test_help["']\n}
+      end
+
+      # Creates `test/interactions`, where interaction tests live.
+      def create_interactions_directory
+        create_file "test/interactions/.keep", ""
+      end
+
+      # Adds jsdom and esbuild to the development dependencies in
+      # `package.json`, creating the file if the app has none. Versions the
+      # app already lists are kept.
+      def add_node_packages
+        package = existing_package || { "private" => true }
+        package["devDependencies"] = PACKAGES.merge(package.fetch("devDependencies", {}))
+        create_file "package.json", "#{JSON.pretty_generate(package)}\n", force: true
+      end
+
+      # Sets `min-release-age` in `.npmrc`, so npm installs only package
+      # versions published at least RELEASE_AGE_DAYS days ago. A compromised
+      # release of jsdom, esbuild or anything they depend on is usually found
+      # and removed within that time. An existing `min-release-age` is kept.
+      def delay_new_releases
+        settings = npm_settings
+        create_file ".npmrc", "#{settings}min-release-age=#{RELEASE_AGE_DAYS}\n", force: true unless settings.match?(/^min-release-age\s*=/)
+      end
+
+      # Warns when the app's npm is older than 11.10, which ignores
+      # `min-release-age`.
+      def check_npm_version
+        say_status :warning, "npm #{npm_version} ignores min-release-age, so it would install brand-new releases. Upgrade to npm #{RELEASE_AGE_NPM} or later.", :yellow if npm_version < RELEASE_AGE_NPM
+      end
+
+      # Runs `npm install`, unless `--skip-npm` is given.
+      def install_node_packages
+        run "npm install" unless options.skip_npm?
+      end
+
+      # Adds `/node_modules` to `.gitignore`, unless it is already ignored.
+      def ignore_node_modules
+        gitignore = path(".gitignore")
+        append_to_file ".gitignore", "\n/node_modules\n" if File.exist?(gitignore) && !File.read(gitignore).include?("node_modules")
+      end
+
+      # Warns when the test environment does not use the ActionCable `test`
+      # adapter, which Turbo Stream broadcasts need.
+      def check_cable_adapter
+        say_status :warning, "Set `adapter: test` for the test environment in config/cable.yml so pages receive Turbo Stream broadcasts", :yellow unless test_cable_adapter?
+      end
+
+      private
+
+      def npm_settings
+        settings = File.exist?(path(".npmrc")) ? File.read(path(".npmrc")) : ""
+        settings.empty? || settings.end_with?("\n") ? settings : "#{settings}\n"
+      end
+
+      def npm_version
+        @npm_version ||= Gem::Version.new(run("npm --version", capture: true, verbose: false).to_s.strip)
+      end
+
+      def existing_package
+        JSON.parse(File.read(path("package.json"))) if File.exist?(path("package.json"))
+      end
+
+      def test_cable_adapter?
+        cable = path("config/cable.yml")
+        File.exist?(cable) && cable_config(cable).dig("test", "adapter") == "test"
+      end
+
+      def cable_config(file)
+        YAML.safe_load(ERB.new(File.read(file)).result, aliases: true)
+      end
+
+      def path(relative)
+        File.join(destination_root, relative)
+      end
+    end
+  end
+end

data/lib/rails_jsdom/bridge.rb

@@ -0,0 +1,80 @@
+module RailsJsdom
+  class Bridge # :nodoc:
+    def initialize(command:, setup:, logger:)
+      @command = command
+      @setup = setup
+      @logger = logger
+    end
+
+    def call(message, &on_fetch)
+      start unless started?
+      write(message)
+      receive(&on_fetch)
+    end
+
+    def started?
+      !!@input
+    end
+
+    def reset
+      call(command: "reset") if started?
+    end
+
+    private
+
+    def start
+      @input, @output, error, @process = Open3.popen3(*@command)
+      @log = Thread.new { log(error) }
+      write(@setup)
+      receive
+    end
+
+    def log(error)
+      error.each_line { |line| @logger.info("[rails_jsdom] #{line.chomp}") }
+      error.close
+    end
+
+    def stop
+      @input.close
+      @output.close
+      Process.kill("TERM", @process.pid) if @process&.alive?
+      @log.join
+      @input = nil
+    end
+
+    def receive(&on_fetch)
+      message = read
+      case message.fetch("type")
+      when "fetch"
+        write(type: "fetch_response", id: message.fetch("id"), response: answer(message.fetch("request"), &on_fetch))
+        receive(&on_fetch)
+      when "error"
+        raise Error, message.fetch("message")
+      else
+        message.fetch("value")
+      end
+    end
+
+    def answer(request, &on_fetch)
+      on_fetch.call(request)
+    rescue StandardError
+      stop
+      raise
+    end
+
+    def read
+      line = @output.gets
+      if line
+        JSON.parse(line)
+      else
+        stop
+        raise Error, "The RailsJsdom Node process exited. See the [rails_jsdom] lines in the Rails log."
+      end
+    end
+
+    def write(payload)
+      @input.puts(JSON.generate(payload))
+      @input.flush
+    end
+  end
+end