backspin 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e49507f2d196ebd4d7b4d39a6013d840224a357272fb5ba4880702e26d28c8d9
-  data.tar.gz: cfee20f6ff8b65c622bfc9482d85e49c78f78e1e9a2c91b5f09f71e2b1d61663
+  metadata.gz: 803ecdad9628acd396e0d70b1e9e4081c612562f6872af8fa05108a820c61590
+  data.tar.gz: 563d3b7e8c413742453971859cf4bb31aeff11dbeee38d5804922ffa150615bb
 SHA512:
-  metadata.gz: 660d3af239a57512fbd74eecf2f7fc81c91a6fc42c0a95957952f01931bcd2b5f5387af2004557af985c8c3ef6f37c6b284e41b757af2919a241d5408060b25e
-  data.tar.gz: 6a0b7f7e2bc4533e80e8011fb17c1f851c31ddd6e831300efec0589423f541640e1ace953c75f066e8a9efc26c6e3fef886cc87941d204e09d1a2302d58adcbc
+  metadata.gz: 17aff3cf0ab930e13da63fa427135cde5e41816341d75ca7712662d4feefb4df1d753db983668a57562c9922d2dda4ae5f54d8cc579ce720d0ac9009015740ff
+  data.tar.gz: 203e8c9f1158712ae20e64864a20645cf5fad7e3bd79627bf6dfc7d7efa40cd51d5cbd2e5ac037ebe9a9f8c0408c33921f948400435aa023db32da9df9dfa8fc

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.7.1 - 2025-12-02
+* Include result object on VerificationError to make it easier for callers to debug verification errors
+
+## 0.7.0 - 2025-08-13
+* Breaking change: `Backspin.run` and `Backspin.capture` now raise an error if verification fails by default. Use `Backspin.configure` to opt-out. https://github.com/rsanheim/backspin/pull/18
+
+## 0.6.0 - 2025-08-13
+* Introduce `Backspin.capture` for rspec-less, simpler stdout/stderr testing https://github.com/rsanheim/backspin/pull/17
+
 ## 0.5.0 - 2025-06-11
 * Simplify matcher API so user provided matchers override defaults - [#14](https://github.com/rsanheim/backspin/pull/14)
 * Also extract a proper `Matcher` object

data/CLAUDE.md

@@ -41,9 +41,11 @@ bin/rake standard                # Alternative: Run via Rake task
 ### Core Components
 
 **Backspin Module** (`lib/backspin.rb`)
-- Main API: `call`, `verify`, `verify!`, `use_record`
+- Main API: `run`, `run!` (both raise on verification failure by default)
+- Capture API: `capture` (raises `VerificationError` on verification failure by default)
+- Legacy API: `call`, `verify`, `verify!`, `use_record`
 - Credential scrubbing logic
-- Configuration management
+- Configuration management (including `raise_on_verification_failure` which defaults to `true` and affects both `run` and `capture`)
 
 **Command Class** (`lib/backspin.rb`)
 - Represents a single CLI execution

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.6.0)
+    backspin (0.7.1)
       ostruct
       rspec-mocks (~> 3)
 
@@ -10,19 +10,19 @@ GEM
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
-    json (2.12.2)
+    json (2.16.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     ostruct (0.6.1)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
+    prism (1.6.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
-    regexp_parser (2.10.0)
+    regexp_parser (2.11.3)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -36,7 +36,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rubocop (1.81.7)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -44,10 +44,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.45.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.25.0)
@@ -55,10 +55,10 @@ GEM
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.50.0)
+    standard (1.52.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.81.7)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -68,9 +68,9 @@ GEM
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.25.0)
     timecop (0.9.10)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
 
 PLATFORMS
   arm64-darwin-24
@@ -84,4 +84,4 @@ DEPENDENCIES
   timecop (~> 0.9)
 
 BUNDLED WITH
-   2.6.9
+  4.0.0.beta2

data/README.md

@@ -1,4 +1,4 @@
-# Backspin 
+# Backspin
 
 [![Ruby](https://img.shields.io/badge/ruby-%23CC342D.svg?style=flat&logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
 [![Gem Version](https://img.shields.io/gem/v/backspin)](https://rubygems.org/gems/backspin)
@@ -33,7 +33,7 @@ And then run `bundle install`.
 
 ### Quick Start
 
-The simplest way to use Backspin is with the `run` method, which automatically records on the first execution and verifies on subsequent runs:
+The simplest way to use Backspin is with the `run` method, which automatically records on the first execution and verifies on subsequent runs.
 
 ```ruby
 require "backspin"
@@ -43,18 +43,20 @@ result = Backspin.run("my_command") do
   Open3.capture3("echo hello world")
 end
 
-# Subsequent runs: verifies the output matches
-result = Backspin.run("my_command") do
-  Open3.capture3("echo hello world")
+# Subsequent runs: verifies the output matches and raises on mismatch
+Backspin.run("my_command") do
+  Open3.capture3("echo hello world")  # Passes - output matches
 end
 
-# Use run! to automatically fail tests on mismatch
-Backspin.run!("my_command") do
-  Open3.capture3("echo hello mars")
+# This will raise an error automatically
+Backspin.run("my_command") do
+  Open3.capture3("echo hello mars")  
 end
-# Raises an error because stdout will not match the recorded output
+# Raises RSpec::Expectations::ExpectationNotMetError because output doesn't match
 ```
 
+By default, `Backspin.run` will raise an exception when verification fails, making your tests fail automatically. This is the recommended approach for most scenarios.
+
 ### Recording Modes
 
 Backspin supports different modes for controlling how commands are recorded and verified:
@@ -83,18 +85,25 @@ result = Backspin.run("slow_command", mode: :playback) do
 end
 ```
 
-### Using run! for automatic test failures
+### The run! method
+
+**NOTE:** This method is deprecated and will be removed soon.
 
-The `run!` method works exactly like `run` but automatically fails the test if verification fails:
+The `run!` method is maintained for backwards compatibility and works identically to `run`. Since `run` now raises on verification failure by default, both methods behave the same way:
 
 ```ruby
-# Automatically fail the test if output doesn't match
+# Both of these are equivalent and will raise on verification failure
+Backspin.run("echo_test") do
+  Open3.capture3("echo hello")
+end
+
 Backspin.run!("echo_test") do
   Open3.capture3("echo hello")
 end
-# Raises an error with detailed diff if verification fails from recorded data in "echo_test.yml"
 ```
 
+For new code, we recommend using `run` as it's the primary API method.
+
 ### Custom matchers
 
 For cases where full matching isn't suitable, you can override via `matcher:`. **NOTE**: If you provide
@@ -199,6 +208,42 @@ result.commands[3].stderr  # curl errors if any
 
 When verifying multiple commands, Backspin ensures all commands match in the exact order they were recorded. If any command differs, you'll get a detailed error showing which commands failed.
 
+### Configuration
+
+You can configure Backspin's behavior globally:
+
+```ruby
+Backspin.configure do |config|
+  # Both run and capture methods will raise on verification failure by default
+  config.raise_on_verification_failure = false # default is true
+  config.backspin_dir = "spec/fixtures/cli_records" # default is "fixtures/backspin"
+  config.scrub_credentials = false # default is true
+end
+```
+
+The `raise_on_verification_failure` setting affects both `Backspin.run` and `Backspin.capture`:
+- When `true` (default): Both methods raise exceptions on verification failure
+  - `run` raises `RSpec::Expectations::ExpectationNotMetError`
+  - `capture` raises `Backspin::VerificationError` (framework-agnostic)
+- When `false`: Both methods return a result with `verified?` set to false
+
+If you need to disable the raising behavior for a specific test, you can temporarily configure it:
+
+```ruby
+# Temporarily disable raising for this block
+Backspin.configure do |config|
+  config.raise_on_verification_failure = false
+end
+
+result = Backspin.run("my_test") do
+  Open3.capture3("echo different")
+end
+# result.verified? will be false but won't raise
+
+# Reset configuration
+Backspin.reset_configuration!
+```
+
 ### Credential Scrubbing
 
 If the CLI interaction you are recording contains sensitive data in stdout or stderr, you should be careful to make sure it is not recorded to yaml!

data/fixtures/backspin/all_for_logging.yml

@@ -4,8 +4,9 @@ format_version: '2.0'
 commands:
 - command_type: Open3::Capture3
   args:
-  - date
-  stdout: 'Wed Jun 11 02:48:13 CDT 2025
+  - echo
+  - 'test output with : colons'
+  stdout: 'test output with : colons
 
     '
   stderr: ''

data/fixtures/backspin/{use_record_filter.yml → strict_test.yml}

@@ -5,9 +5,8 @@ commands:
 - command_type: Open3::Capture3
   args:
   - echo
-  - "'hello"
-  - world'
-  stdout: 'HELLO WORLD
+  - exact output
+  stdout: 'exact output
 
     '
   stderr: ''

data/fixtures/backspin/version_test.yml

@@ -4,9 +4,9 @@ format_version: '2.0'
 commands:
 - command_type: Open3::Capture3
   args:
-  - ruby
-  - "--version"
-  stdout: 'ruby 3.4.4 (2025-05-14 revision a38531fd3f) +PRISM [arm64-darwin24]
+  - echo
+  - ruby version 3.4.5
+  stdout: 'ruby version 3.4.5
 
     '
   stderr: ''

data/lib/backspin/command_diff.rb

@@ -68,11 +68,11 @@ module Backspin
     end
 
     def stdout_diff
-      "stdout diff:\n#{generate_line_diff(recorded_command.stdout, actual_command.stdout)}"
+      "[stdout]\n#{generate_line_diff(recorded_command.stdout, actual_command.stdout)}"
     end
 
     def stderr_diff
-      "stderr diff:\n#{generate_line_diff(recorded_command.stderr, actual_command.stderr)}"
+      "[stderr]\n#{generate_line_diff(recorded_command.stderr, actual_command.stderr)}"
     end
 
     def generate_line_diff(expected, actual)

data/lib/backspin/configuration.rb

@@ -8,11 +8,14 @@ module Backspin
     attr_accessor :scrub_credentials
     # The directory where backspin will store its files - defaults to fixtures/backspin
     attr_accessor :backspin_dir
+    # Whether to raise an exception when verification fails in `run` method - defaults to true
+    attr_accessor :raise_on_verification_failure
     # Regex patterns to scrub from saved output
     attr_reader :credential_patterns
 
     def initialize
       @scrub_credentials = true
+      @raise_on_verification_failure = true
       @credential_patterns = default_credential_patterns
       @backspin_dir = Pathname(Dir.pwd).join("fixtures", "backspin")
     end

data/lib/backspin/recorder.rb

@@ -10,6 +10,7 @@ module Backspin
   # Handles stubbing and recording of command executions
   class Recorder
     include RSpec::Mocks::ExampleMethods
+
     SUPPORTED_COMMAND_TYPES = %i[capture3 system].freeze
 
     attr_reader :commands, :mode, :record, :matcher, :filter
@@ -153,7 +154,6 @@ module Backspin
         $stdout.reopen(stdout_tempfile)
         $stderr.reopen(stderr_tempfile)
 
-        # Execute the block
         result = yield
 
         # Flush and read captured output
@@ -168,7 +168,7 @@ module Backspin
         # Create a single command representing all captured output
         command = Command.new(
           method_class: Backspin::Capturer,
-          args: ["<captured block>"],
+          args: [],
           stdout: captured_stdout,
           stderr: captured_stderr,
           status: 0,

data/lib/backspin/version.rb

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

data/lib/backspin.rb

@@ -19,6 +19,27 @@ require "backspin/record_result"
 module Backspin
   class RecordNotFoundError < StandardError; end
 
+  class VerificationError < StandardError
+    attr_reader :result
+
+    def initialize(message, result: nil)
+      super(message)
+      @result = result
+    end
+
+    def diff
+      result.diff
+    end
+
+    def recorded_commands
+      result.command_diffs.map(&:recorded_command)
+    end
+
+    def actual_commands
+      result.command_diffs.map(&:actual_command)
+    end
+  end
+
   # Include RSpec mocks methods
   extend RSpec::Mocks::ExampleMethods
 
@@ -79,7 +100,7 @@ module Backspin
       recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter)
 
       # Execute the appropriate mode
-      case mode
+      result = case mode
       when :record
         recorder.setup_recording_stubs(:capture3, :system)
         recorder.perform_recording(&block)
@@ -90,6 +111,17 @@ module Backspin
       else
         raise ArgumentError, "Unknown mode: #{mode}"
       end
+
+      # Check if we should raise on verification failure
+      if configuration.raise_on_verification_failure && result.verified? == false
+        error_message = "Backspin verification failed!\n"
+        error_message += "Record: #{result.record.path}\n"
+        error_message += "\n#{result.error_message}" if result.error_message
+
+        raise RSpec::Expectations::ExpectationNotMetError, error_message
+      end
+
+      result
     end
 
     # Strict version of run that raises on verification failure
@@ -141,7 +173,7 @@ module Backspin
       recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter)
 
       # Execute the appropriate mode
-      case mode
+      result = case mode
       when :record
         recorder.perform_capture_recording(&block)
       when :verify
@@ -151,6 +183,22 @@ module Backspin
       else
         raise ArgumentError, "Unknown mode: #{mode}"
       end
+
+      # Check if we should raise on verification failure
+      if configuration.raise_on_verification_failure && result.verified? == false
+        error_message = "Backspin verification failed!\n"
+        error_message += "Record: #{result.record.path}\n"
+        error_message += result.error_message || "Output verification failed"
+
+        # Include diff if available
+        if result.diff
+          error_message += "\n\nDiff:\n#{result.diff}"
+        end
+
+        raise VerificationError.new(error_message, result: result)
+      end
+
+      result
     end
 
     private

data/script/lint

@@ -1,6 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Run Standard Ruby linter
-echo "Running Standard Ruby linter..."
-bundle exec standardrb "$@"
+FIX_OPT="--no-fix"
+while [[ $# -gt 0 ]]; do
+  case $1 in
+      -f|--fix)
+          FIX_OPT="--fix"
+          shift
+          ;;
+      --fix-unsafely)
+          FIX_OPT="--fix-unsafely"
+          shift
+          ;;
+      *)
+          echo "Error: Unknown option: $1"
+          exit 1
+          ;;
+  esac
+done
+
+bundle exec standardrb "$@" $FIX_OPT

data/script/run_affected_tests

@@ -0,0 +1,179 @@
+#!/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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Rob Sanheim
@@ -112,11 +112,11 @@ files:
 - fixtures/backspin/playback_system.yml
 - fixtures/backspin/playback_test.yml
 - fixtures/backspin/stderr_test.yml
+- fixtures/backspin/strict_test.yml
 - fixtures/backspin/string_symbol_test.yml
 - fixtures/backspin/system_echo.yml
 - fixtures/backspin/system_false.yml
 - fixtures/backspin/timestamp_test.yml
-- fixtures/backspin/use_record_filter.yml
 - fixtures/backspin/verify_system.yml
 - fixtures/backspin/verify_system_diff.yml
 - fixtures/backspin/version_test.yml
@@ -132,6 +132,7 @@ files:
 - lib/backspin/version.rb
 - release.rake
 - script/lint
+- script/run_affected_tests
 homepage: https://github.com/rsanheim/backspin
 licenses:
 - MIT
@@ -153,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Record and replay CLI interactions for testing
 test_files: []