backspin 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e49507f2d196ebd4d7b4d39a6013d840224a357272fb5ba4880702e26d28c8d9
-  data.tar.gz: cfee20f6ff8b65c622bfc9482d85e49c78f78e1e9a2c91b5f09f71e2b1d61663
+  metadata.gz: 5f6f79191389f6f6f78661b402a1fa776534e37d87292471b708d0eb338779e6
+  data.tar.gz: 25c8091f368074e45c9f091a0beec04abaf3e5d5e883e3c6ed4d417ac8c2a349
 SHA512:
-  metadata.gz: 660d3af239a57512fbd74eecf2f7fc81c91a6fc42c0a95957952f01931bcd2b5f5387af2004557af985c8c3ef6f37c6b284e41b757af2919a241d5408060b25e
-  data.tar.gz: 6a0b7f7e2bc4533e80e8011fb17c1f851c31ddd6e831300efec0589423f541640e1ace953c75f066e8a9efc26c6e3fef886cc87941d204e09d1a2302d58adcbc
+  metadata.gz: 7f4e22608a611ee37a698f53b6959c74443272d30dd83fbe812abb80e73b068035c09873754ea7dad1289b056f2fed3c35e09c8c19944df87544268caaaeb490
+  data.tar.gz: e1313ad87c03e01386c6ede54ac706acf556c4667359c7c081cb60191dafa2c53a0ca5c8a58a0e8e01fe5028af7664077eda83f56fdd2c66cfa5b31bb04f0174

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 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.0)
       ostruct
       rspec-mocks (~> 3)
 

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/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/version.rb

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

data/lib/backspin.rb

@@ -19,6 +19,8 @@ require "backspin/record_result"
 module Backspin
   class RecordNotFoundError < StandardError; end
 
+  class VerificationError < StandardError; end
+
   # Include RSpec mocks methods
   extend RSpec::Mocks::ExampleMethods
 
@@ -79,7 +81,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 +92,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 +154,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 +164,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, error_message
+      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.0
 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.6.9
 specification_version: 4
 summary: Record and replay CLI interactions for testing
 test_files: []