capybara-simulated 0.4.0 → 0.6.0

data/lib/capybara/simulated/js/snapshot_stubs.js

@@ -56,6 +56,40 @@ if (typeof globalThis.TextDecoder === 'undefined') {
     }
   };
 }
+// parse5 unpacks its base64-packed named-character-reference table with `atob`
+// AT MODULE-LOAD = snapshot-BUILD time here, and the V8 snapshot context has no
+// `atob`. Provide a correct RFC 4648 base64 decoder (+ encoder) before the
+// vendor bundle so parse5's table bakes correctly. The bridge's encoding.js
+// later overrides `globalThis.atob`/`btoa` for app code; parse5 keeps only the
+// decoded table (no reference to atob), so this stub only matters at build time.
+if (typeof globalThis.atob === 'undefined') {
+  const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  globalThis.atob = function (input) {
+    const s = String(input).replace(/[ \t\n\f\r=]/g, '');
+    let out = '', acc = 0, bits = 0;
+    for (let i = 0; i < s.length; i++) {
+      const v = B64.indexOf(s[i]);
+      if (v < 0) continue;
+      acc = (acc << 6) | v; bits += 6;
+      if (bits >= 8) { bits -= 8; out += String.fromCharCode((acc >> bits) & 0xff); }
+    }
+    return out;
+  };
+  globalThis.btoa = function (input) {
+    const s = String(input); let out = '';
+    for (let i = 0; i < s.length; i += 3) {
+      const a = s.charCodeAt(i);
+      const b = i + 1 < s.length ? s.charCodeAt(i + 1) : NaN;
+      const c = i + 2 < s.length ? s.charCodeAt(i + 2) : NaN;
+      const e1 = a >> 2;
+      const e2 = ((a & 3) << 4) | (isNaN(b) ? 0 : b >> 4);
+      const e3 = isNaN(b) ? 64 : (((b & 15) << 2) | (isNaN(c) ? 0 : c >> 6));
+      const e4 = isNaN(c) ? 64 : c & 63;
+      out += B64[e1] + B64[e2] + (e3 === 64 ? '=' : B64[e3]) + (e4 === 64 ? '=' : B64[e4]);
+    }
+    return out;
+  };
+}
 globalThis.__csim_parseUrl = function (input, base) {
   return {
     href: 'http://placeholder/', protocol: 'http:',

data/lib/capybara/simulated/minitest.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'minitest'
+require_relative 'trace_persistence'
+
+# Minitest integration for trace file output. Require it from your
+# `test_helper` / `application_system_test_case.rb`:
+#
+#   require 'capybara/simulated/minitest'
+#
+# With `CSIM_TRACE_DIR=/path/to/dir` set, each test that recorded a trace
+# is persisted to `<dir>/<Class_test_name>.json` after it runs. Inert
+# when the env var is unset. Whether a trace is recorded at all is
+# governed separately by `CSIM_TRACE` (off / on-failure / full) — see
+# Browser. Render a saved trace into an HTML viewer with
+# `capybara-simulated trace <file>.json`.
+module Capybara
+  module Simulated
+    module MinitestTrace
+      module_function
+
+      # Where the test method is defined, as `path:line` (best effort).
+      def source_file(test)
+        loc = test.class.instance_method(test.name).source_location
+        loc && loc.join(':')
+      rescue NameError
+        nil
+      end
+
+      # Skips aren't failures for outcome purposes. `::Minitest` —
+      # unqualified `Minitest` here resolves to `Capybara::Minitest`
+      # (Capybara ships that submodule), which has no `Skip`.
+      def real_failures(test)
+        test.failures.reject {|f| f.is_a?(::Minitest::Skip) }
+      end
+    end
+  end
+end
+
+if (dir = ENV['CSIM_TRACE_DIR']) && !dir.empty?
+  FileUtils.mkdir_p(dir)
+  # Prepend so `after_teardown` chains via `super` and we run after the
+  # host's own teardown. Guarded by `tracing?` inside persist_all, so it
+  # no-ops for every non-Capybara test.
+  hook = Module.new do
+    define_method(:after_teardown) do
+      super()
+    ensure
+      begin
+        fails = Capybara::Simulated::MinitestTrace.real_failures(self)
+        Capybara::Simulated::TracePersistence.persist_all(
+          dir,
+          title:     "#{self.class}##{name}",
+          file:      Capybara::Simulated::MinitestTrace.source_file(self),
+          outcome:   fails.empty? ? 'passed' : 'failed',
+          exception: fails.first&.message
+        )
+      rescue StandardError => e
+        # Trace output must never turn a test red.
+        warn "capybara-simulated: trace persist failed: #{e.message}"
+      end
+    end
+  end
+  Minitest::Test.prepend(hook)
+end

data/lib/capybara/simulated/quickjs_runtime.rb

@@ -216,11 +216,28 @@ module Capybara
       # already the inter-test reset point.
       def reset_page = rebuild_ctx
 
-      # bridge.js patches `Intl.DateTimeFormat`; rusty_racer ships ICU
-      # built-in but QuickJS gates it behind a polyfill flag. Other JS
-      # surfaces bridge.js touches (URL / TextEncoder / atob/btoa /
-      # crypto) are already routed through Ruby-side host fns, so
-      # POLYFILL_INTL is the only one we strictly need.
+      # NOTE: intentionally NO `dispose` — Browser#dispose gates its
+      # `@runtime.dispose` call on `respond_to?(:dispose)`, so QuickJS skips it.
+      # QuickJS VMs aren't pinned by a process-wide registry the way V8 isolates
+      # are in V8Runtime's `@@live`; an aux window's Browser becomes unreferenced
+      # on close and Ruby GC's dfree frees its `@vm` (the same lifecycle
+      # `rebuild_ctx` already relies on). Adding a `@vm = nil` dispose would only
+      # introduce a NoMethodError window for any stray post-close call (eval/call
+      # don't all nil-guard `@vm`) with no leak benefit.
+
+      # bridge.js patches `Intl.DateTimeFormat`; rusty_racer ships ICU built-in but
+      # QuickJS gates it behind a polyfill flag (other surfaces bridge.js touches —
+      # URL / TextEncoder / atob/btoa / crypto — already route through Ruby host fns,
+      # so POLYFILL_INTL is the only one we strictly need).
+      #
+      # PERF (rule 3): quickjs is pinned to `~> 0.18.0` in the Gemfile. quickjs 0.19
+      # both split the Intl polyfills into a separate quickjs-polyfill-intl gem (which
+      # eval's them per VM at ~226 ms — vs this single bundled flag's ~140 ms) AND
+      # regressed interpreter execution ~2.8× (measured: the QuickJS spec suite ran
+      # 5.6 min on 0.18 vs 15.5 min on 0.19 with an equivalent Intl set). The 0.19
+      # migration is recorded in the cross-window / quickjs-CI memory; re-migrate to
+      # 0.19 + quickjs-polyfill-intl once that upstream perf regression is fixed.
+      INTL_FEATURES = [Quickjs::POLYFILL_INTL].freeze
       #
       # `max_stack_size: 0` — `JS_SetMaxStackSize` measures C stack
       # delta from runtime construction; Ruby callers reach QuickJS
@@ -236,7 +253,7 @@ module Capybara
       # handler returns `elapsed >= limit_ms`, so 0 fires on the first
       # check), so practical no-limit.
       VM_OPTIONS = {
-        features:       [Quickjs::POLYFILL_INTL].freeze,
+        features:       INTL_FEATURES,
         max_stack_size: 0,
         # quickjs.rb's 128 MB default trips "out of memory in regexp
         # execution" on class-attribute-heavy polls and the heaviest
@@ -344,6 +361,9 @@ module Capybara
         # flip doesn't race main's `polling?` gate. See v8_runtime's
         # build_worker for the long-form rationale.
         vm.define_function('__setTimersActive') {|_flag| nil }
+        # importScripts runs a classic script at top-level scope so its top-level
+        # const/let/class share the realm's global lexical env (see v8_runtime).
+        vm.define_function('__csim_workerImportEval') {|src| vm.eval_code(src.to_s); nil }
         vm.eval_code('__csim_installWorkerScope();')
         vm.drain_jobs!
         WorkerRuntime.new(

data/lib/capybara/simulated/rspec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'rspec/core'
+require_relative 'trace_persistence'
+
+# RSpec integration for trace file output. Require it from your
+# `spec_helper` / `rails_helper`:
+#
+#   require 'capybara/simulated/rspec'
+#
+# With `CSIM_TRACE_DIR=/path/to/dir` set, each example that recorded a
+# trace is persisted to `<dir>/<example slug>.json` after it runs. Inert
+# when the env var is unset. Whether a trace is recorded at all is
+# governed separately by `CSIM_TRACE` (off / on-failure / full) — see
+# Browser. Render a saved trace into an HTML viewer with
+# `capybara-simulated trace <file>.json`.
+if (dir = ENV['CSIM_TRACE_DIR']) && !dir.empty?
+  FileUtils.mkdir_p(dir)
+  RSpec.configure do |config|
+    # `prepend_after` so we capture the trace before a host's own
+    # teardown (e.g. Capybara session reset) runs.
+    config.prepend_after(:each) do |example|
+      Capybara::Simulated::TracePersistence.persist_all(
+        dir,
+        title:     example.full_description,
+        file:      example.location,
+        outcome:   example.exception ? 'failed' : 'passed',
+        exception: example.exception&.message
+      )
+    end
+  end
+end

data/lib/capybara/simulated/runtime_shared.rb

@@ -45,6 +45,23 @@ module Capybara
         '__csimExternalAsset'        => ->(b, *a) { b.external_asset_source(a[0]) },
         '__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
+        # realm id). Deferred + applied by re-navigating the owning iframe, so a
+        # frame's `location.href = …` navigates the frame, not the top page.
+        '__csimFrameNavigate'        => ->(b, *a) { b.frame_navigate_self(a[0], a[1].to_i); nil },
+        # A same-origin window realm (window.open in this isolate) navigating itself
+        # (a[0] = url, a[1] = the window's realm id). Deferred + applied by reloading
+        # that realm's document in place — see Browser#window_realm_navigate_self.
+        '__csimWindowRealmNavigate'  => ->(b, *a) { b.window_realm_navigate_self(a[0], a[1].to_i); nil },
+        # A nested browsing context reloading its OWN location (a[0] = the frame's
+        # realm id). Deferred + applied by re-navigating the owning iframe to its
+        # current document — see Browser#frame_reload_self.
+        '__csimFrameReload'          => ->(b, *a) { b.frame_reload_self(a[0].to_i); nil },
+        # A <form> submitted from inside a nested browsing context (a[0] = the
+        # initiating frame's realm id). Deferred + applied against that realm,
+        # like __csimFrameNavigate — see Browser#frame_submit_self.
+        '__csimFrameSubmit'          => ->(b, *a) { b.frame_submit_self(a[0].to_i); nil },
+        '__csimFrameHistoryGo'       => ->(b, *a) { b.frame_history_go(a[0].to_i, a[1].to_i); nil },
         '__setTimersActive'          => ->(b, *a) { b.timers_active = !!a[0]; nil },
         '__setCurrentUrl'            => ->(b, *a) { b.history_state(a[0], a[1]); nil },
         '__pushHistoryEntry'         => ->(b, *a) { b.history_push(a[0], a[1]); nil },
@@ -71,27 +88,61 @@ module Capybara
         '__csim_wsClose'             => ->(b, *a) { b.ws_close(a[0], a[1], a[2]); nil },
         '__csim_rackFetchAsync'      => ->(b, *a) { b.rack_fetch_async(a[0], a[1], a[2], a[3]) },
         '__csim_rackFetchAsyncAbort' => ->(b, *a) { b.rack_fetch_async_abort(a[0]); nil },
-        # Cross-window references (window.open / opener / postMessage). Each
-        # window is a separate VM, so these forward to the Driver to route to
-        # the target window's Browser.
-        '__csimWindowOpen'           => ->(b, *a) { b.open_child_window(a[0], a[1]) },
+        # Cross-window references (window.open / opener / postMessage). A separate-VM
+        # aux window forwards to the Driver; a same-origin window realm lives in this
+        # isolate. a[2] is the opener's realm id (for wiring window.opener).
+        '__csimWindowOpen'           => ->(b, *a) { b.open_child_window(a[0], a[1], a[2]) },
+        # A `target=_blank`/named link/area activation from a frame or window realm:
+        # open a new auxiliary window (the realm's VM isn't rebuilt — a fresh window
+        # 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 },
+        '__csimBroadcast'            => ->(b, *a) { b.broadcast_to_windows(a[0], a[1], a[2].to_i); nil },
+        '__csimWindowGet'            => ->(b, *a) { b.window_get(a[0], a[1]) },
+        '__csimWindowDocGet'         => ->(b, *a) { b.window_doc_get(a[0], a[1]) },
+        # Cross-window remote-ref RPC: route an opener's node/object proxy op to
+        # the target window's VM (a[0]=window handle, a[1]=ref id, a[2]=prop/method).
+        '__csimWindowRefGet'         => ->(b, *a) { b.window_ref_get(a[0], a[1], a[2]) },
+        '__csimWindowRefSet'         => ->(b, *a) { b.window_ref_set(a[0], a[1], a[2], a[3]); nil },
+        '__csimWindowRefCall'        => ->(b, *a) { b.window_ref_call(a[0], a[1], a[2], a[3]) },
         '__csimWindowLocation'       => ->(b, *a) { b.window_location_of(a[0]) },
         '__csimWindowSetLocation'    => ->(b, *a) { b.set_window_location(a[0], a[1]); nil },
+        '__csimWindowHistoryGo'      => ->(b, *a) { b.window_history_go(a[0], a[1]) },
         '__csimWindowClosed'         => ->(b, *a) { b.window_closed?(a[0]) },
         '__csimWindowClose'          => ->(b, *a) { b.close_child_window(a[0]); nil },
         '__csimWindowOpener'         => ->(b, *_) { b.opener_handle },
-        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0]) },
+        # Fire an aux window's OWN `load` event (in its VM) — deferred by the
+        # opener so a child `window.onload` runs after the opener's current task.
+        '__csimFireAuxWindowLoad'    => ->(b, *a) { b.fire_aux_window_load(a[0]); nil },
+        '__csim_workerSpawn'         => ->(b, *a) { b.worker_spawn(a[0], shared: !!a[1]) },
+        # 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) },
         '__csim_workerPostToWorker'  => ->(b, *a) { b.worker_post_to_worker(a[0], a[1]); nil },
         '__csim_workerTerminate'     => ->(b, *a) { b.worker_terminate(a[0]); nil },
         '__csim_decodeImage'         => ->(b, *a) { b.decode_image(a[0], a[1], a[2]) },
-        '__csim_blobRegister'        => ->(b, *a) { b.blob_register(a[0], a[1]); nil },
+        '__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).
+        '__csim_domainToASCII'       => ->(b, *a) { b.domain_to_ascii(a[0]) },
+        '__csim_domainToUnicode'     => ->(b, *a) { b.domain_to_unicode(a[0]) },
         '__csim_blobResolve'         => ->(b, *a) { b.blob_resolve(a[0]) },
         '__csim_blobUnregister'      => ->(b, *a) { b.blob_unregister(a[0]); nil },
+        # Any non-timer async channel (worker / SSE / hijacked fetch / window
+        # message / websocket) still in flight — the WPT runner's drain consults
+        # 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_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 },
+        # Universal-server context (WPT runner)? Gates cross-origin eager frame
+        # building: only there is a cross-origin iframe's content served locally,
+        # so an ordinary app leaves cross-origin frames lazy (= baseline) and never
+        # 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_encodeImage'         => ->(b, *a) { b.encode_image(a[0], a[1], a[2], a[3], a[4]) },
         # WebAuthn create / get raise `WebauthnState::Error` carrying

data/lib/capybara/simulated/trace.rb

@@ -29,6 +29,24 @@ module Capybara
         keyword_init: true
       )
 
+      VIEWER_TEMPLATE_PATH = File.expand_path('trace_viewer.html', __dir__)
+      VIEWER_DATA_TOKEN    = '__CSIM_TRACE_DATA__'
+
+      # 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).
+      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('</', '<\/') }
+      end
+
       attr_reader :steps, :metadata
 
       def initialize(metadata: {})
@@ -49,9 +67,24 @@ module Capybara
         @console_buf << {severity: severity.to_s, message: message.to_s}
       end
 
-      def log_network(method, url, status)
+      def log_network(method, url, status,
+                      content_type: nil, size: nil, duration_ms: nil, redirected: nil,
+                      request_headers: nil, request_body: nil,
+                      response_headers: nil, response_body: nil)
         return unless @open_step
-        @network_buf << {method: method.to_s, url: url.to_s, status: status}
+        @network_buf << {
+          method:           method.to_s,
+          url:              url.to_s,
+          status:           status,
+          content_type:     content_type,
+          size:             size,
+          duration_ms:      duration_ms,
+          redirected:       redirected,
+          request_headers:  request_headers,
+          request_body:     request_body,
+          response_headers: response_headers,
+          response_body:    response_body
+        }.compact  # drop fields the caller couldn't determine, keeping entries lean
       end
 
       def begin_step(kind, description:, url_before: nil)

data/lib/capybara/simulated/trace_persistence.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'capybara/simulated'
+
+module Capybara
+  module Simulated
+    # Framework-agnostic trace file-output, shared by the RSpec
+    # (`capybara/simulated/rspec`) and Minitest
+    # (`capybara/simulated/minitest`) integrations. Each of those reads
+    # `CSIM_TRACE_DIR` and feeds the per-example outcome here; this just
+    # stamps metadata and writes `<slug>.json`.
+    module TracePersistence
+      module_function
+
+      # Filename-safe slug: keep word-ish chars, collapse the rest to one
+      # `_`, cap length so a long description can't blow the path limit.
+      def slug(name)
+        name.to_s.gsub(/[^A-Za-z0-9._-]+/, '_')[0, 200]
+      end
+
+      # Stamp the outcome onto one driver's trace and write it. No-op
+      # unless the driver actually recorded something.
+      def persist(driver, dir, title:, file:, outcome:, exception:)
+        return unless driver.respond_to?(:tracing?) && driver.tracing?
+        driver.current_trace.metadata.merge!(
+          title:     title,
+          file:      file,
+          outcome:   outcome,
+          exception: exception
+        )
+        driver.stop_tracing(path: File.join(dir, "#{slug(title)}.json"))
+      end
+
+      # Persist every tracing simulated driver on the current thread
+      # (one example normally has exactly one). Trace output must never
+      # change a test's result, so a write failure is warned and
+      # swallowed rather than propagated out of the after-hook.
+      def persist_all(dir, **fields)
+        Capybara::Simulated::Driver.each_live_on_thread(Thread.current) do |driver|
+          persist(driver, dir, **fields)
+        rescue StandardError => e
+          warn "capybara-simulated: failed to write trace: #{e.message}"
+        end
+      end
+    end
+  end
+end