capybara-simulated 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f13ed6ad46dbf9e9537d89bc384c5ef7386242fa28c9e4fc549b1fda04fd7d8
-  data.tar.gz: 2cd0e24a3eb808728d7a533369b3ac2beafc99accf8fa4c1ec9f9b4af1b60f03
+  metadata.gz: 692a6a8f67870e2078ba815a0698831f3cec4ada4dc3d79d9af795156107e37b
+  data.tar.gz: 734a4cfe94f4cd93367b95082619e10729cb4ebf1f83a890b4d87c78ce5fd3cf
 SHA512:
-  metadata.gz: b26b98c5b972110458565e0a60b6292cd6a446e331636d662e34aed1a4c9456a130aa67f52499f4954820c30a0b9ae22dff2870b25f50556bb577a37a719b042
-  data.tar.gz: cf2cb128d6187eff1fa4c3fd06b928e933cbc1d4c0ec062f4885f3bd31ad847136e8736e604879e0fdb9eba629647802133265d596e3abc451238f499dfb0be3
+  metadata.gz: 9c9bfde944aad7339e4d7153e2d49b3b6834662fc5bcaf945a63899ca580493d1c67bfbd625ce7e06683bdbfacab83fa8192af7f02a73d5228f080dc22fc1dda
+  data.tar.gz: da6971ee07edd867e00baa4e6d382ff291d5d0c8c437084f6f4d7dba50ae5c0596e4726db9be58f1d7a6847340fccff847d06d0056fdb8de3847a703887a4c28

data/README.md

@@ -14,6 +14,57 @@ 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 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.
+
 ## Status
 
 The architecture and behaviour are stable. Correctness is held to two
@@ -305,15 +356,30 @@ 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, 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
+  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.
 
 ## Architecture