capybara-simulated 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02f56bfd3215e67c4a8faa799352e0ae3c399557f928926cafcdc9dde7dd2b9c
-  data.tar.gz: 12e88e441d93de921d0727bfae9e3728cc56d100f8e32e525e37e21a28f0e273
+  metadata.gz: 67e9168ef15e413c1d85b1805ea4d68f36cae09578af5fc539bd1613d52ac04d
+  data.tar.gz: 6214303ef25079d567bc91db43460eda49a54a292ed08021b98a81ce48af0c31
 SHA512:
-  metadata.gz: a1f22b4a5d7ffec1b33080982aa169b5b3356c014d49a399de4cf5b5a430021eec7fb1ba4d624b00769640ffdcd314e55df765afdd44ac90575c88cb137519c9
-  data.tar.gz: 04d95fd0e7215800124d4d81de11247b814e352c0b511d550bb9bb1557a0af069c1261b52a570e82f6100cab90e07d627b18b7a02267f193dd92c4c98c92e2cd
+  metadata.gz: 8112cd3056184946f65739dfb30e76e55bee2a79f1058e3128bc8ae15f0b5790f195d0c289759518e667b69902962e70922af21f48dea6610744ab1093a10ca4
+  data.tar.gz: 53ccb66cb2bd4723d1e999ebd03b0a56bdbc83978834f82b66c128aa2c7e3ba1c4f5464c5965442104de94de2fbabe79e185a74f6e1aaa3cd2c2c2c2bfe68a26

data/README.md

@@ -2,9 +2,8 @@
 
 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.
+`Rack::MockRequest`, inline `<script>` and event handlers run, and the
+Capybara DSL is unchanged.
 
 The DOM lives entirely inside the JS engine — V8 via
 [rusty_racer](https://github.com/ursm/rusty_racer) or QuickJS via
@@ -37,35 +36,15 @@ visual layout:
 
 **Reach for a real browser** (Selenium / Cuprite) **when** your tests need
 what this driver doesn't simulate **by design** — there's no rendering
-engine or real network stack, the same ground Selenium covers via a real
-browser:
-
-- **Pixel layout** — `getBoundingClientRect()` returns zeros and
-  `elementFromPoint()` isn't implemented, so visual hit-testing,
-  coordinate drag-and-drop, and sticky-scroll math don't work.
-- **Real networking** — `fetch` / XHR are synchronous through Rack: no
-  streaming, no HTTP concurrency. (`EventSource` and `WebSocket` *do*
-  work — they ride real reader threads / the in-process `rack.hijack`
-  socket; see below.)
-- **Screenshots**.
-
-**`within_frame` / `switch_to_frame`** work on the V8 (rusty_racer) engine:
-each `<iframe>` runs its own scripts in its own per-frame realm, and the DSL
-routes finds, reads, interactions, `evaluate_script`, and self-targeted
-navigation (a link or form submit inside the frame) into the active frame —
-nested frames included. (QuickJS keeps a same-realm fallback, so
-`within_frame` is V8-only.)
-
-**Multiple windows / tabs** work on both engines: each window is its own
-Browser + JS VM (own DOM, sessionStorage, history; cookies + localStorage
-shared). `open_new_window` / `within_window` / `switch_to_window` /
-`window_opened_by` drive them, and JS `window.open` opens a real window,
-`window.opener` points back to the opener, and `postMessage` is delivered
-across windows. (`target="_blank"` defaults to no-opener, matching modern
-browsers; cross-window `postMessage` data is JSON-shaped, not a full
-structured clone.)
-
-See [Known limits](#known-limits) for the full picture.
+engine: **pixel layout** (`getBoundingClientRect()` returns zeros,
+`elementFromPoint()` isn't implemented, so visual hit-testing, coordinate
+drag-and-drop, and sticky-scroll math don't work) and **screenshots**.
+
+Most of the rest runs in-process — including the things that usually mean
+"you need a real browser": **`within_frame`**, **multiple windows / tabs**,
+**WebSocket + Action Cable**, **EventSource**, and **Web Workers** all work.
+Each has constraints (JS engine, settle-timing, no layout); see
+[Capabilities & limits](#capabilities--limits).
 
 ## Status
 
@@ -78,10 +57,9 @@ Mastodon / Discourse) runs its full system suite against the driver in
 [capybara-simulated-vs-world](https://github.com/ursm/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.
+The remaining gaps are the layout / pixel-geometry features the driver
+deliberately doesn't simulate — the same set Selenium escapes via
+screenshots (see [Capabilities & limits](#capabilities--limits)).
 
 ## Install
 
@@ -222,11 +200,18 @@ end
 
 ### File output
 
-Set `CSIM_TRACE_DIR=/path/to/dir` to enable file output. The bundled
-RSpec hook ([`csim_rspec.rb`](https://github.com/ursm/capybara-simulated-vs-world/blob/main/support/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.
+Require the test-framework integration in your `spec_helper` /
+`rails_helper` (RSpec) or `test_helper` /
+`application_system_test_case.rb` (Minitest):
+
+```ruby
+require 'capybara/simulated/rspec'     # RSpec
+require 'capybara/simulated/minitest'  # Minitest / Rails system tests
+```
+
+With `CSIM_TRACE_DIR=/path/to/dir` set, each example that recorded a
+trace is written to `<dir>/<slug>.json` after it runs; both integrations
+are inert when the env var is unset.
 
 ```sh
 CSIM_TRACE_DIR=tmp/csim-traces bundle exec rspec spec/system
@@ -236,6 +221,31 @@ 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.
 
+### Viewing traces
+
+The recorded JSON stays plain data; to look at one, render it into a
+self-contained HTML viewer with the bundled CLI:
+
+```sh
+capybara-simulated trace tmp/csim-traces/checkout_flow.json
+# wrote /tmp/checkout_flow.html   (then opens it in your browser)
+```
+
+By default the HTML is written to a temp file and opened in your
+browser. The viewer works straight from `file://` — the trace JSON is
+embedded inline, so no server is needed — and shows a step-by-step UI: a
+timeline of actions, and per step the URL before/after, console output,
+network requests, the error, and a rendered preview of the post-action
+DOM snapshot. Its **Load JSON…** button / drag-and-drop swaps in any
+other trace file.
+
+`-o PATH` writes the HTML somewhere specific (`-o -` to stdout);
+`--no-open` skips launching the browser. Browser launching uses
+[launchy](https://rubygems.org/gems/launchy) when it's installed
+(`gem 'launchy'`, recommended for reliable cross-platform / WSL opening)
+and falls back to the platform opener (`xdg-open` / `open` / `start`)
+otherwise.
+
 ### Programmatic
 
 For finer control, call `driver.start_tracing(...)` /
@@ -290,21 +300,6 @@ isolate whose context is reset to a clean realm per navigation
 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,
@@ -335,67 +330,64 @@ referenced page-specific DOM.
   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.
-- **WebSocket** works in-process: `new WebSocket(url)` rides the
-  `rack.hijack` socket the Rack app hijacks, with a hand-rolled RFC6455
-  client (handshake + subprotocol negotiation, masked client frames,
-  ping/pong, close handshake). Frames deliver as `message` events when
-  the page next settles, like SSE. **Action Cable** works end-to-end on
-  this: the real `@rails/actioncable` consumer connects, subscribes, and
-  receives server broadcasts (so `turbo_stream_from` live updates are
-  reachable) — Action Cable hijacks the connection just as csim drives
-  it. Caveats: server pushes land at settle (not instant); the app must
-  use the **async / in-process** Cable adapter (a real Redis adapter
-  would need real Redis); binary frames are V8-only (QuickJS corrupts
-  raw bytes across the host boundary — text, hence Action Cable, is fine
-  on both). `EventSource` and Web Workers are likewise implemented.
-- **Screenshots and drag pixel coordinates** are out of scope by
-  design — use Selenium / Cuprite.
-- **`within_frame` / `switch_to_frame`** work on the V8 engine: each
-  `<iframe>` runs in its own per-frame realm and the DSL routes finds,
-  reads, interactions, `evaluate_script`, and self-targeted navigation
-  (link / form submit) into the active frame (nested frames included) — the
-  frame's realm is rebuilt from the fetched document, leaving the top page
-  untouched. `_top` navigates the main page; a `_parent` target from a
-  frame nested ≥2 levels falls back to navigating the main page, and
-  cross-origin frame locality resolves against the main origin. QuickJS has
-  no nested browsing context, so `within_frame` raises there.
-- **Multiple windows / tabs** work on both engines: each window is its own
+## Capabilities & limits
+
+Most features run in-process; the notes below are mostly "works, but…",
+followed by the short list of things that need a real browser **by design**.
+
+### Works, with constraints
+
+- **`within_frame` / `switch_to_frame`** (V8 engine) — each `<iframe>` runs
+  its own scripts in its own per-frame realm; the DSL routes finds, reads,
+  interactions, `evaluate_script`, and navigation into the active frame,
+  nested frames included — the target frame's realm is rebuilt from the
+  fetched document, the top page untouched. QuickJS has no nested browsing
+  context, so `within_frame` raises there.
+- **Multiple windows / tabs** (both engines) — each window is its own
   Browser + JS VM (own DOM, sessionStorage, history; cookies + localStorage
-  shared across windows). `open_new_window` / `within_window` /
-  `switch_to_window` / `window_opened_by` drive them; JS `window.open` opens
-  a real window, `window.opener` links back, and `postMessage` is routed
-  across windows (delivered as a `message` event when the target window next
-  settles). Caveats: `target="_blank"` opens with no opener (modern-browser
-  no-opener default); cross-window `postMessage` data is JSON-shaped, not a
-  full structured clone (no `DataCloneError`, `undefined`→`null`) — but a
-  buffer in the `transfer` list moves **zero-copy** (its backing store crosses
-  isolates by token and the source is detached); and only the active window's
-  event loop runs, so a message is delivered when you switch to its window.
-  Window viewport APIs (`maximize` / `fullscreen` /
-  pixel-exact `resize_to`) are no-ops — no layout engine.
+  shared). `open_new_window` / `within_window` / `switch_to_window` /
+  `window_opened_by` drive them; JS `window.open` opens a real window,
+  `window.opener` links back, and `postMessage` crosses windows. Only the
+  active window's event loop runs, so a message is delivered when you switch
+  to its window. `target="_blank"` opens with no opener (modern-browser
+  default). `postMessage` carries real structured data (not a lossy JSON
+  hop) — `Map` / `Set` / `Date` / `BigInt` / typed arrays / cyclic graphs all
+  round-trip on V8 — and a `transfer`-list buffer moves **zero-copy** (backing
+  store by token, source detached); only bare `undefined` collapses to `null`
+  (Ruby has no distinct `undefined`). Window viewport APIs (`maximize` /
+  `fullscreen` / pixel-exact `resize_to`) are no-ops (no layout engine).
+- **WebSocket + Action Cable** — `new WebSocket(url)` works in-process over
+  the `rack.hijack` socket the Rack app hijacks (hand-rolled RFC6455, including
+  subprotocol negotiation). The real `@rails/actioncable` consumer connects,
+  subscribes, and receives broadcasts, so `turbo_stream_from` live updates
+  work. Constraints: server
+  pushes land at settle (not instant); the Cable app must use the **async /
+  in-process** adapter (a real Redis adapter needs real Redis); binary frames
+  are V8-only (QuickJS corrupts raw bytes across the host boundary — text,
+  hence Action Cable, works on both engines). `EventSource` and Web Workers
+  are likewise real (background reader threads draining at settle).
+- **`fetch` / XHR** — synchronous through Rack: HTML / JSON round-trips work,
+  but there's no streaming, no `Request#body` ReadableStream, and no
+  concurrent requests.
+- **`:hover` / `:focus-within`-gated content** — 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 the 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 a bare `find('.icon')` —
+  reveal all and Capybara raises `Capybara::Ambiguous`; scope the test
+  (`find('tr', text: 'foo').hover` then `find('.icon')`), which is also more
+  robust against real-browser flake.
+
+### Out of scope (by design — use Selenium / Cuprite)
+
+- **Layout / pixel geometry.** `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,
+  viewport-clip visibility) needs a real browser.
+- **Screenshots.**
 
 ## Architecture
 
@@ -429,39 +421,6 @@ referenced page-specific DOM.
   `(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:
-
-```erb
-<%= 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:
-
-```ruby
-# 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](LICENSE).

data/exe/capybara-simulated

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# capybara-simulated CLI. Currently one subcommand:
+#
+#   capybara-simulated trace TRACE.json [-o OUT.html] [--no-open]
+#
+# Renders a trace JSON (produced by CSIM_TRACE_DIR / driver.stop_tracing)
+# into a self-contained HTML viewer and opens it in your browser. The
+# viewer embeds the JSON inline so it opens straight from file:// — no
+# server, unlike a fetch/import-based loader (CORS blocks those for
+# file:// origins). The persisted trace stays plain JSON; this turns one
+# into a UI on demand.
+
+require 'optparse'
+require 'tmpdir'
+
+# Prefer the library co-located with this executable. In an installed
+# gem that's the gem's own lib (correct version); in a checkout it's the
+# working tree — so `ruby exe/capybara-simulated` doesn't accidentally
+# load an older *installed* capybara-simulated that predates this CLI.
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+require 'capybara/simulated/trace'
+
+PROG = 'capybara-simulated'
+
+# `file://` URL for a local path, percent-encoding each segment so a
+# path with spaces / special chars stays a valid URI for launchy.
+def file_url(path)
+  require 'cgi'
+  'file://' + path.split('/').map {|seg| CGI.escapeURIComponent(seg) }.join('/')
+end
+
+# Hand the raw path (not a URL) to the platform opener; `system`'s array
+# form needs no shell-quoting, so spaces are fine.
+def open_with_platform(path)
+  cmd =
+    case RbConfig::CONFIG['host_os']
+    when /darwin/      then ['open', path]
+    when /mswin|mingw/ then ['cmd', '/c', 'start', '', path]
+    else                    ['xdg-open', path]  # Linux / *BSD
+    end
+  system(*cmd)
+rescue StandardError
+  false
+end
+
+# Open a local file in the default browser. Prefer launchy (handles
+# macOS / Linux / Windows / WSL) when installed; on either a missing gem
+# OR a launchy runtime failure (headless box, no opener), fall back to
+# the platform opener.
+def open_in_browser(path)
+  begin
+    require 'launchy'
+    Launchy.open(file_url(path))
+    return true
+  rescue LoadError
+    # launchy not installed
+  rescue StandardError
+    # launchy present but failed — try the platform opener below
+  end
+  open_with_platform(path)
+end
+
+def cmd_trace(argv)
+  out  = nil
+  open = nil  # nil → default (open), unless writing to stdout
+  parser = OptionParser.new do |o|
+    o.banner = "Usage: #{PROG} trace [options] TRACE.json\n\n" \
+               "Render TRACE.json into a self-contained HTML viewer and open it\n" \
+               "in your browser. By default the HTML goes to a temp file."
+    o.on('-o', '--output PATH', "write HTML to PATH instead of a temp file ('-' = stdout)") {|v| out = v }
+    o.on('--[no-]open', 'open the HTML in your browser (default: yes)') {|v| open = v }
+    o.on('-h', '--help') do
+      puts o
+      exit
+    end
+  end
+  begin
+    parser.parse!(argv)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    warn parser.help
+    exit 1
+  end
+
+  input = argv.shift
+  unless input
+    warn parser.help
+    exit 1
+  end
+  unless File.file?(input)
+    warn "#{PROG}: no such file: #{input}"
+    exit 1
+  end
+
+  json = File.read(input)
+  begin
+    require 'json'
+    JSON.parse(json)  # fail fast on a non-JSON / corrupt trace
+  rescue JSON::ParserError => e
+    warn "#{PROG}: #{input} is not valid JSON: #{e.message}"
+    exit 1
+  end
+
+  html = Capybara::Simulated::Trace.render_viewer(json)
+
+  if out == '-'
+    $stdout.write(html)
+    return
+  end
+  # Default output: a temp file named after the trace (re-runs overwrite).
+  out ||= File.join(Dir.tmpdir, File.basename(input).sub(/\.json\z/, '') + '.html')
+  File.write(out, html)
+  warn "wrote #{out}"
+  open_in_browser(File.expand_path(out)) unless open == false
+end
+
+def main(argv)
+  case argv.first
+  when 'trace'
+    cmd_trace(argv.drop(1))
+  when '-v', '--version'
+    require 'capybara/simulated/version'
+    puts Capybara::Simulated::VERSION
+  when nil, '-h', '--help'
+    puts <<~USAGE
+      Usage: #{PROG} <command> [options]
+
+      Commands:
+        trace TRACE.json   render a trace JSON into a self-contained HTML viewer
+
+      Run `#{PROG} trace --help` for command options.
+    USAGE
+  else
+    warn "#{PROG}: unknown command: #{argv.first}"
+    warn "Run `#{PROG} --help`."
+    exit 1
+  end
+end
+
+main(ARGV)