capybara-simulated 0.9.0 → 0.10.0

data/lib/capybara/simulated/minitest.rb

@@ -19,6 +19,22 @@ module Capybara
     module MinitestTrace
       module_function
 
+      # Paint each live trace's final state, while the page is still the one the test ended on.
+      # Stored on the trace so `TracePersistence` finds it already taken; a passing test pays
+      # nothing (`real_failures` is what decides), and nothing here may raise into a teardown.
+      def capture_screenshots(test)
+        return if real_failures(test).empty?
+
+        Capybara::Simulated::Driver.each_live_on_thread(Thread.current) do |driver|
+          next unless driver.respond_to?(:tracing?) && driver.tracing?
+
+          shot = driver.trace_screenshot
+          driver.current_trace.metadata[:screenshot] = shot if shot
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          warn "capybara-simulated: trace screenshot failed: #{e.class}: #{e.message}"
+        end
+      end
+
       # Where the test method is defined, as `path:line` (best effort).
       def source_file(test)
         loc = test.class.instance_method(test.name).source_location
@@ -44,6 +60,12 @@ if (dir = ENV['CSIM_TRACE_DIR']) && !dir.empty?
   # no-ops for every non-Capybara test.
   hook = Module.new do
     define_method(:after_teardown) do
+      # BEFORE the host's teardown, because that is where `Capybara.reset_sessions!` lives and the
+      # page is rebuilt by it: a screenshot taken after `super()` is a picture of the blank page
+      # the reset installed, stored as "the state the failing example ended in". (RSpec's
+      # `prepend_after` already runs first, so only this host needs the split.) The trace itself is
+      # still WRITTEN after teardown — that is what the `super()` ordering was for.
+      Capybara::Simulated::MinitestTrace.capture_screenshots(self)
       super()
     ensure
       begin

data/lib/capybara/simulated/node.rb

@@ -25,25 +25,22 @@ module Capybara
 
       attr_reader :handle_id, :context_gen, :realm_id
 
-      # Tick the virtual clock unconditionally on the text path. Unlike
-      # `Node#[]` (attribute reads), the text readers are NOT preceded by
-      # a `find_css` that ticks under the wall throttle: `have_text` /
-      # `assert_text` polls `.text` directly against an already-found,
-      # cached scope node, so the find loop short-circuits without
-      # re-ticking. Gating these behind `timer_wait_elapsed?` therefore
-      # stalls a pure text-poll loop's virtual clock and scheduled
-      # `setTimeout`s never fire (smoke_spec virtual-clock contract).
-      # They run ~once per poll-scope (not once per matched result like
-      # the attribute filters the audit targeted), so they are not the
-      # O(N) hot path and are safe to tick every call.
+      # The text readers advance the virtual clock, unlike `Node#[]`
+      # (attribute reads) which sit behind a `find_css` that already
+      # ticked: `have_text` / `assert_text` polls `.text` directly against
+      # an already-found, cached scope node, so the find loop
+      # short-circuits without re-ticking and a page waiting on a timer
+      # would never make progress. `tick_for_read` decides WHEN: a read
+      # leaves the clock where it is and the next query pays the step, so
+      # a walk over one query's results can't be stranded mid-way.
       def all_text
-        browser.tick_real_time
+        browser.tick_for_read(handle_id)
         check_stale
         normalize_spacing(browser.all_text(handle_id))
       end
 
       def visible_text
-        browser.tick_real_time
+        browser.tick_for_read(handle_id)
         check_stale
         normalize_visible_spacing(browser.visible_text(handle_id))
       end

data/lib/capybara/simulated/quickjs_runtime.rb

@@ -104,7 +104,17 @@ module Capybara
           }
         end
 
-        def checkout = @queue.pop
+        # Never BLOCK waiting on the warmers: on a loaded runner (parallel CI
+        # — every core already runs a sibling worker process) they can fall
+        # behind a session-per-iteration spec, and a blocking pop then parks
+        # the example until the global spec timeout fires. An empty pool
+        # instead costs the caller one inline `VM.new` — never slower than
+        # waiting for a warmer to build the same VM on a busier thread.
+        def checkout
+          @queue.pop(true)
+        rescue ThreadError
+          @queue.closed? ? nil : Quickjs::VM.new(**@vm_options)
+        end
 
         # SizedQueue#close unblocks pushers + makes future pops return
         # nil — necessary at process exit because a warmer mid-`VM.new`
@@ -150,6 +160,17 @@ module Capybara
         normalize(result)
       end
 
+      # Run `code` for its EFFECT, skipping the completion value. Mirrors
+      # `V8Runtime#eval_void` (which is where it earns its keep — rusty_racer
+      # marshals a completion value by RUNNING JS on it, so a discarded value
+      # can fail the eval); here it just skips `normalize`.
+      def eval_void(code)
+        v = vm
+        v.eval_code(code.to_s)
+        v.drain_jobs!
+        nil
+      end
+
       # the V8 engine drains its microtask queue at
       # the end of every call (V8's default microtask policy). QuickJS
       # does not: `js_std_await` only pumps pending jobs while it's
@@ -367,6 +388,9 @@ module Capybara
         # for every `<script type="module">`; V8 registers it too via
         # `V8Runtime#attach_native_module_loader`.
         browser = @browser
+        # The V8 path appends a SW fetch-context tail (moduleSwCtx, bridge.entry.js)
+        # that this block deliberately drops: QuickJS module loads don't dispatch SW
+        # fetch events (the engine runs `--tag ~wpt`; no covered observer).
         v.define_function('__csim_evalEsmEntry') {|url, inline_src|
           RuntimeShared.safe_call { browser.eval_esm_module(url, inline_src) }
           nil
@@ -410,6 +434,10 @@ module Capybara
         vm.define_function('__csim_swPostToClient') {|client_id, data| sw_hooks[:post_to_client]&.call(client_id, data); nil } if sw_hooks[:post_to_client]
         vm.define_function('__csim_swFocusClient')  {|client_id|       sw_hooks[:focus_client]&.call(client_id);       nil } if sw_hooks[:focus_client]
         vm.define_function('__csim_swClaim') { sw_hooks[:claim]&.call; nil } if sw_hooks[:claim]
+        vm.define_function('__csim_swUnregisterRequest') { sw_hooks[:unregister]&.call; nil } if sw_hooks[:unregister]
+        vm.define_function('__csim_swNoteRouterRules') { sw_hooks[:router]&.call; nil } if sw_hooks[:router]
+        vm.define_function('__csim_swRaceNetwork') {|fetch_id, realm_id, url, method| sw_hooks[:race_network]&.call(fetch_id, realm_id, url, method); nil } if sw_hooks[:race_network]
+        vm.define_function('__csim_swExtendedChanged') {|n| sw_hooks[:extended]&.call(n); nil } if sw_hooks[:extended]
         vm.define_function('__csim_swFetchRespond') {|fetch_id, resp, realm_id| sw_hooks[:fetch_respond]&.call(fetch_id, resp, realm_id); nil } if sw_hooks[:fetch_respond]
         vm.define_function('__csim_swFetchStream') {|fetch_id, kind, payload, realm_id| sw_hooks[:fetch_stream]&.call(fetch_id, kind, payload, realm_id); nil } if sw_hooks[:fetch_stream]
         vm.define_function('__csim_workerPortPost')     {|channel, data| sw_hooks[:port_post]&.call(channel, data); nil } if sw_hooks[:port_post]
@@ -424,13 +452,16 @@ module Capybara
         vm.eval_code('__csim_installWorkerScope();')
         vm.drain_jobs!
         WorkerRuntime.new(
-          eval_fn:           ->(s)     { v = vm.eval_code(s.to_s); vm.drain_jobs!; v },
+          eval_void_fn:      ->(s)     { vm.eval_code(s.to_s); vm.drain_jobs!; nil },
           call_fn:           ->(n, *a) { v = vm.call(n.to_s, *a); vm.drain_jobs!; v },
           drain_microtasks:  ->        { vm.drain_jobs! },
           drain_timers:      ->        { vm.call('__drainTimers', 50) },
           has_ready_timer:   ->        { !!vm.call('__hasReadyTimer') },
           # quickjs.rb has no explicit dispose; GC reclaims the VM.
           dispose:           ->        { nil }
+          # …and no cross-thread interrupt either, so `terminate` stays nil: a QuickJS worker
+          # inside a call is still only reachable through its inbox, and its own 30 s eval timeout
+          # is the backstop.
         )
       end
 

data/lib/capybara/simulated/runtime_shared.rb

@@ -41,8 +41,14 @@ module Capybara
       # JS exception that crashes the whole script chain. Bodies take
       # `(browser, *js_args)` and return whatever the JS caller expects.
       BROWSER_HOST_FNS = {
-        '__rackFetch'                => ->(b, *a) { b.rack_fetch(a[0], a[1], a[2], a[3], a[4], a[5], credentials: a[6] || 'same-origin', referrer_policy: a[7], referrer: a[8], cache_mode: a[9] || 'default', initiator: a[10], site_seed: a[11], origin_null: a[12]) },
+        '__rackFetch'                => ->(b, *a) { b.rack_fetch(a[0], a[1], a[2], a[3], a[4], a[5], credentials: a[6] || 'same-origin', referrer_policy: a[7], referrer: a[8], cache_mode: a[9] || 'default', initiator: a[10], site_seed: a[11], origin_null: a[12], client_url: a[13], cookie_cross_site: a[14] == true, nav_dest: a[15]) },
         '__csimExternalAsset'        => ->(b, *a) { b.external_asset_source(a[0]) },
+        # fetch(…, {keepalive}) — eager detached-thread dispatch + one-shot result poll.
+        '__csim_keepaliveStart'      => ->(b, *a) { b.keepalive_start(a[0], a[1], a[2], a[3], a[4], a[5], a[6], a[7], a[8], a[9], a[10]) },
+        '__csim_keepaliveTake'       => ->(b, *a) { b.keepalive_take(a[0]) },
+        # A controlled document's external classic script → its controller's fetch
+        # event, synchronously (destination 'script'). See sw_script_subresource_fetch.
+        '__csim_swScriptFetch'       => ->(b, *a) { b.sw_script_subresource_fetch(a[0], a[1], a[2], a[3], a[4] || 'script', a[5] || 'no-cors', a[6] || 'include', binary: a[7] == true, integrity: a[8] || '') },
         '__locationAssign'           => ->(b, *a) { b.location_assign(a[0]); nil },
         '__locationReload'           => ->(b, *_) { b.location_reload; nil },
         # A nested browsing context navigating its OWN location (a[1] = the frame's
@@ -117,7 +123,7 @@ module Capybara
         # is). `opener` = rel=opener (target=_blank defaults to noopener); the Driver
         # forces noopener for a cross-partition blob: target.
         '__csimOpenAuxFromRealm'     => ->(b, *a) { b.open_aux_from_realm(a[0], a[1], a[2]); nil },
-        '__csimWindowPostMessage'    => ->(b, *a) { b.post_message_to_window(a[0], a[1], a[2]); nil },
+        '__csimWindowPostMessage'    => ->(b, *a) { b.post_message_to_window(a[0], a[1], a[2], a[3]); nil },
         '__csimBroadcast'            => ->(b, *a) { b.broadcast_to_windows(a[0], a[1], a[2].to_i, a[3]); nil },
         # BroadcastChannel isolate-wide, creation-ordered registry (the multi-realm delivery path). A
         # channel registers on construction / unregisters on close; `bc_post` snapshots the eligible
@@ -146,10 +152,19 @@ module Capybara
         # a[3] is the CREATING realm (the worker dies when it is discarded); a[4] that context's
         # CURRENT controller handle, which a DEDICATED worker inherits rather than scope-matching
         # its own — often opaque (blob:/data:) — script URL. 0 when the creator is uncontrolled.
-        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0], shared: !!a[1], creator_key: a[2], realm_id: a[3].to_i, controller_handle: a[4].to_i) },
+        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0], shared: !!a[1], creator_key: a[2], realm_id: a[3].to_i, controller_handle: a[4].to_i, script_type: a[5]) },
         # navigator.serviceWorker.register (universal-server only) — spawn a worker
         # running the SW script as an executor context. Returns its handle.
-        '__csim_serviceWorkerRegister' => ->(b, *a) { b.worker_spawn(a[0], service: true, creator_key: a[1]) },
+        '__csim_serviceWorkerRegister' => ->(b, *a) { b.worker_spawn(a[0], service: true, creator_key: a[1], sw_scope: a[2], script_type: a[3]) },
+        # Registration update surface: the updateViaCache mode is REGISTRATION-wide state
+        # (scope-keyed, host-owned — a frame's registration object must see the mode the
+        # top window set), and __csim_swUpdateFetch is the Update algorithm's fetch +
+        # byte-check (sw_registration_update_fetch).
+        '__csim_swSetUpdateViaCache'   => ->(b, *a) { b.sw_set_update_via_cache(a[0], a[1]) },
+        '__csim_swScopeUpdateViaCache' => ->(b, *a) { b.sw_scope_update_via_cache(a[0]) },
+        '__csim_swUpdateFetch'         => ->(b, *a) { b.sw_registration_update_fetch(a[0], a[1], a[2].to_i, a[3]) },
+        '__csim_swNoteImport'          => ->(b, *a) { b.sw_note_import(a[0].to_i, a[1], a[2]) },
+        '__csim_swDropPendingScript'   => ->(b, *a) { b.sw_drop_pending_script(a[0]) },
         '__csim_workerPostToWorker'  => ->(b, *a) { b.worker_post_to_worker(a[0], a[1]); nil },
         # ServiceWorker.postMessage from a client window → the SW's `message` event (source = client).
         '__csim_serviceWorkerPostMessage' => ->(b, *a) { b.service_worker_post_message(a[0], a[1], a[2], a[3]); nil },
@@ -164,6 +179,12 @@ module Capybara
         # control is installed, by the realm, because only it knows its own URL, frame type and
         # controller. `a[3]` is the controlling worker's handle, 0 when uncontrolled.
         '__csimNoteClient' => ->(b, *a) { b.sw_note_client(a[0], a[1], a[2], a[3]); nil },
+        # A worker client's controller changed (claim adoption inside the worker isolate) —
+        # update the HOST-owned record (a worker must not take the realm-style report path).
+        '__csim_workerNoteController' => ->(b, *a) { b.sw_note_worker_controller(a[0], a[1]); nil },
+        # A controlled worker's importScripts, through its SW's fetch event (synchronous
+        # on the calling worker's thread — sw_import_script_fetch).
+        '__csim_swImportFetch' => ->(b, *a) { b.sw_import_script_fetch(a[0], a[1], a[2]) },
         # A controlled client's fetch → the controlling SW's `fetch` event. Returns false if the SW
         # is gone (client falls back to the network).
         '__csim_serviceWorkerControllerFetch' => ->(b, *a) { b.service_worker_controller_fetch(a[0], a[1], a[2], a[3]) },
@@ -173,14 +194,27 @@ module Capybara
         # Client lifecycle mirrors scope→active-worker into Ruby so a navigation (fetched
         # Ruby-side before the destination realm's JS exists) can find its controlling SW.
         '__csim_swRegisterScope'      => ->(b, *a) { b.sw_register_scope(a[0], a[1]); nil },
+        # A live registration object exists at this scope (Register job success) — claim's
+        # longest-registration-wins must see it before any worker state exists.
+        '__csim_swNoteRegistered'     => ->(b, *a) { b.sw_note_registered(a[0]); nil },
+        # The lifecycle reached 'activating': the scope's active worker exists but its
+        # activate waitUntil hasn't settled — Handle Fetch parks functional events on it.
+        '__csim_swNoteActivating'     => ->(b, *a) { b.sw_note_activating(a[0], a[1]); nil },
         '__csim_swUnregisterScope'    => ->(b, *a) { b.sw_unregister_scope(a[0]); nil },
+        # unregister() parked its Clear Registration: the workers live on until no client is
+        # using the registration and no extended work is pending (see sw_note_uninstalling).
+        '__csim_swNoteUninstalling'   => ->(b, *a) { b.sw_note_uninstalling(a[0], a[1], a[2] || []); nil },
         # The active worker handle at an EXACT scope (0 if none), so a register() from a realm with no
         # local registration (a different iframe registering an already-active scope) can synthesize a
         # registration reflecting the shared active worker instead of installing a duplicate.
         '__csim_swActiveHandleForScope' => ->(b, *a) { b.sw_active_handle_for_scope(a[0]) },
-        # Does this worker still control any client? An incoming worker may only activate once the
-        # outgoing one controls nothing (or skipWaiting is called) — see _scheduleLifecycle.
-        '__csim_swControlsClients'    => ->(b, *a) { b.sw_worker_controls_clients?(a[0]) },
+        # The committed script type at that scope — the synthesized registration's
+        # reg._workerType (module SWs observed from a second realm).
+        '__csim_swScopeWorkerType'      => ->(b, *a) { b.sw_scope_worker_type(a[0]) },
+        # HTML "try activate" in one atomic verdict: may `candidate` (installed, in the waiting
+        # slot) take over from `outgoing`? Extended work / controllees / skipWaiting are all
+        # host state — see sw_may_activate? and _scheduleLifecycle.
+        '__csim_swMayActivate'        => ->(b, *a) { b.sw_may_activate?(a[0], a[1]) },
         '__csim_swNoteActivationParked' => ->(b, *_) { b.sw_note_activation_parked; nil },
         # Navigation Preload state (NavigationPreloadManager), keyed by the registration's active
         # worker handle — reached identically from the client (registration.active._handle) and the
@@ -190,10 +224,13 @@ module Capybara
         # A navigation (iframe/document load) → its controlling SW's `fetch` event, awaited
         # synchronously. Returns the response wire hash, or nil to load from the network.
         '__csim_swNavigationFetch'    => ->(b, *a) { b.service_worker_navigation_fetch(a[0], is_reload: !!a[1], is_history: !!a[2], referrer_source: a[3], method: a[4] || 'GET', body_b64: a[5] || '', content_type: a[6]) },
+        '__csim_frameNavigationFetch' => ->(b, *a) { b.frame_navigation_fetch(a[0], a[2], is_reload: !!a[1], secure_ancestors: a[3].nil? || !!a[3], method: a[4] || 'GET', body_b64: a[5] || '', content_type: a[6], defer_ok: !!a[7], dest: a[8] || 'iframe') },
         '__csim_workerTerminate'     => ->(b, *a) { b.worker_terminate(a[0]); nil },
         '__csim_decodeImage'         => ->(b, *a) { b.decode_image(a[0], a[1], a[2]) },
         '__csim_renderText'          => ->(b, *a) { b.render_text(a[0], a[1], a[2], a[3], a[4]) },
+        '__csim_fontAdvances'        => ->(b, *a) { b.font_advance_table(a[0], a[1]) },
         '__csim_loadImage'           => ->(b, *a) { b.load_image(a[0], !!a[1], a[2] || 'same-origin') },
+        '__csim_imageLoadStart'      => ->(b, *a) { b.image_load_start(a[0], !!a[1], a[2] || 'same-origin') },
         '__csim_blobRegister'        => ->(b, *a) { b.blob_register(a[0], a[1], a[2]); nil },
         # WHATWG/UTS46 IDNA for the URL parser's host processing (the JS tr46 stub
         # delegates non-ASCII / xn-- hosts here; ASCII stays in-VM).
@@ -206,7 +243,7 @@ module Capybara
         # this so it doesn't bail before an async message (e.g. a freshly-spawned
         # worker's first postMessage) has had a chance to land.
         '__csim_asyncIoPending'      => ->(b, *_a) { b.async_io_pending? },
-        '__csim_transferStash'       => ->(b, *a) { b.transfer_buffer_stash(a[0]) },
+        '__csim_transferStash'       => ->(b, *a) { b.transfer_buffer_stash(a[0], a[1]) },
         '__csim_transferFetch'       => ->(b, *a) { b.transfer_buffer_fetch_for_js(a[0]) },
         # Zero-copy postMessage transfer-token bookkeeping (see Browser#drop_pending_transfers).
         '__csim_transferIssued'      => ->(b, *a) { b.transfer_token_issued(a[0]); nil },
@@ -216,7 +253,7 @@ module Capybara
         # eager-@app.calls a foreign URL (side effects: extra visit / log row).
         '__csim_allHostsLocal'       => ->(b, *a) { b.send(:all_hosts_local?) },
         '__csim_decodeVideoFrame'    => ->(b, *a) { b.decode_video_frame(a[0]) },
-        '__csim_videoBytesB64'       => ->(b, *a) { b.video_bytes_b64(a[0]) },
+        '__csim_videoBytesB64'       => ->(b, *a) { b.video_bytes_b64(a[0], !!a[1], a[2] || 'same-origin', a[3]) },
         '__csim_encodeImage'         => ->(b, *a) { b.encode_image(a[0], a[1], a[2], a[3], a[4]) },
         # WebAuthn create / get raise `WebauthnState::Error` carrying
         # the DOMException name (`InvalidStateError`, …); rescue here

data/lib/capybara/simulated/stack_resolver.rb

@@ -25,6 +25,11 @@ module Capybara
       @@maps = {}
       @@lock = Mutex.new
 
+      # Drop the fetched source maps (part of `Browser.clear_http_cache`).
+      def self.clear
+        @@lock.synchronize { @@maps.clear }
+      end
+
       def initialize(browser)
         @browser = browser
       end

data/lib/capybara/simulated/trace.rb

@@ -5,9 +5,13 @@ require 'fileutils'
 
 module Capybara
   module Simulated
-    # Per-test trace of Capybara actions with DOM snapshots, console
-    # output, and network requests interleaved. JSON output, one file
-    # per test — downstream tooling builds whatever viewer it wants.
+    # Per-test trace of Capybara actions with DOM snapshots, screenshots,
+    # console output, and network requests interleaved. JSON output, one
+    # file per test — downstream tooling builds whatever viewer it wants.
+    #
+    # A screenshot is carried INLINE as a data URL, like everything else here:
+    # the viewer's whole point is that it opens from `file://` with no server,
+    # and a side-file image would need one (or a second artefact to lose).
     #
     # Off by default. `CSIM_TRACE_DIR=/path/to/dir` enables auto-mode
     # via `Browser#record_action`; the RSpec hook in `csim_rspec.rb`
@@ -21,6 +25,7 @@ module Capybara
         :url_before,
         :url_after,
         :dom_after,    # only the post-action snapshot — the previous step's `dom_after` is the implicit "before"
+        :shot_after,   # …and the same moment PAINTED, as a `data:image/png;base64,…` URL
         :console,
         :network,
         :elapsed_ms,
@@ -34,17 +39,30 @@ module Capybara
 
       # Render the self-contained HTML viewer for a trace JSON *string*,
       # embedding it inline (the `capybara-simulated trace` CLI is the
-      # caller). `</` → `<\/` so an embedded `</script>` inside a DOM
-      # snapshot can't close the data block early — still valid JSON
-      # (`\/` is a legal JSON escape for `/`). The whole point of inline
-      # embedding over fetch / `import … with { type: 'json' }` is that
-      # the result opens straight from `file://` with no server (module /
-      # fetch loads are CORS-blocked for `file://` origins).
+      # caller). The whole point of inline embedding over fetch / `import
+      # … with { type: 'json' }` is that the result opens straight from
+      # `file://` with no server (module / fetch loads are CORS-blocked
+      # for `file://` origins).
+      #
+      # EVERY `<` is escaped, not just `</`. Escaping only the closing
+      # form looks sufficient — nothing can close the block early — and
+      # is worse than nothing: `<!--` puts the HTML tokenizer into
+      # script-data-escaped state and a following `<script` into
+      # script-data-DOUBLE-escaped state, where a real `</script>` no
+      # longer closes the element and only `</script` can leave... which
+      # is exactly what the old escaping guaranteed could never appear.
+      # A DOM snapshot of a page with a commented-out script tag —
+      # `<!-- <script src="/analytics.js"></script> -->`, which is not an
+      # exotic thing for a page to contain — therefore swallowed the rest
+      # of the viewer as text and rendered a blank white page, with
+      # nothing in the console to say why. `\u003c` is a legal escape
+      # inside a JSON string, `<` cannot appear anywhere else in JSON, and
+      # `JSON.parse` restores it, so the round trip is exact.
       def self.render_viewer(json_text)
         template = (@viewer_template ||= File.read(VIEWER_TEMPLATE_PATH))
         # Block form: the replacement is taken literally, so backslashes
         # in the JSON aren't interpreted as regexp backreferences.
-        template.sub(VIEWER_DATA_TOKEN) { json_text.to_s.gsub('</', '<\/') }
+        template.sub(VIEWER_DATA_TOKEN) { json_text.to_s.gsub('<', '\u003c') }
       end
 
       attr_reader :steps, :metadata
@@ -99,7 +117,7 @@ module Capybara
         @network_buf = []
       end
 
-      def finish_step(url_after: nil, dom_after: nil, error: nil)
+      def finish_step(url_after: nil, dom_after: nil, shot_after: nil, error: nil)
         return unless @open_step
         s = @open_step
         @steps << Step.new(
@@ -109,6 +127,7 @@ module Capybara
           url_before:   s[:url_before],
           url_after:    url_after,
           dom_after:    dom_after,
+          shot_after:   shot_after,
           console:      @console_buf,
           network:      @network_buf,
           elapsed_ms:   (s[:start_ms] - @started_at).round,
@@ -120,6 +139,14 @@ module Capybara
         @network_buf = []
       end
 
+      # Is the step just recorded another attempt at the SAME failing action? Capybara retries an
+      # action for its whole wait window, and every attempt records a step — so this is what keeps
+      # a screenshot from being painted 60 times for one failed click.
+      def retrying_failure?(kind, description)
+        last = @steps.last
+        !last.nil? && !last.error.nil? && last.kind == kind && last.description == description
+      end
+
       def empty? = @steps.empty?
 
       def to_h

data/lib/capybara/simulated/trace_persistence.rb

@@ -23,12 +23,38 @@ module Capybara
       # unless the driver actually recorded something.
       def persist(driver, dir, title:, file:, outcome:, exception:)
         return unless driver.respond_to?(:tracing?) && driver.tracing?
+        # `engine` only when the driver can say — and never at the cost of the write: this method
+        # exists to produce the trace file, so a driver call that raises must not take it down
+        # (the same reason the screenshot below is in its own rescue). A driver that has no answer
+        # leaves the key out rather than writing `null`.
+        engine = begin
+          driver.js_engine if driver.respond_to?(:js_engine)
+        rescue StandardError
+          nil
+        end
         driver.current_trace.metadata.merge!(
-          title:     title,
-          file:      file,
-          outcome:   outcome,
-          exception: exception
+          {title: title, file: file, outcome: outcome, exception: exception, engine: engine}.compact
         )
+        # The state the example ENDED in, painted once — and painted HERE, after the example,
+        # rather than per step: a paint is ~50 ms on V8 and ~525 ms on QuickJS, and doing it inside
+        # an action's failure path puts it inside Capybara's retry window, where it can turn an
+        # action a retry would have rescued into a failure (measured: a click waiting on an overlay
+        # went from 35 ms to 563 ms). Only for a failure — that is the state anyone opens the trace
+        # to look at, and a passing example should pay nothing.
+        # …unless the host already took it, before its own teardown reset the page (see
+        # `minitest.rb`). Whoever gets there first with a LIVE page wins.
+        if outcome.to_s == 'failed' && !driver.current_trace.metadata[:screenshot] &&
+           driver.respond_to?(:trace_screenshot)
+          # In its own rescue, and rescuing more than `StandardError`: the paint is the one part of
+          # persisting that runs arbitrary engine code, and the trace file — the thing this method
+          # exists to write — must not be lost to it.
+          begin
+            shot = driver.trace_screenshot
+            driver.current_trace.metadata[:screenshot] = shot if shot
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            warn "capybara-simulated: trace screenshot failed: #{e.class}: #{e.message}"
+          end
+        end
         driver.stop_tracing(path: File.join(dir, "#{slug(title)}.json"))
       end