capybara-simulated 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b2b947ec8b6945ec441d61c70a2bf0155283696c7d8188a135c990850149f68
-  data.tar.gz: c7530db87c7b019f25db0370213c6965a4c3f44172284ef469f84e8617319291
+  metadata.gz: 67e9168ef15e413c1d85b1805ea4d68f36cae09578af5fc539bd1613d52ac04d
+  data.tar.gz: 6214303ef25079d567bc91db43460eda49a54a292ed08021b98a81ce48af0c31
 SHA512:
-  metadata.gz: 1c3e5d6358892be026316a31531ed4ced5e66f52ac0dafcda51236977f8f94f40b5465e9653cce4ce2ad84cee0ef4d29b8fbe2d850cd94efb3f1a3ab47db3eb6
-  data.tar.gz: '099d9b40e65a21667a543721f26b1df60176a2651da945f175016d5d85bbd81b0296099a17bf23b2a415101387489573d6b487aecdf8255ee0a923935d0f9b10'
+  metadata.gz: 8112cd3056184946f65739dfb30e76e55bee2a79f1058e3128bc8ae15f0b5790f195d0c289759518e667b69902962e70922af21f48dea6610744ab1093a10ca4
+  data.tar.gz: 53ccb66cb2bd4723d1e999ebd03b0a56bdbc83978834f82b66c128aa2c7e3ba1c4f5464c5965442104de94de2fbabe79e185a74f6e1aaa3cd2c2c2c2bfe68a26

data/README.md

@@ -200,11 +200,18 @@ end
 
 ### File output
 
-Set `CSIM_TRACE_DIR=/path/to/dir` to enable file output. The bundled
-RSpec hook ([`csim_rspec.rb`](https://github.com/ursm/capybara-simulated-vs-world/blob/main/support/csim_rspec.rb))
-writes `<example slug>.json` into that directory after each test;
-mirror it in `application_system_test_case.rb`'s teardown for
-Minitest.
+Require the test-framework integration in your `spec_helper` /
+`rails_helper` (RSpec) or `test_helper` /
+`application_system_test_case.rb` (Minitest):
+
+```ruby
+require 'capybara/simulated/rspec'     # RSpec
+require 'capybara/simulated/minitest'  # Minitest / Rails system tests
+```
+
+With `CSIM_TRACE_DIR=/path/to/dir` set, each example that recorded a
+trace is written to `<dir>/<slug>.json` after it runs; both integrations
+are inert when the env var is unset.
 
 ```sh
 CSIM_TRACE_DIR=tmp/csim-traces bundle exec rspec spec/system
@@ -214,6 +221,31 @@ The metadata block on each trace includes `title`, `file`, `outcome`
 (`passed` / `failed`), and the exception message — enough to index a
 CI artifact directory by failure.
 
+### Viewing traces
+
+The recorded JSON stays plain data; to look at one, render it into a
+self-contained HTML viewer with the bundled CLI:
+
+```sh
+capybara-simulated trace tmp/csim-traces/checkout_flow.json
+# wrote /tmp/checkout_flow.html   (then opens it in your browser)
+```
+
+By default the HTML is written to a temp file and opened in your
+browser. The viewer works straight from `file://` — the trace JSON is
+embedded inline, so no server is needed — and shows a step-by-step UI: a
+timeline of actions, and per step the URL before/after, console output,
+network requests, the error, and a rendered preview of the post-action
+DOM snapshot. Its **Load JSON…** button / drag-and-drop swaps in any
+other trace file.
+
+`-o PATH` writes the HTML somewhere specific (`-o -` to stdout);
+`--no-open` skips launching the browser. Browser launching uses
+[launchy](https://rubygems.org/gems/launchy) when it's installed
+(`gem 'launchy'`, recommended for reliable cross-platform / WSL opening)
+and falls back to the platform opener (`xdg-open` / `open` / `start`)
+otherwise.
+
 ### Programmatic
 
 For finer control, call `driver.start_tracing(...)` /

data/exe/capybara-simulated

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# capybara-simulated CLI. Currently one subcommand:
+#
+#   capybara-simulated trace TRACE.json [-o OUT.html] [--no-open]
+#
+# Renders a trace JSON (produced by CSIM_TRACE_DIR / driver.stop_tracing)
+# into a self-contained HTML viewer and opens it in your browser. The
+# viewer embeds the JSON inline so it opens straight from file:// — no
+# server, unlike a fetch/import-based loader (CORS blocks those for
+# file:// origins). The persisted trace stays plain JSON; this turns one
+# into a UI on demand.
+
+require 'optparse'
+require 'tmpdir'
+
+# Prefer the library co-located with this executable. In an installed
+# gem that's the gem's own lib (correct version); in a checkout it's the
+# working tree — so `ruby exe/capybara-simulated` doesn't accidentally
+# load an older *installed* capybara-simulated that predates this CLI.
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+require 'capybara/simulated/trace'
+
+PROG = 'capybara-simulated'
+
+# `file://` URL for a local path, percent-encoding each segment so a
+# path with spaces / special chars stays a valid URI for launchy.
+def file_url(path)
+  require 'cgi'
+  'file://' + path.split('/').map {|seg| CGI.escapeURIComponent(seg) }.join('/')
+end
+
+# Hand the raw path (not a URL) to the platform opener; `system`'s array
+# form needs no shell-quoting, so spaces are fine.
+def open_with_platform(path)
+  cmd =
+    case RbConfig::CONFIG['host_os']
+    when /darwin/      then ['open', path]
+    when /mswin|mingw/ then ['cmd', '/c', 'start', '', path]
+    else                    ['xdg-open', path]  # Linux / *BSD
+    end
+  system(*cmd)
+rescue StandardError
+  false
+end
+
+# Open a local file in the default browser. Prefer launchy (handles
+# macOS / Linux / Windows / WSL) when installed; on either a missing gem
+# OR a launchy runtime failure (headless box, no opener), fall back to
+# the platform opener.
+def open_in_browser(path)
+  begin
+    require 'launchy'
+    Launchy.open(file_url(path))
+    return true
+  rescue LoadError
+    # launchy not installed
+  rescue StandardError
+    # launchy present but failed — try the platform opener below
+  end
+  open_with_platform(path)
+end
+
+def cmd_trace(argv)
+  out  = nil
+  open = nil  # nil → default (open), unless writing to stdout
+  parser = OptionParser.new do |o|
+    o.banner = "Usage: #{PROG} trace [options] TRACE.json\n\n" \
+               "Render TRACE.json into a self-contained HTML viewer and open it\n" \
+               "in your browser. By default the HTML goes to a temp file."
+    o.on('-o', '--output PATH', "write HTML to PATH instead of a temp file ('-' = stdout)") {|v| out = v }
+    o.on('--[no-]open', 'open the HTML in your browser (default: yes)') {|v| open = v }
+    o.on('-h', '--help') do
+      puts o
+      exit
+    end
+  end
+  begin
+    parser.parse!(argv)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    warn parser.help
+    exit 1
+  end
+
+  input = argv.shift
+  unless input
+    warn parser.help
+    exit 1
+  end
+  unless File.file?(input)
+    warn "#{PROG}: no such file: #{input}"
+    exit 1
+  end
+
+  json = File.read(input)
+  begin
+    require 'json'
+    JSON.parse(json)  # fail fast on a non-JSON / corrupt trace
+  rescue JSON::ParserError => e
+    warn "#{PROG}: #{input} is not valid JSON: #{e.message}"
+    exit 1
+  end
+
+  html = Capybara::Simulated::Trace.render_viewer(json)
+
+  if out == '-'
+    $stdout.write(html)
+    return
+  end
+  # Default output: a temp file named after the trace (re-runs overwrite).
+  out ||= File.join(Dir.tmpdir, File.basename(input).sub(/\.json\z/, '') + '.html')
+  File.write(out, html)
+  warn "wrote #{out}"
+  open_in_browser(File.expand_path(out)) unless open == false
+end
+
+def main(argv)
+  case argv.first
+  when 'trace'
+    cmd_trace(argv.drop(1))
+  when '-v', '--version'
+    require 'capybara/simulated/version'
+    puts Capybara::Simulated::VERSION
+  when nil, '-h', '--help'
+    puts <<~USAGE
+      Usage: #{PROG} <command> [options]
+
+      Commands:
+        trace TRACE.json   render a trace JSON into a self-contained HTML viewer
+
+      Run `#{PROG} trace --help` for command options.
+    USAGE
+  else
+    warn "#{PROG}: unknown command: #{argv.first}"
+    warn "Run `#{PROG} --help`."
+    exit 1
+  end
+end
+
+main(ARGV)