capybara-simulated 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f13ed6ad46dbf9e9537d89bc384c5ef7386242fa28c9e4fc549b1fda04fd7d8
-  data.tar.gz: 2cd0e24a3eb808728d7a533369b3ac2beafc99accf8fa4c1ec9f9b4af1b60f03
+  metadata.gz: 02f56bfd3215e67c4a8faa799352e0ae3c399557f928926cafcdc9dde7dd2b9c
+  data.tar.gz: 12e88e441d93de921d0727bfae9e3728cc56d100f8e32e525e37e21a28f0e273
 SHA512:
-  metadata.gz: b26b98c5b972110458565e0a60b6292cd6a446e331636d662e34aed1a4c9456a130aa67f52499f4954820c30a0b9ae22dff2870b25f50556bb577a37a719b042
-  data.tar.gz: cf2cb128d6187eff1fa4c3fd06b928e933cbc1d4c0ec062f4885f3bd31ad847136e8736e604879e0fdb9eba629647802133265d596e3abc451238f499dfb0be3
+  metadata.gz: a1f22b4a5d7ffec1b33080982aa169b5b3356c014d49a399de4cf5b5a430021eec7fb1ba4d624b00769640ffdcd314e55df765afdd44ac90575c88cb137519c9
+  data.tar.gz: 04d95fd0e7215800124d4d81de11247b814e352c0b511d550bb9bb1557a0af069c1261b52a570e82f6100cab90e07d627b18b7a02267f193dd92c4c98c92e2cd

data/README.md

@@ -14,6 +14,59 @@ 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.
 
+## Is it a fit?
+
+**A good fit when** your tests are JavaScript-driven but don't depend on
+visual layout:
+
+- **Fast, in-process** — no Chrome to boot, no WebDriver, no Node
+  toolchain. About **1.9× faster** than a headless browser on
+  server-rendered / Hotwire apps, and roughly at parity on JS-heavy SPAs
+  (with rusty_racer).
+- **Deterministic** — a virtual clock and synchronous in-process execution
+  remove the wall-clock timing, network, and rendering races that make
+  headless-browser suites flaky.
+- **Real front-end JS runs**: inline `<script>` + event handlers,
+  MutationObserver, custom elements, `<template>`, Shadow DOM, ES modules
+  + importmap, **Hotwire (Stimulus + Turbo)**, Trix.
+- **Drop-in**: the Capybara DSL is unchanged — register `:simulated` and
+  go. Just this gem plus one JS-engine gem.
+- **Held to spec**: a vendored
+  [web-platform-tests](https://github.com/web-platform-tests/wpt)
+  conformance gate plus five real app suites (see [Status](#status)).
+
+**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.
+
 ## Status
 
 The architecture and behaviour are stable. Correctness is held to two
@@ -305,15 +358,44 @@ referenced page-specific DOM.
   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.)
+- **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
+  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.
 
 ## Architecture