backspin 0.11.0 → 0.13.0

data/fixtures/projects/dummy_cli_gem/exe/dummy_cli_gem

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "dummy_cli_gem"
+
+exit(DummyCliGem::CLI.run(ARGV))

data/fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_echo.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T01:57:42-06:00'
+recorded_at: '2026-02-11T01:57:42-06:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - echo
+  - hello from dummy gem
+  stdout: 'hello from dummy gem
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T01:57:42-06:00'

data/fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_ls.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T01:57:42-06:00'
+recorded_at: '2026-02-11T01:57:42-06:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - list
+  - spec/fixtures/listing_target
+  stdout: 'alpha.txt
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T01:57:42-06:00'

data/fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/cli.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module DummyCliGem
+  module CLI
+    module_function
+
+    def run(argv, out: $stdout, err: $stderr)
+      command = argv.first
+
+      case command
+      when "echo"
+        text = argv[1]
+        return usage(err) if text.nil? || text.empty?
+
+        stdout, stderr, status = Open3.capture3("echo", text)
+      when "list"
+        target = argv[1] || "."
+        stdout, stderr, status = Open3.capture3("ls", "-1", target)
+      else
+        return usage(err)
+      end
+
+      out.print(stdout)
+      err.print(stderr)
+      status.exitstatus
+    end
+
+    def usage(err)
+      err.puts("usage: dummy_cli_gem echo <text> | dummy_cli_gem list <path>")
+      1
+    end
+  end
+end

data/fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DummyCliGem
+  VERSION = "0.1.0"
+end

data/fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "dummy_cli_gem/version"
+require "dummy_cli_gem/cli"
+
+module DummyCliGem
+end

data/fixtures/projects/dummy_cli_gem/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.0"

data/fixtures/projects/dummy_cli_gem/spec/dummy_cli_gem_backspin_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "DummyCliGem Backspin full-stack fixture" do
+  let(:project_root) { Pathname(__dir__).join("..").expand_path }
+
+  it "verifies echo command output from committed YAML" do
+    expect(BACKSPIN_DIR.join("dummy_echo.yml")).to exist
+
+    result = Backspin.run(
+      ["ruby", "exe/dummy_cli_gem", "echo", "hello from dummy gem"],
+      name: "dummy_echo"
+    )
+
+    expect(result).to be_verified
+    expect(result.actual.stdout).to eq("hello from dummy gem\n")
+    expect(result.actual.stderr).to eq("")
+    expect(result.actual.status).to eq(0)
+  end
+
+  it "verifies list command output from committed YAML" do
+    expect(BACKSPIN_DIR.join("dummy_ls.yml")).to exist
+
+    result = Backspin.run(
+      ["ruby", "exe/dummy_cli_gem", "list", "spec/fixtures/listing_target"],
+      name: "dummy_ls"
+    )
+
+    expect(result).to be_verified
+    expect(result.actual.stdout).to eq("alpha.txt\n")
+    expect(result.actual.stderr).to eq("")
+    expect(result.actual.status).to eq(0)
+  end
+
+  it "uses current Backspin record format for fixture YAML files" do
+    %w[dummy_echo dummy_ls].each do |record_name|
+      record_path = BACKSPIN_DIR.join("#{record_name}.yml")
+      expect(record_path).to exist
+
+      record_data = YAML.load_file(record_path)
+      expect(record_data["format_version"]).to eq("4.1")
+      expect(record_data["snapshot"]["command_type"]).to eq("Open3::Capture3")
+    end
+  end
+end

data/fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_echo.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T07:43:21+00:00'
+recorded_at: '2026-02-11T07:43:21+00:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - echo
+  - hello from dummy gem
+  stdout: 'hello from dummy gem
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T07:43:21+00:00'

data/fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_ls.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T07:43:21+00:00'
+recorded_at: '2026-02-11T07:43:21+00:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - list
+  - spec/fixtures/listing_target
+  stdout: 'alpha.txt
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T07:43:21+00:00'

data/fixtures/projects/dummy_cli_gem/spec/fixtures/listing_target/alpha.txt

@@ -0,0 +1 @@
+alpha fixture file

data/fixtures/projects/dummy_cli_gem/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "pathname"
+require "yaml"
+require "backspin"
+require "dummy_cli_gem"
+
+BACKSPIN_DIR = Pathname(__dir__).join("fixtures", "backspin")
+
+Backspin.configure do |config|
+  config.backspin_dir = BACKSPIN_DIR
+  config.logger = nil
+end
+
+RSpec.configure do |config|
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |expectations|
+    expectations.syntax = :expect
+  end
+end

data/lib/backspin/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "logger"
 require "pathname"
 
 module Backspin
@@ -10,6 +11,8 @@ module Backspin
     attr_accessor :backspin_dir
     # Whether to raise an exception when verification fails in `run`/`capture` - defaults to true
     attr_accessor :raise_on_verification_failure
+    # Logger for Backspin diagnostics - defaults to WARN level, logfmt-lite format
+    attr_accessor :logger
     # Regex patterns to scrub from saved output
     attr_reader :credential_patterns
 
@@ -18,6 +21,7 @@ module Backspin
       @raise_on_verification_failure = true
       @credential_patterns = default_credential_patterns
       @backspin_dir = Pathname(Dir.pwd).join("fixtures", "backspin")
+      @logger = default_logger
     end
 
     def add_credential_pattern(pattern)
@@ -34,6 +38,15 @@ module Backspin
 
     private
 
+    def default_logger
+      logger = Logger.new($stdout)
+      logger.level = Logger::WARN
+      logger.formatter = proc { |severity, _time, _progname, msg|
+        "level=#{severity.downcase} lib=backspin #{msg}\n"
+      }
+      logger
+    end
+
     # Some default patterns for common credential types
     def default_credential_patterns
       [

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.11.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"
@@ -14,8 +15,14 @@ require "backspin/backspin_result"
 require "backspin/recorder"
 
 module Backspin
+  VALID_MODES = %i[auto record verify].freeze
+
   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
 
@@ -113,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)
@@ -145,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?
@@ -176,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,
@@ -199,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}"
@@ -210,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
@@ -232,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
 
@@ -242,8 +290,26 @@ module Backspin
     def determine_mode(mode_option, record_path)
       return mode_option if mode_option && mode_option != :auto
 
-      # Auto mode: record if file doesn't exist, verify if it does
-      File.exist?(record_path) ? :verify : :record
+      env_mode = mode_from_env
+      if env_mode && env_mode != :auto
+        configuration.logger&.debug { "event=mode_resolved mode=#{env_mode} source=env record=#{record_path}" }
+        return env_mode
+      end
+
+      resolved = File.exist?(record_path) ? :verify : :record
+      configuration.logger&.debug { "event=mode_resolved mode=#{resolved} source=auto record=#{record_path}" }
+      resolved
+    end
+
+    def mode_from_env
+      raw = ENV["BACKSPIN_MODE"]
+      return if raw.nil? || raw.strip.empty?
+
+      mode = raw.strip.downcase.to_sym
+      return mode if VALID_MODES.include?(mode)
+
+      raise ArgumentError,
+        "Invalid BACKSPIN_MODE value: #{raw.inspect}. Allowed values: auto, record, verify"
     end
 
     def validate_mode!(mode)

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.0"

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Rob Sanheim
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 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.
@@ -38,8 +52,28 @@ 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
+- fixtures/projects/dummy_cli_gem/Gemfile
+- fixtures/projects/dummy_cli_gem/Gemfile.lock
+- fixtures/projects/dummy_cli_gem/LICENSE.txt
+- fixtures/projects/dummy_cli_gem/README.md
+- fixtures/projects/dummy_cli_gem/Rakefile
+- fixtures/projects/dummy_cli_gem/dummy_cli_gem.gemspec
+- fixtures/projects/dummy_cli_gem/exe/dummy_cli_gem
+- fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_echo.yml
+- fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_ls.yml
+- fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem.rb
+- fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/cli.rb
+- fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/version.rb
+- fixtures/projects/dummy_cli_gem/mise.toml
+- fixtures/projects/dummy_cli_gem/spec/dummy_cli_gem_backspin_spec.rb
+- fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_echo.yml
+- fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_ls.yml
+- fixtures/projects/dummy_cli_gem/spec/fixtures/listing_target/alpha.txt
+- fixtures/projects/dummy_cli_gem/spec/spec_helper.rb
 - lib/backspin.rb
 - lib/backspin/backspin_result.rb
 - lib/backspin/command_diff.rb
@@ -49,9 +83,9 @@ files:
 - lib/backspin/recorder.rb
 - lib/backspin/snapshot.rb
 - lib/backspin/version.rb
+- mise.toml
 - release.rake
 - script/lint
-- script/run_affected_tests
 homepage: https://github.com/rsanheim/backspin
 licenses:
 - MIT
@@ -66,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: []