capybara-simulated 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 692a6a8f67870e2078ba815a0698831f3cec4ada4dc3d79d9af795156107e37b
-  data.tar.gz: 734a4cfe94f4cd93367b95082619e10729cb4ebf1f83a890b4d87c78ce5fd3cf
+  metadata.gz: 3b2b947ec8b6945ec441d61c70a2bf0155283696c7d8188a135c990850149f68
+  data.tar.gz: c7530db87c7b019f25db0370213c6965a4c3f44172284ef469f84e8617319291
 SHA512:
-  metadata.gz: 9c9bfde944aad7339e4d7153e2d49b3b6834662fc5bcaf945a63899ca580493d1c67bfbd625ce7e06683bdbfacab83fa8192af7f02a73d5228f080dc22fc1dda
-  data.tar.gz: da6971ee07edd867e00baa4e6d382ff291d5d0c8c437084f6f4d7dba50ae5c0596e4726db9be58f1d7a6847340fccff847d06d0056fdb8de3847a703887a4c28
+  metadata.gz: 1c3e5d6358892be026316a31531ed4ced5e66f52ac0dafcda51236977f8f94f40b5465e9653cce4ce2ad84cee0ef4d29b8fbe2d850cd94efb3f1a3ab47db3eb6
+  data.tar.gz: '099d9b40e65a21667a543721f26b1df60176a2651da945f175016d5d85bbd81b0296099a17bf23b2a415101387489573d6b487aecdf8255ee0a923935d0f9b10'

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,33 +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 concurrency, no WebSocket.
-- **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
 
@@ -76,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
 
@@ -288,21 +268,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,
@@ -333,53 +298,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, screenshots, and drag pixel coordinates** are out of
-  scope by design — use Selenium / Cuprite. (EventSource and Web
-  Workers *are* implemented.)
-- **`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`); 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
 
@@ -413,39 +389,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).