backspin 0.4.5 → 0.6.0

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
@@ -135,6 +136,150 @@ module Backspin
       )
     end
 
+    # Performs capture recording by intercepting all stdout/stderr output
+    def perform_capture_recording
+      require "tempfile"
+
+      # Create temporary files for capturing output
+      stdout_tempfile = Tempfile.new("backspin_stdout")
+      stderr_tempfile = Tempfile.new("backspin_stderr")
+
+      begin
+        # Save original file descriptors
+        original_stdout_fd = $stdout.dup
+        original_stderr_fd = $stderr.dup
+
+        # Redirect both Ruby IO and file descriptors
+        $stdout.reopen(stdout_tempfile)
+        $stderr.reopen(stderr_tempfile)
+
+        # Execute the block
+        result = yield
+
+        # Flush and read captured output
+        $stdout.flush
+        $stderr.flush
+        stdout_tempfile.rewind
+        stderr_tempfile.rewind
+
+        captured_stdout = stdout_tempfile.read
+        captured_stderr = stderr_tempfile.read
+
+        # Create a single command representing all captured output
+        command = Command.new(
+          method_class: Backspin::Capturer,
+          args: ["<captured block>"],
+          stdout: captured_stdout,
+          stderr: captured_stderr,
+          status: 0,
+          recorded_at: Time.now.iso8601
+        )
+
+        record.add_command(command)
+        record.save(filter: @filter)
+
+        RecordResult.new(output: result, mode: :record, record: record)
+      ensure
+        # Restore original file descriptors
+        $stdout.reopen(original_stdout_fd)
+        $stderr.reopen(original_stderr_fd)
+        original_stdout_fd.close
+        original_stderr_fd.close
+
+        # Clean up temp files
+        stdout_tempfile.close!
+        stderr_tempfile.close!
+      end
+    end
+
+    # Performs capture verification by capturing output and comparing with recorded values
+    def perform_capture_verification
+      raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
+      raise RecordNotFoundError, "No commands found in record #{record.path}" if record.empty?
+
+      require "tempfile"
+
+      # Create temporary files for capturing output
+      stdout_tempfile = Tempfile.new("backspin_stdout")
+      stderr_tempfile = Tempfile.new("backspin_stderr")
+
+      begin
+        # Save original file descriptors
+        original_stdout_fd = $stdout.dup
+        original_stderr_fd = $stderr.dup
+
+        # Redirect both Ruby IO and file descriptors
+        $stdout.reopen(stdout_tempfile)
+        $stderr.reopen(stderr_tempfile)
+
+        # Execute the block
+        output = yield
+
+        # Flush and read captured output
+        $stdout.flush
+        $stderr.flush
+        stdout_tempfile.rewind
+        stderr_tempfile.rewind
+
+        captured_stdout = stdout_tempfile.read
+        captured_stderr = stderr_tempfile.read
+
+        # Get the recorded command (should be only one for capture)
+        recorded_command = record.commands.first
+
+        # Create actual command from captured output
+        actual_command = Command.new(
+          method_class: Backspin::Capturer,
+          args: ["<captured block>"],
+          stdout: captured_stdout,
+          stderr: captured_stderr,
+          status: 0
+        )
+
+        # Create CommandDiff for comparison
+        command_diff = CommandDiff.new(
+          recorded_command: recorded_command,
+          actual_command: actual_command,
+          matcher: @matcher
+        )
+
+        RecordResult.new(
+          output: output,
+          mode: :verify,
+          verified: command_diff.verified?,
+          record: record,
+          command_diffs: [command_diff]
+        )
+      ensure
+        # Restore original file descriptors
+        $stdout.reopen(original_stdout_fd)
+        $stderr.reopen(original_stderr_fd)
+        original_stdout_fd.close
+        original_stderr_fd.close
+
+        # Clean up temp files
+        stdout_tempfile.close!
+        stderr_tempfile.close!
+      end
+    end
+
+    # Performs capture playback - executes block normally but could optionally suppress output
+    def perform_capture_playback
+      raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
+      raise RecordNotFoundError, "No commands found in record" if record.empty?
+
+      # For now, just execute the block normally
+      # In the future, we could optionally suppress output or return recorded output
+      output = yield
+
+      RecordResult.new(
+        output: output,
+        mode: :playback,
+        verified: true,
+        record: record
+      )
+    end
+
     private
 
     def setup_capture3_replay_stub

data/lib/backspin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Backspin
-  VERSION = "0.4.5"
+  VERSION = "0.6.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"
@@ -165,6 +116,43 @@ module Backspin
       result
     end
 
+    # Captures all stdout/stderr output from a block
+    #
+    # @param record_name [String] Name for the record file
+    # @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 captured output
+    def capture(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(mode, record_path)
+
+      # Create or load the record based on mode
+      record = if mode == :record
+        Record.create(record_name)
+      else
+        Record.load_or_create(record_path)
+      end
+
+      # Create recorder with all needed context
+      recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter)
+
+      # Execute the appropriate mode
+      case mode
+      when :record
+        recorder.perform_capture_recording(&block)
+      when :verify
+        recorder.perform_capture_verification(&block)
+      when :playback
+        recorder.perform_capture_playback(&block)
+      else
+        raise ArgumentError, "Unknown mode: #{mode}"
+      end
+    end
+
     private
 
     def determine_mode(mode_option, record_path)

data/release.rake

@@ -4,7 +4,7 @@ require "bundler/gem_tasks"
 
 # Simplified release tasks using gem-release
 # Install with: gem install gem-release
-
+# https://github.com/svenfuchs/gem-release
 namespace :release do
   desc "Release a new version (bump, tag, release)"
   task :version, [:level] do |t, args|
@@ -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.6.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
@@ -165,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Record and replay CLI interactions for testing
 test_files: []