backspin 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6373427307003e8469435ce1c461e6f9bf6ff307c952bce87f07c393470f5fdc
-  data.tar.gz: 3e8487ba8345a4fef0b8419487de0e84b756c302ada8b313e2bf0e5cd6c1ec1a
+  metadata.gz: 3810a17b9b213b010cadd7419559fda50aed8dee3faad5865e824e765921339d
+  data.tar.gz: 400594d38ca7937da9095c78eb6578d5d384077a1cbbf78db97f06e133c6dcd0
 SHA512:
-  metadata.gz: d7f1915e4632d8fb4b08ae6a8ff0e6e9846ed3f1cd783c7dcc283ca2d3816afb518173a50cd519b5859eb6d991be7636a81a48e34fb63f0176d14c9a2bdd500a
-  data.tar.gz: 7307a43c18730ec430f39dbadecb301eaad177ecc3795906f9682ec3e4781e9d5d9ec2b8c913220f8c5985393ae90e73974e5f2855a40ea17d33f87914b5a527
+  metadata.gz: c2614110086b787c10b31504ae0eed80b32adc7a72d61709f6fba6245e093b35f92816227faebf781b3257e25b766c45676c47e74422176ae07fbc3eafaabce2
+  data.tar.gz: 6bb11f527a1aebc8ed495ccde7ca4deddf87b33f33f160cf76da13e02bc994e9b397cbaa59df2f30656cbd4a589ea70ebe24194743ac96a9b639fcda4cd9bf22

data/.gitignore

@@ -7,6 +7,7 @@
 /tmp/
 /.claude
 /.cursor
+/checksums/
 
 /backspin*.gem
 # rspec failure tracking

data/.ruby-version

@@ -1 +1 @@
-4.0.0
+4

data/.standard.yml

@@ -2,6 +2,11 @@
 parallel: true
 format: progress
 
+# Match the gemspec's required_ruby_version. Without this, Standard infers the
+# target from .ruby-version (4) and flags requires that are only redundant on
+# Ruby >= 3.5 - removing them would break the 3.x versions we still support.
+ruby_version: 3.2
+
 ignore:
   - 'tmp/**/*'
   - 'vendor/**/*'

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## 0.12.0
+## 0.13.0
+* Added `Backspin.compare(reference:, actual:)` for differential testing - runs both commands live and compares their filtered output, with no record file. Only stdout, stderr, and exit status are compared, so the two commands may differ in argv and env without normalization.
+* Added `Backspin::ReferenceCommandError`, raised when a compare's reference command produces no output at all (usually a sign it failed to start), rather than comparing empty to empty.
+* Raised the minimum supported Ruby to 3.2 (3.1 reached end-of-life in March 2025).
+* Fixed snapshot timestamps to be recorded as UTC rather than local time, so re-recording in a different timezone no longer produces noisy diffs.
+* Fixed a missing `require "time"`, which could raise `NoMethodError` on `Time#iso8601` in consumers that never load the time stdlib themselves.
+
+## 0.12.0 - 2026-02-11
 * Added `BACKSPIN_MODE` environment variable to globally override recording mode (`auto`, `record`, `verify`).
 * Explicit `mode:` kwarg still takes highest precedence, followed by the env var, then auto-detection.
 * Added configurable logger to `Backspin::Configuration` (defaults to WARN level, logfmt-lite format, and can be disabled with `config.logger = nil`).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.12.0)
+    backspin (0.13.0)
       logger
 
 GEM
@@ -9,64 +9,64 @@ GEM
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
-    json (2.16.0)
-    language_server-protocol (3.17.0.5)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    prism (1.6.0)
+    prism (1.9.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
-    regexp_parser (2.11.3)
-    rspec (3.13.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.4)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.81.7)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.48.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.52.0)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.81.7)
+      rubocop (~> 1.88.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
-    timecop (0.9.10)
+      rubocop-performance (~> 1.26.0)
+    timecop (0.9.11)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
@@ -83,4 +83,4 @@ DEPENDENCIES
   timecop (~> 0.9)
 
 BUNDLED WITH
-  4.0.5
+  4.0.16

data/README.md

@@ -75,6 +75,25 @@ end
 
 Block capture records a single combined stdout/stderr snapshot. Exit status is a placeholder (`0`) in this mode.
 
+### Differential Testing (Compare)
+
+Use `Backspin.compare` when the question is "does my tool produce the same output as this reference tool?" Both commands run live and their output is compared directly - nothing is recorded to disk:
+
+```ruby
+result = Backspin.compare(
+  reference: ["bundle", "exec", "rspec", "spec/failing_spec.rb"],
+  actual: ["my-runner", "spec/failing_spec.rb"]
+)
+
+result.expected.stdout  # reference output
+result.actual.stdout    # output from the command under test
+result.verified?        # true when they match
+```
+
+Only stdout, stderr, and exit status are compared, so the two commands can differ in argv and environment without any normalization. `filter` and `matcher` work exactly as they do for `Backspin.run`, and a mismatch raises `Backspin::VerificationError` unless `raise_on_verification_failure` is disabled.
+
+If the reference command produces no output at all - usually a sign it failed to start rather than that its output is genuinely empty - `compare` raises `Backspin::ReferenceCommandError` instead of comparing empty to empty.
+
 ### Recording Modes
 
 Backspin supports different modes for controlling how commands are recorded and verified:
@@ -211,7 +230,7 @@ Backspin.run(["echo", "id=123"], name: "record_only", filter: normalize_filter,
 
 ### Working with the Result Object
 
-The API returns a `Backspin::BackspinResult` object with helpful methods:
+The API returns a `Backspin::BackspinResult` object with details on run.
 
 ```ruby
 result = Backspin.run(["sh", "-c", "echo out; echo err >&2; exit 42"], name: "my_test")

data/backspin.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Backspin is a Ruby library for characterization testing of command-line interfaces. Inspired by VCR's cassette-based approach, it records and replays CLI interactions to make testing faster and more deterministic."
   spec.homepage = "https://github.com/rsanheim/backspin"
   spec.license = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage

data/docs/compare-api-plan.md

@@ -0,0 +1,193 @@
+# Compare API Plan — differential testing between two commands
+
+Date: 2026-07-20 (revised 2026-07-25)
+
+## Motivation
+
+The most common way Backspin is used in the `plur` test suite is *differential
+testing*: "does tool B produce the same output as reference tool A?" plur is a
+Go reimplementation of a parallel RSpec runner, and its golden specs assert that
+plur's output matches `rspec`'s own output byte-for-byte.
+
+Backspin has no first-class API for this, so today it is expressed as an
+implicit two-call dance with the same record name:
+
+```ruby
+# record rspec baseline
+chdir(fixture) { Backspin.run(rspec_cmd, name: "x", filter: normalize) }
+# verify plur against it
+result = chdir(fixture) { Backspin.run(plur_cmd, name: "x", filter: normalize) }
+expect(result.verified?).to be(true)
+```
+
+That pattern works but has sharp edges, each of which has bitten a real plur
+spec:
+
+1. **Ordering is load-bearing and invisible.** The first `run` records only
+   because the record file happens not to exist yet; if it does exist, *both*
+   calls verify against the stored baseline — a different meaning than the code
+   reads like.
+2. **A stale baseline requires a manual `rm`.** Change the fixture and the
+   committed `.yml` no longer matches the reference command, so the first call
+   fails on `reference-vs-stale-baseline`. Nothing signals that deleting the
+   snapshot is the fix.
+3. **The command line must be neutralized by hand.** The two commands *differ*
+   on purpose (`rspec …` vs `plur …`), so specs stuff `"args" => ["[PLACEHOLDER]"]`
+   into the filter to stop the recorded command from mismatching.
+4. **The filter is passed twice** and must be identical on both calls.
+5. **The dance can span two examples.** plur's minitest golden test records in
+   one `it` and verifies in a *different* `it` — order-dependent across
+   examples, so it only works because RSpec runs in defined order.
+
+The gap is small and specific: `Backspin.run` assumes the *record command* and
+the *verify command* are the same. Differential testing needs them to differ.
+
+## The idea
+
+Add `Backspin.compare`, which runs a **reference** command and an **actual**
+command and compares their (filtered) output. It is pure orchestration over
+primitives Backspin already has — no new filtering, snapshot, diff, matcher, or
+result code, and no record file.
+
+```ruby
+Backspin.compare(
+  reference:,   # String/Array command that defines correct output
+  actual:,      # String/Array command under test
+  env: nil,
+  matcher: nil, # reused as-is
+  filter: nil   # reused as-is
+)
+# => BackspinResult
+```
+
+`reference` maps to `result.expected`, `actual` maps to `result.actual` — which
+is exactly the existing `BackspinResult` contract (expected = baseline, actual =
+what just ran). See `docs/backspin-result-api-sketch.md`.
+
+## Scope: live-vs-live only
+
+An earlier draft also proposed a snapshot-backed mode (`name:` + `mode:`), where
+`compare` would record the reference to a `.yml` and later verify `actual`
+against it. That is deliberately **not** in scope:
+
+- In `mode: :verify` the `reference:` argument would be silently ignored. You
+  could change the reference command and nothing would happen until someone
+  deleted the record — sharp edge #2 wearing a new hat, plus a dead keyword arg.
+- It roughly doubles the API surface (`name`, `mode`, `BACKSPIN_MODE`,
+  `filter_on`) for a caller that does not exist yet. plur always has `rspec`
+  available, in dev and in CI.
+
+If a real caller shows up with a reference command that is expensive or absent
+in CI, add it then. `Backspin.run` already covers "freeze one command's output."
+
+## Reuse map — what each need already maps to
+
+| Need | Existing primitive | Location |
+|---|---|---|
+| Run a command → stdout/stderr/status | `execute_command(command, env)` | `lib/backspin.rb` |
+| Build a snapshot value object | `Snapshot.new(command_type: Open3::Capture3, …)` | `lib/backspin/snapshot.rb` |
+| Apply `filter` to both sides | `CommandDiff#build_comparison_snapshot` | `lib/backspin/command_diff.rb` |
+| Compare (default = stdout/stderr/status; custom matcher/hash) | `CommandDiff` + `Matcher` | `lib/backspin/command_diff.rb`, `lib/backspin/matcher.rb` |
+| `verified?` / `diff` / `summary` | `CommandDiff` | `lib/backspin/command_diff.rb` |
+| Result object (`expected`, `actual`, `verified?`, `diff`, `error_message`) | `BackspinResult` | `lib/backspin/backspin_result.rb` |
+| Raise on mismatch (config-gated) | `raise_on_verification_failure!(result)` | `lib/backspin.rb` |
+
+The heart of it: `CommandDiff.new(expected:, actual:, matcher:, filter:)`
+already takes two snapshots, applies the filter to both, runs the matcher, and
+produces `verified?`/`diff`. `compare` just has to hand it two snapshots.
+
+## Semantics that fall out for free
+
+- **args/env are not compared.** The default matcher only looks at stdout,
+  stderr, status (`Matcher#evaluate_default`), and `CommandDiff#diff` only diffs
+  those three. So two intentionally-different commands compare cleanly with no
+  `args` placeholder — deleting plur boilerplate.
+- **command_type matches.** Both sides are `Open3::Capture3`, so
+  `CommandDiff#command_types_match?` is true.
+- **Strict-by-default is preserved.** `raise_on_verification_failure!` already
+  raises `VerificationError` (with `result.diff`) unless
+  `raise_on_verification_failure = false`. `compare` reuses it verbatim.
+
+## Guard: a broken reference must not pass
+
+Live-vs-live has one failure mode the two-call dance did not: if the reference
+command fails to *run at all* — wrong directory, `bundle` not on `PATH`, a load
+error — it produces empty stdout and a non-zero status. If `actual` fails the
+same way, `verified?` is true and the spec goes green while testing nothing.
+
+`compare` raises `Backspin::ReferenceCommandError` when the reference command
+produces no output on either stream. Exit status can't be the signal: plur's
+golden specs deliberately run failing suites that exit 1.
+
+## The new code
+
+1. `Backspin.compare` public method (validation + orchestration + the guard).
+2. A private `capture_command_snapshot(command, env)` wrapping
+   `execute_command` + `Snapshot.new`. This is **extracted from existing
+   duplication** — `perform_command_run` builds that same snapshot twice, so
+   pulling it out DRYs `run` as well.
+3. One fix in `raise_on_verification_failure!`: only emit the `Record:` line
+   when there is a record path, so `compare` failures don't render a dangling
+   `Record: ` label.
+
+No changes to `CommandDiff`, `Matcher`, `Snapshot`, `Record`, or
+`BackspinResult`. `compare` lives beside `run`/`capture` in `lib/backspin.rb`.
+
+### Notes
+
+- There is no `filter_on:` keyword. `filter_on: :record` would mean "filter only
+  when persisting", and `compare` never persists — passing it would silently
+  disable filtering. Omitting the keyword makes that a plain `ArgumentError`.
+- `record_path` is `nil` on the result, and `mode` is `:verify` (nothing was
+  recorded, so `recorded?` is false).
+
+## Before / after (plur golden spec)
+
+Today (`spec/integration/spec/aggregate_failure_golden_spec.rb` in plur):
+
+```ruby
+chdir(fixture) { Backspin.run(rspec_cmd, name: "x", filter: normalize) }
+result = chdir(fixture) { Backspin.run(plur_cmd, name: "x", filter: normalize) }
+expect(result.verified?).to be(true)
+```
+
+With `compare`:
+
+```ruby
+result = chdir(fixture) do
+  Backspin.compare(reference: rspec_cmd, actual: plur_cmd, filter: normalize)
+end
+expect(result.verified?).to be(true)
+```
+
+A `dir:` option to drop the `chdir` wrapper is a possible follow-up; not needed
+here, since one wrapper now covers what took two.
+
+## Success criteria
+
+1. `Backspin.compare(reference:, actual:)` runs both and returns a
+   `BackspinResult` with `expected` = reference snapshot, `actual` = actual
+   snapshot, and boolean `verified?`.
+2. On mismatch, `result.diff` / `result.error_message` are populated by the
+   existing `CommandDiff`, and `VerificationError` is raised unless
+   `raise_on_verification_failure = false`. The failure message has no empty
+   `Record:` line.
+3. `filter` / `matcher` behave exactly as in `run` (same objects, same code
+   paths).
+4. Two commands with different argv compare on output only — no `args`
+   normalization needed.
+5. No record file is written or read.
+6. A reference command that produces no output raises
+   `ReferenceCommandError` rather than comparing empty-to-empty.
+7. No new filtering / snapshot / diff / matcher / result implementation — only a
+   `compare` entry point, the extracted `capture_command_snapshot` helper, and
+   the nil-`record_path` message fix.
+
+## Downstream: what this buys plur
+
+Six call-site pairs across four files collapse to a single call each:
+`single_failure_golden_spec.rb` (three examples), `aggregate_failure_golden_spec.rb`,
+`pending_output_spec.rb`, and `minitest_integration_spec.rb` (the cross-example
+one). Five fixture YAMLs get deleted, along with every `"args" => [...]`
+placeholder line. plur's other five Backspin specs are ordinary single-command
+snapshot tests and are untouched.

data/fixtures/projects/dummy_cli_gem/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../../..
   specs:
-    backspin (0.11.0)
+    backspin (0.13.0)
       logger
 
 PATH
@@ -40,7 +40,7 @@ DEPENDENCIES
   rspec (~> 3)
 
 CHECKSUMS
-  backspin (0.11.0)
+  backspin (0.13.0)
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   dummy_cli_gem (0.1.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203

data/fixtures/projects/dummy_cli_gem/dummy_cli_gem.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.description = "Fixture gem that shells out to unix utilities and is tested via Backspin snapshots."
   spec.homepage = "https://example.com/dummy_cli_gem"
   spec.license = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.files = Dir.chdir(__dir__) do
     Dir["lib/**/*.rb", "exe/*", "spec/**/*", "script/**/*", "README.md", "LICENSE.txt"]

data/lib/backspin/record.rb

@@ -44,7 +44,7 @@ module Backspin
 
     def set_snapshot(snapshot)
       @snapshot = snapshot
-      snapshot_recorded_at = snapshot.recorded_at || Time.now.iso8601
+      snapshot_recorded_at = snapshot.recorded_at || Time.now.utc.iso8601
       @first_recorded_at ||= snapshot_recorded_at
       @recorded_at = snapshot_recorded_at
       self

data/lib/backspin/recorder.rb

@@ -26,7 +26,7 @@ module Backspin
         stdout: captured_stdout,
         stderr: captured_stderr,
         status: 0,
-        recorded_at: Time.now.iso8601
+        recorded_at: Time.now.utc.iso8601
       )
 
       record.set_snapshot(actual_snapshot)

data/lib/backspin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Backspin
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/backspin.rb

@@ -4,6 +4,7 @@ require "yaml"
 require "fileutils"
 require "open3"
 require "pathname"
+require "time"
 require "backspin/version"
 require "backspin/configuration"
 require "backspin/snapshot"
@@ -18,6 +19,10 @@ module Backspin
 
   class RecordNotFoundError < StandardError; end
 
+  # Raised when the reference command in a compare produced no output at all,
+  # which almost always means it failed to run rather than that it is correct.
+  class ReferenceCommandError < StandardError; end
+
   class VerificationError < StandardError
     attr_reader :result
 
@@ -115,6 +120,49 @@ module Backspin
       perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
     end
 
+    # Differential testing - runs a reference command and a command under test
+    # and compares their filtered output. Nothing is recorded to disk.
+    #
+    # Only stdout, stderr, and status are compared, so the two commands may
+    # differ in argv and env without any normalization.
+    #
+    # @param reference [String, Array] Command that defines the correct output
+    # @param actual [String, Array] Command under test
+    # @param env [Hash] Environment variables passed to both commands
+    # @param matcher [Proc, Hash] Custom matcher for verification
+    # @param filter [Proc] Custom filter applied to both sides before comparing
+    # @return [BackspinResult] expected = reference, actual = command under test
+    def compare(reference:, actual:, env: nil, matcher: nil, filter: nil)
+      normalized_env = normalize_env(env)
+
+      expected_snapshot, = capture_command_snapshot(reference, normalized_env)
+      if expected_snapshot.stdout.empty? && expected_snapshot.stderr.empty?
+        raise ReferenceCommandError,
+          "Reference command produced no output (exit status #{expected_snapshot.status}): #{reference.inspect}"
+      end
+
+      actual_snapshot, = capture_command_snapshot(actual, normalized_env)
+
+      command_diff = CommandDiff.new(
+        expected: expected_snapshot,
+        actual: actual_snapshot,
+        matcher: matcher,
+        filter: filter
+      )
+      result = BackspinResult.new(
+        mode: :verify,
+        record_path: nil,
+        actual: actual_snapshot,
+        expected: expected_snapshot,
+        verified: command_diff.verified?,
+        command_diff: command_diff
+      )
+
+      raise_on_verification_failure!(result)
+
+      result
+    end
+
     private
 
     def perform_capture(record_name, mode:, matcher:, filter:, filter_on:, &block)
@@ -147,27 +195,18 @@ module Backspin
 
       record = Record.load_or_create(record_path)
 
-      normalized_env = env.nil? ? nil : normalize_env(env)
+      normalized_env = normalize_env(env)
 
       result = case mode
       when :record
-        stdout, stderr, status = execute_command(command, normalized_env)
-        actual_snapshot = Snapshot.new(
-          command_type: Open3::Capture3,
-          args: command,
-          env: normalized_env,
-          stdout: stdout,
-          stderr: stderr,
-          status: status.exitstatus,
-          recorded_at: Time.now.iso8601
-        )
+        actual_snapshot, output = capture_command_snapshot(command, normalized_env)
         record.set_snapshot(actual_snapshot)
         record.save(filter: filter)
         BackspinResult.new(
           mode: :record,
           record_path: record.path,
           actual: actual_snapshot,
-          output: [stdout, stderr, status]
+          output: output
         )
       when :verify
         raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
@@ -178,15 +217,7 @@ module Backspin
           raise RecordFormatError, "Invalid record format: expected Open3::Capture3 for run"
         end
 
-        stdout, stderr, status = execute_command(command, normalized_env)
-        actual_snapshot = Snapshot.new(
-          command_type: Open3::Capture3,
-          args: command,
-          env: normalized_env,
-          stdout: stdout,
-          stderr: stderr,
-          status: status.exitstatus
-        )
+        actual_snapshot, output = capture_command_snapshot(command, normalized_env)
         command_diff = CommandDiff.new(
           expected: expected_snapshot,
           actual: actual_snapshot,
@@ -201,7 +232,7 @@ module Backspin
           expected: expected_snapshot,
           verified: command_diff.verified?,
           command_diff: command_diff,
-          output: [stdout, stderr, status]
+          output: output
         )
       else
         raise ArgumentError, "Unknown mode: #{mode}"
@@ -212,7 +243,22 @@ module Backspin
       result
     end
 
+    def capture_command_snapshot(command, env)
+      stdout, stderr, status = execute_command(command, env)
+      snapshot = Snapshot.new(
+        command_type: Open3::Capture3,
+        args: command,
+        env: env,
+        stdout: stdout,
+        stderr: stderr,
+        status: status.exitstatus,
+        recorded_at: Time.now.utc.iso8601
+      )
+      [snapshot, [stdout, stderr, status]]
+    end
+
     def normalize_env(env)
+      return nil if env.nil?
       raise ArgumentError, "env must be a Hash" unless env.is_a?(Hash)
 
       env.empty? ? nil : env
@@ -234,7 +280,7 @@ module Backspin
       return unless configuration.raise_on_verification_failure && result.verified? == false
 
       error_message = "Backspin verification failed!\n"
-      error_message += "Record: #{result.record_path}\n"
+      error_message += "Record: #{result.record_path}\n" if result.record_path
       details = result.error_message || result.diff
       error_message += "\n#{details}" if details
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -52,6 +52,7 @@ files:
 - bin/rspec
 - bin/setup
 - docs/backspin-result-api-sketch.md
+- docs/compare-api-plan.md
 - examples/match_on_example.rb
 - fixtures/backspin/.gitkeep
 - fixtures/projects/dummy_cli_gem/.rspec
@@ -85,7 +86,6 @@ files:
 - mise.toml
 - release.rake
 - script/lint
-- script/run_affected_tests
 homepage: https://github.com/rsanheim/backspin
 licenses:
 - MIT
@@ -100,14 +100,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Record and replay CLI interactions for testing
 test_files: []

data/script/run_affected_tests

@@ -1,179 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "json"
-require "pathname"
-require "open3"
-
-class AffectedTestRunner
-  EXIT_SUCCESS = 0
-  EXIT_FAILURE = 2
-
-  def initialize
-    @project_dir = ENV["CLAUDE_PROJECT_DIR"]
-    validate_environment!
-  end
-
-  def run
-    input_data = parse_input
-    file_path = extract_file_path(input_data)
-
-    return EXIT_SUCCESS unless ruby_file?(file_path)
-
-    validated_path = validate_and_normalize_path(file_path)
-    return EXIT_SUCCESS unless validated_path
-
-    test_file = determine_test_file(validated_path)
-    return EXIT_SUCCESS unless test_file
-
-    run_tests(test_file)
-  rescue => e
-    abort_to_claude("Unexpected error: #{e.message}")
-  end
-
-  private
-
-  def validate_environment!
-    unless @project_dir
-      abort_to_claude("CLAUDE_PROJECT_DIR environment variable not set")
-    end
-
-    unless Dir.exist?(@project_dir)
-      abort_to_claude("CLAUDE_PROJECT_DIR does not exist: #{@project_dir}")
-    end
-
-    @project_path = Pathname.new(@project_dir).realpath
-  rescue => e
-    abort_to_claude("Invalid CLAUDE_PROJECT_DIR: #{e.message}")
-  end
-
-  def parse_input
-    input = $stdin.read
-    JSON.parse(input)
-  rescue JSON::ParserError => e
-    abort_to_claude("Invalid JSON input: #{e.message}")
-  end
-
-  def extract_file_path(data)
-    file_path = data.dig("tool_input", "file_path")
-
-    unless file_path && !file_path.empty?
-      abort_to_claude("No file_path provided in input")
-    end
-
-    file_path
-  end
-
-  def ruby_file?(file_path)
-    file_path.end_with?(".rb")
-  end
-
-  def validate_and_normalize_path(file_path)
-    # Expand the path to get absolute path
-    expanded_path = File.expand_path(file_path, @project_dir)
-    normalized_path = Pathname.new(expanded_path).cleanpath
-
-    # Check if the path is within the project directory
-    unless normalized_path.to_s.start_with?(@project_path.to_s)
-      log_info("File path outside project directory: #{file_path}")
-      return nil
-    end
-
-    # Convert back to relative path from project root for consistency
-    normalized_path.relative_path_from(@project_path).to_s
-  rescue => e
-    log_info("Invalid file path: #{file_path} - #{e.message}")
-    nil
-  end
-
-  def determine_test_file(file_path)
-    log_info("Determining tests for: #{file_path}")
-
-    if spec_file?(file_path)
-      # If a spec file was modified, run just that spec
-      test_file = file_path
-      log_info("Running single spec: #{test_file}")
-    elsif lib_file?(file_path)
-      # If a lib file was modified, try to find corresponding spec
-      test_file = lib_to_spec_path(file_path)
-
-      if File.exist?(File.join(@project_dir, test_file))
-        log_info("Running corresponding spec: #{test_file}")
-      else
-        # No corresponding spec found, run all tests
-        log_info("No corresponding spec found, running all tests")
-        test_file = "spec"
-      end
-    else
-      # For other Ruby files, run all tests
-      log_info("Running all tests")
-      test_file = "spec"
-    end
-
-    # Validate test file/directory exists
-    full_test_path = File.join(@project_dir, test_file)
-    unless File.exist?(full_test_path)
-      abort_to_claude("Test file/directory does not exist: #{test_file}")
-    end
-
-    test_file
-  end
-
-  def spec_file?(file_path)
-    file_path.match?(%r{^.*spec/.*_spec\.rb$})
-  end
-
-  def lib_file?(file_path)
-    file_path.match?(%r{^.*lib/.*})
-  end
-
-  def lib_to_spec_path(lib_path)
-    # Convert lib/backspin/foo.rb to spec/backspin/foo_spec.rb
-    lib_path.sub(%r{^(.*/)?lib/}, '\1spec/')
-      .sub(/\.rb$/, "_spec.rb")
-  end
-
-  def run_tests(test_file)
-    rspec_path = File.join(@project_dir, "bin", "rspec")
-
-    unless File.executable?(rspec_path)
-      abort_to_claude("rspec binary not found or not executable: #{rspec_path}")
-    end
-
-    log_info("Running: bin/rspec #{test_file}")
-
-    # Change to project directory for command execution
-    Dir.chdir(@project_dir) do
-      stdout, stderr, status = Open3.capture3("bin/rspec", test_file)
-
-      # Output both stdout and stderr
-      $stdout.print stdout
-      $stderr.print stderr
-
-      if status.success?
-        log_info("✅ Tests passed")
-        EXIT_SUCCESS
-      else
-        warn("❌ Tests failed - fix before continuing")
-        EXIT_FAILURE
-      end
-    end
-  rescue => e
-    abort_to_claude("Failed to run tests: #{e.message}")
-  end
-
-  def log_info(message)
-    warn(message)
-  end
-
-  def abort_to_claude(message)
-    warn("❌ ERROR: #{message}")
-    exit EXIT_FAILURE
-  end
-end
-
-# Run the script
-if __FILE__ == $0
-  runner = AffectedTestRunner.new
-  exit runner.run
-end