backspin 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dced94847519f3f0f72a83bf4faf924d1a87271ba04891082f4e403124eda48c
-  data.tar.gz: d92e797ff52c989b6e1fd4910397d38770fe91b8e5b14aef4924412c11e8a804
+  metadata.gz: d9c7a5cfbb0da377abb251f0f53d3bef24f131e72664fde1de6372f02024a506
+  data.tar.gz: 3835b7201b3d9ca7d4b399b7f7e58fdfa8e81838e22a45b1f4d7225da2fca09b
 SHA512:
-  metadata.gz: d1dc52cdfbc6835548b8cdac5e0ef7ea26b4714a168870fb480f2e67c9d54b1305f5ef93a0942909a685c74b53a40323beb81bc2b79a2c46ad274ed1054f98a1
-  data.tar.gz: d3fc481d4e52eb5871c1deace41707a654981336c6570ffc07ae847e3d10a94f3ff602c09b764d0e3591841e334f8c8eed53028db217a3c5f1082e50b5493d9a
+  metadata.gz: e533519b22a5e4a83a3511eb3ffbfd0429432b75179988435806d006ff57aa7a91e7c3f73c3bb6d1fe2b587f90bef97febdc5952a82f69e46c1b6f7bc26f6087
+  data.tar.gz: ddffab372459f5c8ff6f8246cc5ffd988c3a28c5041d56f9961e13f7d5bd0a2c9bfde3bf6d844792e708b332e5acd836afd4d71d041ec1435e7a1644716d2156

data/Gemfile

@@ -6,8 +6,8 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem "rake", "~> 13.0"
-  gem "rspec", "~> 3.0"
+  gem "rake", "~> 13"
+  gem "rspec", "~> 3"
   gem "standard"
   gem "timecop", "~> 0.9"
 end

data/Gemfile.lock

@@ -1,20 +1,19 @@
 PATH
   remote: .
   specs:
-    backspin (0.4.5)
-      ostruct (~> 0.5.0)
-      rspec-mocks (~> 3.0)
+    backspin (0.5.0)
+      ostruct
+      rspec-mocks (~> 3)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
-    gem-release (2.2.4)
     json (2.12.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    ostruct (0.5.5)
+    ostruct (0.6.1)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
@@ -48,7 +47,7 @@ GEM
       rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.45.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.25.0)
@@ -79,9 +78,8 @@ PLATFORMS
 
 DEPENDENCIES
   backspin!
-  gem-release (~> 2)
-  rake (~> 13.0)
-  rspec (~> 3.0)
+  rake (~> 13)
+  rspec (~> 3)
   standard
   timecop (~> 0.9)
 

data/MATCHERS.md

@@ -0,0 +1,234 @@
+# Custom Matcher Usage Guide
+
+Backspin supports custom matchers for flexible verification of command outputs. This is useful when dealing with dynamic content like timestamps, process IDs, or version numbers.
+
+## Matcher Behavior
+
+**Important**: Matchers work as overrides - only the fields you specify will be checked. Fields without matchers are ignored completely.
+
+## Matcher Formats
+
+### 1. Simple Proc Matcher
+
+A proc matcher receives full command hashes and can check any combination of fields:
+
+```ruby
+# Check that output starts with expected prefix
+result = Backspin.run("version_test",
+  matcher: ->(recorded, actual) {
+    recorded["stdout"].start_with?("v") && 
+    actual["stdout"].start_with?("v")
+  }) do
+  Open3.capture3("node --version")
+end
+```
+
+### 2. Field-Specific Hash Matchers
+
+Use a hash to specify matchers for individual fields. Only specified fields are checked:
+
+```ruby
+# Only check stdout - stderr and status are ignored
+result = Backspin.run("timestamp_test",
+  matcher: {
+    stdout: ->(recorded, actual) {
+      # Both should contain a timestamp
+      recorded.match?(/\d{4}-\d{2}-\d{2}/) &&
+      actual.match?(/\d{4}-\d{2}-\d{2}/)
+    }
+  }) do
+  Open3.capture3("date")
+end
+
+# Check multiple specific fields
+result = Backspin.run("api_test",
+  matcher: {
+    stdout: ->(recorded, actual) {
+      # Check JSON structure exists
+      recorded.include?("\"data\":") &&
+      actual.include?("\"data\":")
+    },
+    status: ->(recorded, actual) {
+      # Both should succeed
+      recorded == 0 && actual == 0
+    }
+    # Note: stderr is NOT checked
+  }) do
+  Open3.capture3("curl", "-s", "https://api.example.com")
+end
+```
+
+### 3. The :all Matcher
+
+The `:all` matcher receives complete command hashes with all fields:
+
+```ruby
+# Cross-field validation
+result = Backspin.run("build_test",
+  matcher: {
+    all: ->(recorded, actual) {
+      # Check overall success: stdout has "BUILD SUCCESSFUL" AND status is 0
+      actual["stdout"].include?("BUILD SUCCESSFUL") &&
+      actual["status"] == 0
+    }
+  }) do
+  Open3.capture3("./build.sh")
+end
+```
+
+### 4. Combining :all with Field Matchers
+
+When both `:all` and field matchers are present, all must pass:
+
+```ruby
+result = Backspin.run("complex_test",
+  matcher: {
+    all: ->(recorded, actual) {
+      # Overall check: command succeeded
+      actual["status"] == 0
+    },
+    stdout: ->(recorded, actual) {
+      # Specific check: output contains result
+      actual.include?("Result:")
+    },
+    stderr: ->(recorded, actual) {
+      # No errors expected
+      actual.empty?
+    }
+  }) do
+  Open3.capture3("./process_data.sh")
+end
+```
+
+## Matcher Proc Arguments
+
+Field-specific matchers receive field values:
+- For `:stdout`, `:stderr` - String values
+- For `:status` - Integer exit code
+
+The `:all` matcher receives full hashes with these keys:
+- `"stdout"` - String output
+- `"stderr"` - String error output  
+- `"status"` - Integer exit code
+- `"command_type"` - String like "Open3::Capture3"
+- `"args"` - Array of command arguments
+- `"recorded_at"` - Timestamp string
+
+## Examples
+
+### Matching Version Numbers
+
+```ruby
+# Match major version only
+matcher: {
+  stdout: ->(recorded, actual) {
+    recorded_major = recorded[/(\d+)\./, 1]
+    actual_major = actual[/(\d+)\./, 1]
+    recorded_major == actual_major
+  }
+}
+```
+
+### Ignoring Timestamps
+
+```ruby
+# Strip timestamps before comparing
+matcher: {
+  stdout: ->(recorded, actual) {
+    pattern = /\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/
+    recorded.gsub(pattern, '[TIME]') == actual.gsub(pattern, '[TIME]')
+  }
+}
+```
+
+### JSON Response Validation
+
+```ruby
+# Validate JSON structure, ignore values
+matcher: {
+  stdout: ->(recorded, actual) {
+    begin
+      recorded_data = JSON.parse(recorded)
+      actual_data = JSON.parse(actual)
+      
+      # Same keys at top level
+      recorded_data.keys.sort == actual_data.keys.sort
+    rescue JSON::ParserError
+      false
+    end
+  }
+}
+```
+
+### Logging/Debugging with :all
+
+```ruby
+# Use :all for side effects while other matchers do validation
+logged_commands = []
+
+result = Backspin.run("debug_test",
+  matcher: {
+    all: ->(recorded, actual) {
+      # Log for debugging
+      logged_commands << {
+        args: actual["args"],
+        exit: actual["status"],
+        output_size: actual["stdout"].size
+      }
+      true  # Always pass
+    },
+    stdout: ->(recorded, actual) {
+      # Actual validation
+      actual.include?("SUCCESS")
+    }
+  }) do
+  Open3.capture3("./test.sh")
+end
+
+# Can inspect logged_commands after run
+```
+
+## Using with run!
+
+The `run!` method automatically fails tests when matchers return false:
+
+```ruby
+# This will raise an error if the matcher fails
+Backspin.run!("critical_test",
+  matcher: {
+    stdout: ->(r, a) { a.include?("OK") },
+    status: ->(r, a) { a == 0 }
+  }) do
+  Open3.capture3("./health_check.sh")
+end
+```
+
+## Migration from match_on
+
+The `match_on` option is deprecated. To migrate:
+
+```ruby
+# Old match_on style:
+Backspin.run("test", 
+  match_on: [:stdout, ->(r, a) { ... }])
+
+# New matcher style:
+Backspin.run("test",
+  matcher: { stdout: ->(r, a) { ... } })
+
+# Old match_on with multiple fields:
+Backspin.run("test",
+  match_on: [
+    [:stdout, ->(r, a) { ... }],
+    [:stderr, ->(r, a) { ... }]
+  ])
+
+# New matcher style:
+Backspin.run("test", 
+  matcher: {
+    stdout: ->(r, a) { ... },
+    stderr: ->(r, a) { ... }
+  })
+```
+
+Key difference: `match_on` required other fields to match exactly, while the new `matcher` hash only checks specified fields.

data/README.md

@@ -5,11 +5,11 @@
 [![CircleCI](https://img.shields.io/circleci/build/github/rsanheim/backspin/main)](https://circleci.com/gh/rsanheim/backspin)
 [![Last Commit](https://img.shields.io/github/last-commit/rsanheim/backspin/main)](https://github.com/rsanheim/backspin/commits/main)
 
-Backspin records and replays CLI interactions in Ruby for easy snapshot testing of command-line interfaces. Currently supports `Open3.capture3` and `system` and requires `rspec-mocks`.  More system calls and test integrations are welcome - send a PR!
+Backspin records and replays CLI interactions in Ruby for easy snapshot testing of command-line interfaces. Currently supports `Open3.capture3` and `system` and requires `rspec`, as it uses `rspec-mocks` under the hood.
 
-**NOTE:** Backspin should be considered alpha quality software while pre v1.0. It is in heavy development, and you can expect the API to change. It is being developed in conjunction with production CLI apps, so the API will be refined and improved as we get to 1.0.
+**NOTE:** Backspin should be considered alpha while pre version 1.0. It is in heavy development along-side some real-world CLI apps, so expect things to change and mature.
 
-Inspired by [VCR](https://github.com/vcr/vcr) and other [golden master](https://en.wikipedia.org/wiki/Golden_master_(software_development)) libraries.
+Inspired by [VCR](https://github.com/vcr/vcr) and other [golden master](https://en.wikipedia.org/wiki/Golden_master_(software_development)) testing libraries.
 
 ## Overview
 
@@ -17,6 +17,8 @@ Backspin is a Ruby library for snapshot testing (or characterization testing) of
 
 ## Installation
 
+Requires Ruby 3+ and will use rspec-mocks under the hood...Backspin has not been tested in other test frameworks.
+
 Add this line to your application's Gemfile in the `:test` group:
 
 ```ruby
@@ -95,20 +97,47 @@ end
 
 ### Custom matchers
 
-For cases where exact matching isn't suitable, you can provide custom verification logic:
+For cases where full matching isn't suitable, you can override via `matcher:`. **NOTE**: If you provide
+custom matchers, that is the only matching that will be done. Default matching is skipped if user-provided
+matchers are present.
+
+You can override the full match logic with a proc:
 
 ```ruby
-# Use custom logic to verify output
-result = Backspin.run("version_check", 
-                     matcher: ->(recorded, actual) {
-                       # Just check that both start with "ruby"
-                       recorded["stdout"].start_with?("ruby") && 
-                       actual["stdout"].start_with?("ruby")
-                     }) do
-  Open3.capture3("ruby --version")
+# Match stdout and status, ignore stderr
+my_matcher = ->(recorded, actual) {
+  recorded["stdout"] == actual["stdout"] && recorded["status"] != actual["status"]
+}
+
+result = Backspin.run("my_test", matcher: { all: my_matcher }) do
+  Open3.capture3("echo hello")
 end
 ```
 
+Or you can override specific fields:
+
+```ruby
+# Match dynamic timestamps in stdout
+timestamp_matcher = ->(recorded, actual) {
+  recorded.match?(/\d{4}-\d{2}-\d{2}/) && actual.match?(/\d{4}-\d{2}-\d{2}/)
+}
+
+result = Backspin.run("timestamp_test", matcher: { stdout: timestamp_matcher }) do
+  Open3.capture3("date")
+end
+
+# Match version numbers in stderr
+version_matcher = ->(recorded, actual) {
+  recorded[/v(\d+)\./, 1] == actual[/v(\d+)\./, 1]
+}
+
+result = Backspin.run("version_check", matcher: { stderr: version_matcher }) do
+  Open3.capture3("node --version")
+end
+```
+
+For more matcher examples and detailed documentation, see [MATCHERS.md](MATCHERS.md).
+
 ### Working with the Result Object
 
 The API returns a `RecordResult` object with helpful methods:
@@ -174,10 +203,10 @@ When verifying multiple commands, Backspin ensures all commands match in the exa
 
 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!
 
-By default, Backspin automatically scrubs [common credential patterns](https://github.com/rsanheim/backspin/blob/f8661f084aad0ae759cd971c4af31ccf9bdc6bba/lib/backspin.rb#L46-L65) from records, but this will only handle some common cases.
+By default, Backspin automatically tries to scrub [common credential patterns](https://github.com/rsanheim/backspin/blob/f8661f084aad0ae759cd971c4af31ccf9bdc6bba/lib/backspin.rb#L46-L65) from records, but this will only handle some common cases.
 Always review your record files before commiting them to source control. 
 
-A tool like [trufflehog](https://github.com/trufflesecurity/trufflehog) or [gitleaks](https://github.com/gitleaks/gitleaks) run via a pre-commit to catch any sensitive data before commit. 
+Use a tool like [trufflehog](https://github.com/trufflesecurity/trufflehog) or [gitleaks](https://github.com/gitleaks/gitleaks) run via a pre-commit to catch any sensitive data before commit. 
 
 ```ruby
 # This will automatically scrub AWS keys, API tokens, passwords, etc.
@@ -194,7 +223,6 @@ end
 Backspin.configure do |config|
   config.scrub_credentials = false
 end
-
 ```
 
 Automatic scrubbing includes:
@@ -203,16 +231,6 @@ Automatic scrubbing includes:
 - Generic API keys, auth tokens, and passwords
 - Private keys (RSA, etc.)
 
-## Features
-
-- **Simple recording**: Capture stdout, stderr, and exit status
-- **Flexible verification**: Strict matching, playback mode, or custom matchers
-- **Auto-naming**: Automatically generate record names from RSpec examples
-- **Multiple commands**: Record sequences of commands in a single record
-- **RSpec integration**: Works seamlessly with RSpec's mocking framework
-- **Human-readable**: YAML records are easy to read and edit
-- **Credential scrubbing**: Automatically removes sensitive data like API keys and passwords
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.

data/backspin.gemspec

@@ -25,8 +25,6 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "ostruct", "~> 0.5.0"
-  spec.add_dependency "rspec-mocks", "~> 3.0"
-
-  spec.add_development_dependency "gem-release", "~> 2"
+  spec.add_dependency "ostruct"
+  spec.add_dependency "rspec-mocks", "~> 3"
 end

data/fixtures/backspin/all_for_logging.yml

@@ -5,7 +5,7 @@ commands:
 - command_type: Open3::Capture3
   args:
   - date
-  stdout: 'Tue Jun 10 22:50:14 CDT 2025
+  stdout: 'Wed Jun 11 02:48:13 CDT 2025
 
     '
   stderr: ''

data/lib/backspin/command_diff.rb

@@ -9,23 +9,18 @@ module Backspin
     def initialize(recorded_command:, actual_command:, matcher: nil)
       @recorded_command = recorded_command
       @actual_command = actual_command
-      @matcher = normalize_matcher(matcher)
+      @matcher = Matcher.new(
+        config: matcher,
+        recorded_command: recorded_command,
+        actual_command: actual_command
+      )
     end
 
     # @return [Boolean] true if the command output matches
     def verified?
-      # First check if method classes match
       return false unless method_classes_match?
 
-      if matcher.nil?
-        recorded_command.result == actual_command.result
-      elsif matcher.is_a?(Proc) # basic all matcher: lambda { |recorded, actual| ...}
-        matcher.call(recorded_command.to_h, actual_command.to_h)
-      elsif matcher.is_a?(Hash) # matcher: {all: lambda { |recorded, actual| ...}, stdout: lambda { |recorded, actual| ...}}
-        verify_with_hash_matcher
-      else
-        raise ArgumentError, "Invalid matcher type: #{matcher.class}"
-      end
+      @matcher.match?
     end
 
     # @return [String, nil] Human-readable diff if not verified
@@ -34,7 +29,6 @@ module Backspin
 
       parts = []
 
-      # Check method class mismatch first
       unless method_classes_match?
         parts << "Command type mismatch: expected #{recorded_command.method_class.name}, got #{actual_command.method_class.name}"
       end
@@ -65,78 +59,12 @@ module Backspin
       recorded_command.method_class == actual_command.method_class
     end
 
-    def normalize_matcher(matcher)
-      return nil if matcher.nil?
-      return matcher if matcher.is_a?(Proc)
-
-      raise ArgumentError, "Matcher must be a Proc or Hash, got #{matcher.class}" unless matcher.is_a?(Hash)
-
-      # Validate hash keys and values
-      matcher.each do |key, value|
-        unless %i[all stdout stderr status].include?(key)
-          raise ArgumentError, "Invalid matcher key: #{key}. Must be one of: :all, :stdout, :stderr, :status"
-        end
-        raise ArgumentError, "Matcher for #{key} must be callable (Proc/Lambda)" unless value.respond_to?(:call)
-      end
-      matcher
-    end
-
-    def verify_with_hash_matcher
-      recorded_hash = recorded_command.to_h
-      actual_hash = actual_command.to_h
-
-      all_passed = matcher[:all].nil? || matcher[:all].call(recorded_hash, actual_hash)
-
-      fields_passed = %w[stdout stderr status].all? do |field|
-        field_sym = field.to_sym
-        if matcher[field_sym]
-          matcher[field_sym].call(recorded_hash[field], actual_hash[field])
-        else
-          recorded_hash[field] == actual_hash[field]
-        end
-      end
-
-      all_passed && fields_passed
-    end
-
     def failure_reason
-      reasons = []
-
-      # Check method class first
       unless method_classes_match?
-        reasons << "command type mismatch"
-        return reasons.join(", ")
-      end
-
-      if matcher.nil?
-        reasons << "stdout differs" if recorded_command.stdout != actual_command.stdout
-        reasons << "stderr differs" if recorded_command.stderr != actual_command.stderr
-        reasons << "exit status differs" if recorded_command.status != actual_command.status
-      elsif matcher.is_a?(Hash)
-        recorded_hash = recorded_command.to_h
-        actual_hash = actual_command.to_h
-
-        # Check :all matcher first
-        reasons << ":all matcher failed" if matcher[:all] && !matcher[:all].call(recorded_hash, actual_hash)
-
-        # Check field-specific matchers
-        %w[stdout stderr status].each do |field|
-          field_sym = field.to_sym
-          if matcher[field_sym]
-            unless matcher[field_sym].call(recorded_hash[field], actual_hash[field])
-              reasons << "#{field} custom matcher failed"
-            end
-          elsif recorded_hash[field] != actual_hash[field]
-            # Always check exact equality for fields without matchers
-            reasons << "#{field} differs"
-          end
-        end
-      else
-        # Proc matcher
-        reasons << "custom matcher failed"
+        return "command type mismatch"
       end
 
-      reasons.join(", ")
+      @matcher.failure_reason
     end
 
     def stdout_diff

data/lib/backspin/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Backspin
+  # Configuration for Backspin
+  class Configuration
+    attr_accessor :scrub_credentials
+    # The directory where backspin will store its files - defaults to fixtures/backspin
+    attr_accessor :backspin_dir
+    # Regex patterns to scrub from saved output
+    attr_reader :credential_patterns
+
+    def initialize
+      @scrub_credentials = true
+      @credential_patterns = default_credential_patterns
+      @backspin_dir = Pathname(Dir.pwd).join("fixtures", "backspin")
+    end
+
+    def add_credential_pattern(pattern)
+      @credential_patterns << pattern
+    end
+
+    def clear_credential_patterns
+      @credential_patterns = []
+    end
+
+    def reset_credential_patterns
+      @credential_patterns = default_credential_patterns
+    end
+
+    private
+
+    # Some default patterns for common credential types
+    def default_credential_patterns
+      [
+        # AWS credentials
+        /AKIA[0-9A-Z]{16}/, # AWS Access Key ID
+        %r{aws_secret_access_key\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})["']?}i,  # AWS Secret Key
+        %r{aws_session_token\s*[:=]\s*["']?([A-Za-z0-9/+=]+)["']?}i,         # AWS Session Token
+
+        # Google Cloud credentials
+        /AIza[0-9A-Za-z\-_]{35}/, # Google API Key
+        /[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com/, # Google OAuth2 client ID
+        /-----BEGIN (RSA )?PRIVATE KEY-----/, # Private keys
+
+        # Generic patterns
+        /api[_-]?key\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Generic API keys
+        /auth[_-]?token\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Auth tokens
+        /Bearer\s+([A-Za-z0-9\-_]+)/,                               # Bearer tokens
+        /password\s*[:=]\s*["']?([^"'\s]{8,})["']?/i, # Passwords
+        /-p([^"'\s]{8,})/, # MySQL-style password args
+        /secret\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i # Generic secrets
+      ]
+    end
+  end
+end

data/lib/backspin/matcher.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Handles matching logic between recorded and actual commands
+  class Matcher
+    attr_reader :config, :recorded_command, :actual_command
+
+    def initialize(config:, recorded_command:, actual_command:)
+      @config = normalize_config(config)
+      @recorded_command = recorded_command
+      @actual_command = actual_command
+    end
+
+    # @return [Boolean] true if commands match according to the configured matcher
+    def match?
+      if config.nil?
+        # Default behavior: check all fields for equality
+        default_matcher.call(recorded_command.to_h, actual_command.to_h)
+      elsif config.is_a?(Proc)
+        config.call(recorded_command.to_h, actual_command.to_h)
+      elsif config.is_a?(Hash)
+        verify_with_hash_matcher
+      else
+        raise ArgumentError, "Invalid matcher type: #{config.class}"
+      end
+    end
+
+    # @return [String] reason why matching failed
+    def failure_reason
+      reasons = []
+
+      if config.nil?
+        # Default matcher checks all fields
+        recorded_hash = recorded_command.to_h
+        actual_hash = actual_command.to_h
+
+        reasons << "stdout differs" if recorded_hash["stdout"] != actual_hash["stdout"]
+        reasons << "stderr differs" if recorded_hash["stderr"] != actual_hash["stderr"]
+        reasons << "exit status differs" if recorded_hash["status"] != actual_hash["status"]
+      elsif config.is_a?(Hash)
+        recorded_hash = recorded_command.to_h
+        actual_hash = actual_command.to_h
+
+        # Only check matchers that were provided
+        config.each do |field, matcher_proc|
+          case field
+          when :all
+            reasons << ":all matcher failed" unless matcher_proc.call(recorded_hash, actual_hash)
+          when :stdout, :stderr, :status
+            unless matcher_proc.call(recorded_hash[field.to_s], actual_hash[field.to_s])
+              reasons << "#{field} custom matcher failed"
+            end
+          end
+        end
+      else
+        # Proc matcher
+        reasons << "custom matcher failed"
+      end
+
+      reasons.join(", ")
+    end
+
+    private
+
+    def normalize_config(config)
+      return nil if config.nil?
+      return config if config.is_a?(Proc)
+
+      raise ArgumentError, "Matcher must be a Proc or Hash, got #{config.class}" unless config.is_a?(Hash)
+
+      # Validate hash keys and values
+      config.each do |key, value|
+        unless %i[all stdout stderr status].include?(key)
+          raise ArgumentError, "Invalid matcher key: #{key}. Must be one of: :all, :stdout, :stderr, :status"
+        end
+        raise ArgumentError, "Matcher for #{key} must be callable (Proc/Lambda)" unless value.respond_to?(:call)
+      end
+      config
+    end
+
+    def verify_with_hash_matcher
+      recorded_hash = recorded_command.to_h
+      actual_hash = actual_command.to_h
+
+      # Override-based: only run matchers that are explicitly provided
+      # Use map to ensure all matchers run, then check if all passed
+      results = config.map do |field, matcher_proc|
+        case field
+        when :all
+          matcher_proc.call(recorded_hash, actual_hash)
+        when :stdout, :stderr, :status
+          matcher_proc.call(recorded_hash[field.to_s], actual_hash[field.to_s])
+        else
+          # This should never happen due to normalize_config validation
+          raise ArgumentError, "Unknown field: #{field}"
+        end
+      end
+
+      results.all?
+    end
+
+    def default_matcher
+      @default_matcher ||= lambda do |recorded, actual|
+        recorded["stdout"] == actual["stdout"] &&
+          recorded["stderr"] == actual["stderr"] &&
+          recorded["status"] == actual["status"]
+      end
+    end
+  end
+end

data/lib/backspin/recorder.rb

@@ -12,12 +12,13 @@ module Backspin
     include RSpec::Mocks::ExampleMethods
     SUPPORTED_COMMAND_TYPES = %i[capture3 system].freeze
 
-    attr_reader :commands, :mode, :record, :options
+    attr_reader :commands, :mode, :record, :matcher, :filter
 
-    def initialize(mode: :record, record: nil, options: {})
+    def initialize(mode: :record, record: nil, matcher: nil, filter: nil)
       @mode = mode
       @record = record
-      @options = options
+      @matcher = matcher
+      @filter = filter
       @commands = []
       @playback_index = 0
       @command_diffs = []
@@ -45,14 +46,14 @@ module Backspin
     # Records registered commands, adds them to the record, saves the record, and returns the overall RecordResult
     def perform_recording
       result = yield
-      record.save(filter: options[:filter])
+      record.save(filter: @filter)
       RecordResult.new(output: result, mode: :record, record: record)
     end
 
     # Performs verification by executing commands and comparing with recorded values
     def perform_verification
       raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
-      raise RecordNotFoundError, "No commands found in record" if record.empty?
+      raise RecordNotFoundError, "No commands found in record #{record.path}" if record.empty?
 
       # Initialize tracking variables
       @command_diffs = []
@@ -76,7 +77,7 @@ module Backspin
           status: status.exitstatus
         )
 
-        @command_diffs << CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: options[:matcher])
+        @command_diffs << CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: @matcher)
         @command_index += 1
         [stdout, stderr, status]
       end
@@ -96,7 +97,7 @@ module Backspin
         )
 
         # Create CommandDiff to track the comparison
-        @command_diffs << CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: options[:matcher])
+        @command_diffs << CommandDiff.new(recorded_command: recorded_command, actual_command: actual_command, matcher: @matcher)
 
         @command_index += 1
         result

data/lib/backspin/version.rb

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

data/lib/backspin.rb

@@ -7,8 +7,10 @@ require "pathname"
 require "ostruct"
 require "rspec/mocks"
 require "backspin/version"
+require "backspin/configuration"
 require "backspin/command_result"
 require "backspin/command"
+require "backspin/matcher"
 require "backspin/command_diff"
 require "backspin/record"
 require "backspin/recorder"
@@ -20,58 +22,6 @@ module Backspin
   # Include RSpec mocks methods
   extend RSpec::Mocks::ExampleMethods
 
-  # Configuration for Backspin
-  class Configuration
-    attr_accessor :scrub_credentials
-    # The directory where backspin will store its files - defaults to fixtures/backspin
-    attr_accessor :backspin_dir
-    # Regex patterns to scrub from saved output
-    attr_reader :credential_patterns
-
-    def initialize
-      @scrub_credentials = true
-      @credential_patterns = default_credential_patterns
-      @backspin_dir = Pathname(Dir.pwd).join("fixtures", "backspin")
-    end
-
-    def add_credential_pattern(pattern)
-      @credential_patterns << pattern
-    end
-
-    def clear_credential_patterns
-      @credential_patterns = []
-    end
-
-    def reset_credential_patterns
-      @credential_patterns = default_credential_patterns
-    end
-
-    private
-
-    # Some default patterns for common credential types
-    def default_credential_patterns
-      [
-        # AWS credentials
-        /AKIA[0-9A-Z]{16}/, # AWS Access Key ID
-        %r{aws_secret_access_key\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})["']?}i,  # AWS Secret Key
-        %r{aws_session_token\s*[:=]\s*["']?([A-Za-z0-9/+=]+)["']?}i,         # AWS Session Token
-
-        # Google Cloud credentials
-        /AIza[0-9A-Za-z\-_]{35}/, # Google API Key
-        /[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com/, # Google OAuth2 client ID
-        /-----BEGIN (RSA )?PRIVATE KEY-----/, # Private keys
-
-        # Generic patterns
-        /api[_-]?key\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Generic API keys
-        /auth[_-]?token\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Auth tokens
-        /Bearer\s+([A-Za-z0-9\-_]+)/,                               # Bearer tokens
-        /password\s*[:=]\s*["']?([^"'\s]{8,})["']?/i, # Passwords
-        /-p([^"'\s]{8,})/, # MySQL-style password args
-        /secret\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i # Generic secrets
-      ]
-    end
-  end
-
   class << self
     def configuration
       return @configuration if @configuration
@@ -102,22 +52,21 @@ module Backspin
     # Primary API - records on first run, verifies on subsequent runs
     #
     # @param record_name [String] Name for the record file
-    # @param options [Hash] Options for recording/verification
-    # @option options [Symbol] :mode (:auto) Recording mode - :auto, :record, :verify, :playback
-    # @option options [Proc] :filter Custom filter for recorded data
-    # @option options [Proc, Hash] :matcher Custom matcher for verification
+    # @param mode [Symbol] Recording mode - :auto, :record, :verify, :playback
+    # @param matcher [Proc, Hash] Custom matcher for verification
     #   - Proc: ->(recorded, actual) { ... } for full command matching
     #   - Hash: { stdout: ->(recorded, actual) { ... }, stderr: ->(recorded, actual) { ... } } for field-specific matching
-    #   - Hash with :all key: { all: ->(recorded, actual) { ... }, stdout: ->(recorded, actual) { ... } } for combined matching
-    #     When both :all and field matchers are present, both must pass for verification to succeed.
-    #     Fields without specific matchers always use exact equality, regardless of :all presence.
+    #     Only specified fields are checked - fields without matchers are ignored
+    #   - Hash with :all key: { all: ->(recorded, actual) { ... } } receives full command hashes
+    #     Can be combined with field matchers - all specified matchers must pass
+    # @param filter [Proc] Custom filter for recorded data
     # @return [RecordResult] Result object with output and status
-    def run(record_name, options = {}, &block)
+    def run(record_name, mode: :auto, matcher: nil, filter: nil, &block)
       raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
       raise ArgumentError, "block is required" unless block_given?
 
       record_path = Record.build_record_path(record_name)
-      mode = determine_mode(options[:mode], record_path)
+      mode = determine_mode(mode, record_path)
 
       # Create or load the record based on mode
       record = if mode == :record
@@ -127,7 +76,7 @@ module Backspin
       end
 
       # Create recorder with all needed context
-      recorder = Recorder.new(record: record, options: options, mode: mode)
+      recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter)
 
       # Execute the appropriate mode
       case mode
@@ -146,11 +95,13 @@ module Backspin
     # Strict version of run that raises on verification failure
     #
     # @param record_name [String] Name for the record file
-    # @param options [Hash] Options for recording/verification
+    # @param mode [Symbol] Recording mode - :auto, :record, :verify, :playback
+    # @param matcher [Proc, Hash] Custom matcher for verification
+    # @param filter [Proc] Custom filter for recorded data
     # @return [RecordResult] Result object with output and status
     # @raise [RSpec::Expectations::ExpectationNotMetError] If verification fails
-    def run!(record_name, options = {}, &block)
-      result = run(record_name, options, &block)
+    def run!(record_name, mode: :auto, matcher: nil, filter: nil, &block)
+      result = run(record_name, mode: mode, matcher: matcher, filter: filter, &block)
 
       if result.verified? == false
         error_message = "Backspin verification failed!\n"

data/release.rake

@@ -23,12 +23,13 @@ namespace :release do
     sh "git commit -am 'Bump version to #{new_version}'"
     sh "git push"
 
-    sh "gem release --tag --github --push"
+    sh "gem release --tag --push"
+    Rake::Task["release:github"].invoke(new_version)
   end
 
-  desc "Create GitHub release for current version"
-  task :github do
-    version = Backspin::VERSION
+  desc "Create GitHub release for specified version or current version"
+  task :github, [:version] do |t, args|
+    version = args[:version] || Backspin::VERSION
 
     if system("which gh > /dev/null 2>&1")
       puts "\nCreating GitHub release for v#{version}..."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -13,44 +13,30 @@ dependencies:
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-mocks
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: gem-release
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2'
+        version: '3'
 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.
@@ -71,7 +57,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- MATCH_ON_USAGE.md
+- MATCHERS.md
 - README.md
 - Rakefile
 - backspin.gemspec
@@ -138,6 +124,8 @@ files:
 - lib/backspin/command.rb
 - lib/backspin/command_diff.rb
 - lib/backspin/command_result.rb
+- lib/backspin/configuration.rb
+- lib/backspin/matcher.rb
 - lib/backspin/record.rb
 - lib/backspin/record_result.rb
 - lib/backspin/recorder.rb

data/MATCH_ON_USAGE.md

@@ -1,110 +0,0 @@
-# Using match_on for Field-Specific Verification
-
-The `match_on` option allows you to use custom matchers for specific fields while maintaining exact equality checks for all other fields. This is useful when dealing with dynamic content like timestamps, process IDs, or version numbers.
-
-## Basic Usage
-
-### Single Field Matcher
-
-```ruby
-# Record a command with a timestamp
-Backspin.run("timestamp_test") do
-  Open3.capture3("date")
-end
-
-# Verify with a custom matcher for stdout
-result = Backspin.run("timestamp_test",
-  match_on: [:stdout, ->(recorded, actual) {
-    # Both should contain a day of the week
-    recorded.match?(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/) &&
-    actual.match?(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/)
-  }]) do
-  Open3.capture3("date")
-end
-```
-
-### Multiple Field Matchers
-
-```ruby
-# Match different fields with different rules
-result = Backspin.run("multi_field_test",
-  match_on: [
-    [:stdout, ->(recorded, actual) {
-      # Match process ID format
-      recorded.match?(/PID: \d+/) && actual.match?(/PID: \d+/)
-    }],
-    [:stderr, ->(recorded, actual) {
-      # Match error type, ignore details
-      recorded.include?("Error:") && actual.include?("Error:")
-    }]
-  ]) do
-  Open3.capture3("./my_script.sh")
-end
-```
-
-## Matcher Format
-
-The `match_on` option accepts two formats:
-
-1. **Single field**: `[:field_name, matcher_proc]`
-2. **Multiple fields**: `[[:field1, matcher1], [:field2, matcher2], ...]`
-
-Valid field names are:
-- `:stdout` - Standard output
-- `:stderr` - Standard error
-- `:status` - Exit status code
-
-## Matcher Proc
-
-The matcher proc receives two arguments:
-- `recorded_value` - The value from the saved recording
-- `actual_value` - The value from the current execution
-
-It should return `true` if the values match according to your criteria, `false` otherwise.
-
-## Examples
-
-### Matching Version Numbers
-
-```ruby
-# Match major version only
-match_on: [:stdout, ->(recorded, actual) {
-  recorded.match(/Version: (\d+)\./) && 
-  actual.match(/Version: (\d+)\./) &&
-  $1 == $1  # Major versions match
-}]
-```
-
-### Ignoring Timestamps
-
-```ruby
-# Match log format but ignore timestamp
-match_on: [:stdout, ->(recorded, actual) {
-  # Remove timestamps before comparing
-  recorded.gsub(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/, '') ==
-  actual.gsub(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/, '')
-}]
-```
-
-### Handling Dynamic IDs
-
-```ruby
-# Match API response structure, ignore dynamic IDs
-match_on: [:stdout, ->(recorded, actual) {
-  recorded_json = JSON.parse(recorded)
-  actual_json = JSON.parse(actual)
-  
-  # Compare structure, not values
-  recorded_json.keys.sort == actual_json.keys.sort
-}]
-```
-
-## Important Notes
-
-1. **Other fields must match exactly**: When using `match_on`, all fields not specified in the matcher list must match exactly. If stdout has a custom matcher but stderr doesn't, stderr must be identical to pass verification.
-
-2. **Precedence**: If both `matcher` and `match_on` options are provided, `matcher` takes precedence (for backward compatibility).
-
-3. **Error messages**: When verification fails with `match_on`, the error will indicate which fields failed and whether they failed exact matching or custom matching.
-
-4. **Works with run!**: The `match_on` option works with both `run` and `run!` methods.