backspin 0.4.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dced94847519f3f0f72a83bf4faf924d1a87271ba04891082f4e403124eda48c
-  data.tar.gz: d92e797ff52c989b6e1fd4910397d38770fe91b8e5b14aef4924412c11e8a804
+  metadata.gz: e49507f2d196ebd4d7b4d39a6013d840224a357272fb5ba4880702e26d28c8d9
+  data.tar.gz: cfee20f6ff8b65c622bfc9482d85e49c78f78e1e9a2c91b5f09f71e2b1d61663
 SHA512:
-  metadata.gz: d1dc52cdfbc6835548b8cdac5e0ef7ea26b4714a168870fb480f2e67c9d54b1305f5ef93a0942909a685c74b53a40323beb81bc2b79a2c46ad274ed1054f98a1
-  data.tar.gz: d3fc481d4e52eb5871c1deace41707a654981336c6570ffc07ae847e3d10a94f3ff602c09b764d0e3591841e334f8c8eed53028db217a3c5f1082e50b5493d9a
+  metadata.gz: 660d3af239a57512fbd74eecf2f7fc81c91a6fc42c0a95957952f01931bcd2b5f5387af2004557af985c8c3ef6f37c6b284e41b757af2919a241d5408060b25e
+  data.tar.gz: 6a0b7f7e2bc4533e80e8011fb17c1f851c31ddd6e831300efec0589423f541640e1ace953c75f066e8a9efc26c6e3fef886cc87941d204e09d1a2302d58adcbc

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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
+
 ## 0.4.2 - 2025-06-10
 Unified `:match` API for customizing how actual commands are matched against recorded commands. - [#11](https://github.com/rsanheim/backspin/pull/11)
 

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.6.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.rb

@@ -52,6 +52,8 @@ module Backspin
         Open3::Capture3
       when "Kernel::System"
         ::Kernel::System
+      when "Backspin::Capturer"
+        Backspin::Capturer
       else
         # Default to capture3 for backwards compatibility
         Open3::Capture3
@@ -97,3 +99,8 @@ end
 module ::Kernel
   class System; end
 end
+
+# Define the Backspin::Capturer class for identification
+module Backspin
+  class Capturer; end
+end

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