capybara-simulated

A lightweight Capybara driver that runs JavaScript against an in-process JS-resident DOM, with no Chrome. Forms submit through Rack::MockRequest, inline <script> and event handlers run, MutationObserver / custom elements / <template> / Shadow DOM / Trix / Stimulus / Turbo all work, and the Capybara DSL is unchanged.

The DOM lives entirely inside the JS engine — V8 via rusty_racer or QuickJS via quickjs.rb, whichever is installed — with no Nokogiri tree on the Ruby side. Capybara finds resolve through css-select (CSS) and xpathway (XPath) running in the same context as the page's JS, so find / has_css? / within see exactly the tree the app sees.

Status

The architecture and behaviour are stable. Correctness is held to two bars. A vendored subset of web-platform-tests — the same DOM / HTML tests Chromium and Firefox hold themselves to — runs as a conformance gate. And each target app (Redmine / Forem / Avo / Mastodon / Discourse) runs its full system suite against the driver in capybara-simulated-vs-world as an integration check.

The remaining gaps need a real layout engine (elementFromPoint, truthy getBoundingClientRect, viewport-clip visibility, display: contents table edge cases) — the same set Selenium escapes via screenshots and this driver deliberately doesn't simulate.

Install

gem 'capybara-simulated', group: :test
gem 'rusty_racer', group: :test  # JS engine — pick one

bundle install. Requires Ruby ≥ 3.3. The gem ships its JS bridge under lib/capybara/simulated/js/ and the vendored JS deps under vendor/js/, so there's no Node toolchain at consume time.

JS engine

The gem treats the JS engine as a soft dependency. Pick one of:

gem 'rusty_racer'         # V8 (JIT, fastest per spec) — default
gem 'quickjs', '>= 0.18'  # QuickJS (interpreter, smaller per-VM RAM —
                          # wins when scaling parallel workers under
                          # a fixed memory budget)

The V8 engine comes from rusty_racer, a rusty_v8-based Ruby binding with the native ES Module API, ScriptCompiler::CachedData snapshots, and per-frame realm contexts the driver builds on.

The engine is auto-detected at boot; if both gems are present V8 wins. Override explicitly with CSIM_JS_ENGINE=v8|quickjs or Capybara::Simulated::Driver.new(app, js_engine: :quickjs).

Use

require 'capybara/simulated' registers the :simulated driver.

RSpec

# spec/spec_helper.rb (or spec/rails_helper.rb)
require 'capybara/rspec'
require 'capybara/simulated'

Capybara.javascript_driver = :simulated
# Optional: use :simulated for non-JS specs too.
# Capybara.default_driver = :simulated

Tests tagged js: true (or type: :system, js: true in Rails) run in the driver:

RSpec.describe 'sign-in', type: :system, js: true do
  it 'logs the user in' do
    visit '/login'
    fill_in 'Email',    with: 'alice@example.com'
    fill_in 'Password', with: 'hunter2'
    click_button 'Log in'
    expect(page).to have_text('Welcome, Alice')
  end
end

For Rails system tests, set the driver via driven_by:

RSpec.describe 'sign-in', type: :system do
  before { driven_by :simulated }
  # ...
end

Minitest

Capybara.javascript_driver is RSpec-only — ActionDispatch::SystemTestCase ignores it. Set the driver explicitly:

# test/application_system_test_case.rb
require 'capybara/minitest'
require 'capybara/simulated'

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :simulated
end

Plain Capybara DSL (no framework)

require 'capybara/dsl'
require 'capybara/simulated'

Capybara.app = MyRackApp
Capybara.default_driver = :simulated

include Capybara::DSL

visit '/'
click_link 'About'
puts page.text

Trace

Each Capybara action (visit, click, set, …) is recorded as a step in a per-test trace: URL before / after, console output and network requests during the step, plus elapsed and per-step durations. On action failure (and only then, by default) the post-action DOM is captured too.

Recording is on by default — fully in-memory, no files written unless you opt in via CSIM_TRACE_DIR. Wall-time overhead is run-to-run-variance equivalent because the expensive part — DOM serialization — only fires on action error.

Modes (CSIM_TRACE=…)

value	recording	DOM snapshot
(unset) / on-failure	yes (default)	per step on action error only
full	yes	after every action — debug-heavy
off	nothing recorded, record_action early-exits	—

Inspecting traces

In an after-hook:

after(:each) do |example|
  if example.exception
    trace = page.driver.current_trace
    puts trace.steps.last.dom_after  # final-state HTML
    puts trace.steps.flat_map(&:console).map {|c| "#{c[:severity]} #{c[:message]}" }
  end
end

File output

Set CSIM_TRACE_DIR=/path/to/dir to enable file output. The bundled RSpec hook (csim_rspec.rb) writes <example slug>.json into that directory after each test; mirror it in application_system_test_case.rb's teardown for Minitest.

CSIM_TRACE_DIR=tmp/csim-traces bundle exec rspec spec/system

The metadata block on each trace includes title, file, outcome (passed / failed), and the exception message — enough to index a CI artifact directory by failure.

Programmatic

For finer control, call driver.start_tracing(...) / driver.stop_tracing(path: ...). The shape mirrors capybara-playwright-driver:

RSpec.describe 'flaky payment flow', type: :system, js: true do
  it 'completes a checkout' do
    page.driver.start_tracing(case_id: 'PAY-1431')
    visit '/checkout'
    fill_in 'Card', with: '4242424242424242'
    click_button 'Pay'
    expect(page).to have_text 'Thank you'
  ensure
    page.driver.stop_tracing(path: "tmp/traces/#{example.full_description}.json")
  end
end

Trace JSON schema

{
  "version": 1,
  "metadata": { "title": "...", "outcome": "passed", "...": "..." },
  "steps": [
    {
      "index":       0,
      "kind":        "visit",       // visit / click / set / send_keys / select / submit / refresh / go_back / go_forward
      "description": "visit /checkout",
      "url_before":  null,
      "url_after":   "http://www.example.com/checkout",
      "dom_after":   null,          // populated only on action error or in `full` mode
      "console":     [{ "severity": "info", "message": "Stripe.js loaded" }],
      "network":     [{ "method": "GET",    "url": "/checkout", "status": 200 }],
      "elapsed_ms":  0,
      "duration_ms": 38,
      "error":       null
    }
  ]
}

Performance characteristics

The driver builds a base snapshot once per process — the bundled bridge plus the vendored JS deps, as a V8 Snapshot for rusty_racer or bytecode for QuickJS. On V8 that snapshot warms a single long-lived isolate whose context is reset to a clean realm per navigation (Context#reset); on QuickJS each navigation checks a freshly snapshot-loaded VM out of a small pre-warmed pool. Either way, every navigation lands on a clean, warm JS context near-instantly.

Wall time is sensitive to whether the app uses Turbo Drive, because navigation simulates real-browser semantics:

navigation source	what happens
visit(...), refresh, programmatic location.assign	full reload — fresh JS Context, scripts re-evaluated
link click with Turbo Drive loaded	Turbo intercepts, body-swap via JS, JS context preserved
link click without Turbo Drive	full reload (anchor default action)
form submit with Turbo Drive loaded	Turbo intercepts (turbo-frame or page-level), body-swap
form submit without Turbo Drive	full reload

So Turbo Drive apps stay fast even with click-heavy tests; non-Turbo apps pay full-reload cost per click — exactly mirroring what the production site does.

Library snapshot policy

Per visit, <script src>-referenced libraries (jQuery, Stimulus, …) re-evaluate fresh against the new page. They are not baked into a per-app snapshot — preserving library state across page navigations is what real browsers don't do, and trying to do it broke $.ready Callbacks queues whose user-app callbacks referenced page-specific DOM.

Other factors

• <script src> parsing dominates visit on JS-heavy pages. Each external script is fetched through the in-process Rack app, compiled, and run in the JS engine with bytecode cache hits from the base snapshot warmup.
• CSS cascade resolution: stylesheets are parsed once per distinct set of sources and cached content-addressably, so repeat visits and subsequent finds on the same page reuse the resolved cascade instead of re-parsing.
• DOM ops stay inside the JS engine — find / has_? / event dispatch never cross the Ruby ↔ JS boundary for the actual tree walk; only the resulting handle ids do. Modify-heavy tests (SortableJS dragging thousands of items) run at JS-engine speed, not at host-call-IPC speed.
• Polling (Capybara default_max_wait_time) advances a virtual JS clock — timers fire as polling steps the clock forward, not in real time. A page that schedules setTimeout(2000, x) doesn't block for 2 s; the callback fires once polling has advanced the clock past it.

Known limits

• No layout engine. visible? and Node#style consult the CSS cascade and the inline style attribute, but getBoundingClientRect() returns zeros and elementFromPoint() isn't implemented. Click offsets work for fixture-style absolute / relative positioning (ancestor-summed top/left); position-via- layout (Dragula drops, sticky-header scroll math) needs a real browser.
• :hover / :focus-within-gated content is reachable two ways: call element.hover explicitly (we track the most-recently-hovered element and propagate :hover up its chain), or rely on the candidate-chain fallback (when stateless cascade reports display: none, we re-evaluate with the candidate itself in the :hover set). Symmetric peers — N rows each with tr:hover .icon revealing .icon, queried as bare find('.icon') — reveal all and Capybara raises Capybara::Ambiguous. Scope the test (find('tr', text: 'foo').hover then find('.icon')) — also more robust against real-browser flake.
• fetch is synchronous-via-Rack — HTML / JSON round-trips work but there's no real network, no streaming, no Request#body ReadableStream, and no concurrent requests. XHR is implemented with the same Rack pass-through.
• Multi-window is URL-tracking only — target="_blank" clicks open a window-handle and current_window / switch_to_window work, but each aux window only records its URL (no per-window JS context or cross-window postMessage).
• within_frame, WebSocket, screenshots, and drag pixel coordinates are out of scope — use Selenium / Cuprite. There's no frame-switching DSL to drive a test into an <iframe>, though an iframe's own scripts do run, in a per-frame JS realm. (EventSource and Web Workers are implemented.)

Architecture

• lib/capybara/simulated/js/src/ — the entire DOM lives here, split across ~50 ES modules bundled into bridge.bundle.js (esbuild; no Node toolchain at consume time). Document / Element / Text / DocumentFragment / ShadowRoot classes; event dispatch (capture / target / bubble with shadow retargeting, via dispatchEvent(target, event)); a virtual setTimeout / setInterval / requestAnimationFrame clock; MutationObserver; custom-element registry; Range / Selection; and the cascade resolver for display / visibility / text-transform. Capybara's finds run through the vendored css-select (with css-what / css-tree) for CSS and xpathway for XPath — both true third parties under vendor/js/, executing in the same context as the page's JS.
• lib/capybara/simulated/browser.rb — Rack client, history stack, modal handler queue, virtual-clock anchor, trace recorder. Owns the JS runtime via V8Runtime or QuickJSRuntime. The hot operations (find_css / find_xpath / DOM ops / event dispatch) are single-Context#call round-trips returning handle id arrays; per-result iteration stays Ruby-side.
• lib/capybara/simulated/v8_runtime.rb / quickjs_runtime.rb — per-engine wrappers, common bits in runtime_shared.rb. The V8 base-snapshot (and the QuickJS bytecode equivalent) bakes in the bundled bridge + vendored deps, so a per-navigation context reset (V8) or pooled VM checkout (QuickJS) is sub-millisecond.
• lib/capybara/simulated/driver.rb — Capybara Driver::Base surface (visit / find / execute_script / window handling / modal / tracing API).
• lib/capybara/simulated/node.rb — Driver::Node over a (handle_id, context_gen) pair so a handle from a pre-rebuild Context can't ghost into the next one.

ES modules + importmap

<script type="module"> and <script type="importmap"> work the same way they do in a real browser: bare specifiers resolve through the importmap, relative paths resolve against the importer's URL, and every load (including dynamic import(...)) routes back through the in-process Rack app. No bundling step, no Node toolchain.

The standard importmap-rails layout works as-is:

<%= javascript_importmap_tags %>
<!-- emits:
  <script type="importmap">{ "imports": { "application": "/assets/application-...js", ... } }</script>
  <script type="module">import "application"</script>
-->

Hotwire (Stimulus + Turbo)

Stimulus and Turbo work both via UMD (classic <script src>) and via the standard ESM bundles imported through importmap. For importmap-rails apps, no changes are needed:

# config/importmap.rb
pin '@hotwired/stimulus'
pin '@hotwired/turbo'

window.fetch routes through Rack, so Turbo's frame fetch and link-action POSTs round-trip the test app.

License

MIT.