backspin 0.3.0 → 0.4.1

data/lib/backspin/recorder.rb

@@ -6,6 +6,7 @@ module Backspin
   # Handles stubbing and recording of command executions
   class Recorder
     include RSpec::Mocks::ExampleMethods
+    SUPPORTED_COMMAND_TYPES = [:capture3, :system]
 
     attr_reader :commands, :verification_data, :mode, :record
 
@@ -17,7 +18,7 @@ module Backspin
     end
 
     def record_calls(*command_types)
-      command_types = [:capture3, :system] if command_types.empty?
+      command_types = SUPPORTED_COMMAND_TYPES if command_types.empty?
 
       command_types.each do |command_type|
         record_call(command_type)
@@ -31,7 +32,7 @@ module Backspin
       when :capture3
         setup_capture3_call_stub
       else
-        raise ArgumentError, "Unknown command type: #{command_type}"
+        raise ArgumentError, "Unsupported command type: #{command_type} - currently supported types: #{SUPPORTED_COMMAND_TYPES.join(", ")}"
       end
     end
 
@@ -66,7 +67,6 @@ module Backspin
           # For system calls, we only track the exit status
           @verification_data["stdout"] = ""
           @verification_data["stderr"] = ""
-          # Derive exit status from result: true = 0, false = non-zero
           @verification_data["status"] = result ? 0 : 1
 
           result
@@ -107,12 +107,10 @@ module Backspin
       allow_any_instance_of(Object).to receive(:system) do |receiver, *args|
         command = @record.next_command
 
-        # Make sure this is a system command
         unless command.method_class == ::Kernel::System
           raise RecordNotFoundError, "Expected Kernel::System command but got #{command.method_class.name}"
         end
 
-        # Return true if exit status was 0, false otherwise
         command.status == 0
       rescue NoMoreRecordingsError => e
         raise RecordNotFoundError, e.message
@@ -121,17 +119,14 @@ module Backspin
 
     def setup_capture3_call_stub
       allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
-        # Execute the real command
         stdout, stderr, status = original_method.call(*args)
 
-        # Parse command args
         cmd_args = if args.length == 1 && args.first.is_a?(String)
           args.first.split(" ")
         else
           args
         end
 
-        # Create command with interaction data
         command = Command.new(
           method_class: Open3::Capture3,
           args: cmd_args,
@@ -142,17 +137,12 @@ module Backspin
         )
         @commands << command
 
-        # Store output for later access (last one wins)
-        Backspin.last_output = stdout
-
-        # Return original result
         [stdout, stderr, status]
       end
     end
 
     def setup_system_call_stub
       allow_any_instance_of(Object).to receive(:system).and_wrap_original do |original_method, receiver, *args|
-        # Execute the real system call
         result = original_method.call(receiver, *args)
 
         # Parse command args based on how system was called
@@ -164,14 +154,9 @@ module Backspin
           args
         end
 
-        # For system calls, stdout and stderr are not captured
-        # The caller of system() doesn't have access to them
-        stdout = ""
-        stderr = ""
-        # Derive exit status from result: true = 0, false = non-zero, nil = command failed
+        stdout, stderr = "", ""
         status = result ? 0 : 1
 
-        # Create command with interaction data
         command = Command.new(
           method_class: ::Kernel::System,
           args: parsed_args,
@@ -182,10 +167,6 @@ module Backspin
         )
         @commands << command
 
-        # Store output for later access (for consistency with capture3)
-        Backspin.last_output = stdout
-
-        # Return the original result (true/false/nil)
         result
       end
     end

data/lib/backspin/version.rb

@@ -1,3 +1,3 @@
 module Backspin
-  VERSION = "0.3.0"
+  VERSION = "0.4.1"
 end

data/lib/backspin.rb

@@ -5,9 +5,12 @@ require "pathname"
 require "ostruct"
 require "rspec/mocks"
 require "backspin/version"
+require "backspin/command_result"
 require "backspin/command"
+require "backspin/command_diff"
 require "backspin/record"
 require "backspin/recorder"
+require "backspin/record_result"
 
 module Backspin
   class RecordNotFoundError < StandardError; end
@@ -18,7 +21,7 @@ module Backspin
   # Configuration for Backspin
   class Configuration
     attr_accessor :scrub_credentials
-    # The directory where backspin will store its files - defaults to spec/backspin_data
+    # 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
@@ -26,7 +29,7 @@ module Backspin
     def initialize
       @scrub_credentials = true
       @credential_patterns = default_credential_patterns
-      @backspin_dir = Pathname(Dir.pwd).join("spec", "backspin_data")
+      @backspin_dir = Pathname(Dir.pwd).join("fixtures", "backspin")
     end
 
     def add_credential_pattern(pattern)
@@ -69,7 +72,9 @@ module Backspin
 
   class << self
     def configuration
-      @configuration ||= Configuration.new
+      return @configuration if @configuration
+
+      @configuration = Configuration.new
     end
 
     def configure
@@ -79,86 +84,6 @@ module Backspin
     def reset_configuration!
       @configuration = Configuration.new
     end
-  end
-
-  class Result
-    attr_reader :commands, :record_path
-
-    def initialize(commands:, record_path:)
-      @commands = commands
-      @record_path = record_path
-    end
-  end
-
-  class VerifyResult
-    attr_reader :record_path, :expected_output, :actual_output, :diff, :stderr_diff
-
-    def initialize(verified:, record_path:, expected_output: nil, actual_output: nil,
-      expected_stderr: nil, actual_stderr: nil, expected_status: nil, actual_status: nil,
-      command_executed: true)
-      @verified = verified
-      @record_path = record_path
-      @expected_output = expected_output
-      @actual_output = actual_output
-      @expected_stderr = expected_stderr
-      @actual_stderr = actual_stderr
-      @expected_status = expected_status
-      @actual_status = actual_status
-      @command_executed = command_executed
-
-      if !verified && expected_output && actual_output
-        @diff = generate_diff(expected_output, actual_output)
-      end
-
-      if !verified && expected_stderr && actual_stderr && expected_stderr != actual_stderr
-        @stderr_diff = generate_diff(expected_stderr, actual_stderr)
-      end
-    end
-
-    def verified?
-      @verified
-    end
-
-    def output
-      @actual_output
-    end
-
-    def error_message
-      return nil if verified?
-
-      "Output verification failed\nExpected: #{@expected_output.chomp}\nActual: #{@actual_output.chomp}"
-    end
-
-    def command_executed?
-      @command_executed
-    end
-
-    private
-
-    def generate_diff(expected, actual)
-      expected_lines = expected.lines
-      actual_lines = actual.lines
-      diff = []
-
-      # Simple diff for now
-      expected_lines.each do |line|
-        unless actual_lines.include?(line)
-          diff << "-#{line.chomp}"
-        end
-      end
-
-      actual_lines.each do |line|
-        unless expected_lines.include?(line)
-          diff << "+#{line.chomp}"
-        end
-      end
-
-      diff.join("\n")
-    end
-  end
-
-  class << self
-    attr_accessor :last_output
 
     def scrub_text(text)
       return text unless configuration.scrub_credentials && text
@@ -173,262 +98,219 @@ module Backspin
       scrubbed
     end
 
-    def call(record_name, filter: nil)
+    # 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] :matcher Custom matcher for verification
+    # @return [RecordResult] Result object with output and status
+    def run(record_name, options = {}, &block)
       raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
+      raise ArgumentError, "block is required" unless block_given?
 
       record_path = build_record_path(record_name)
+      mode = determine_mode(options[:mode], record_path)
+
+      case mode
+      when :record
+        perform_recording(record_name, record_path, options, &block)
+      when :verify
+        perform_verification(record_name, record_path, options, &block)
+      when :playback
+        perform_playback(record_name, record_path, options, &block)
+      else
+        raise ArgumentError, "Unknown mode: #{mode}"
+      end
+    end
 
-      # Create recorder to handle stubbing and command recording
-      recorder = Recorder.new
-      recorder.record_calls(:capture3, :system)
+    # 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
+    # @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)
 
-      yield
+      if result.verified? == false
+        error_message = "Backspin verification failed!\n"
+        error_message += "Record: #{result.record_path}\n"
 
-      # Save commands using new format
-      FileUtils.mkdir_p(File.dirname(record_path))
-      # Don't load existing data when creating new record
-      record = Record.new(record_path)
-      record.clear  # Clear any loaded data
-      recorder.commands.each { |cmd| record.add_command(cmd) }
-      record.save(filter: filter)
+        # Use the error_message from the result which is now properly formatted
+        error_message += "\n#{result.error_message}" if result.error_message
 
-      Result.new(commands: recorder.commands, record_path: Pathname.new(record_path))
-    end
+        raise RSpec::Expectations::ExpectationNotMetError, error_message
+      end
 
-    def output
-      last_output
+      result
     end
 
-    def use_record(record_name, options = {}, &block)
-      raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
+    private
 
-      record_path = build_record_path(record_name)
-      record_mode = options[:record] || :once
-      filter = options[:filter]
-
-      case record_mode
-      when :none
-        # Never record, only replay
-        unless File.exist?(record_path)
-          raise RecordNotFoundError, "Record not found: #{record_path}"
-        end
-        replay_record(record_path, &block)
-      when :all
-        # Always record
-        record_and_save_record(record_path, filter: filter, &block)
-      when :once
-        # Record if doesn't exist, replay if exists
-        if File.exist?(record_path)
-          replay_record(record_path, &block)
-        else
-          record_and_save_record(record_path, filter: filter, &block)
-        end
-      when :new_episodes
-        # Record new commands not in record
-        # For now, simplified: just append new recordings
-        record_new_episode(record_path, filter: filter, &block)
-      else
-        raise ArgumentError, "Unknown record mode: #{record_mode}"
-      end
+    def determine_mode(mode_option, record_path)
+      return mode_option if mode_option && mode_option != :auto
+
+      # Auto mode: record if file doesn't exist, verify if it does
+      File.exist?(record_path) ? :verify : :record
     end
 
-    def verify(record_name, mode: :strict, matcher: nil, &block)
-      record_path = build_record_path(record_name)
+    def perform_recording(_record_name, record_path, options)
+      recorder = Recorder.new
+      recorder.record_calls(:capture3, :system)
 
-      record = Record.load_or_create(record_path)
-      unless record.exists?
-        raise RecordNotFoundError, "Record not found: #{record_path}"
-      end
+      output = yield
 
-      if record.empty?
-        raise RecordNotFoundError, "No commands found in record"
+      if output.is_a?(Array) && output.size == 3
+        stdout, stderr, status = output
+        status_int = status.respond_to?(:exitstatus) ? status.exitstatus : status
+        output = [stdout, stderr, status_int]
       end
 
-      # For verify, we only handle single command verification for now
-      # Use the first command
-      command = record.commands.first
+      # Save the recording
+      FileUtils.mkdir_p(File.dirname(record_path))
+      record = Record.new(record_path)
+      record.clear
+      recorder.commands.each { |cmd| record.add_command(cmd) }
+      record.save(filter: options[:filter])
+
+      # Return result
+      RecordResult.new(
+        output: output,
+        mode: :record,
+        record_path: Pathname.new(record_path),
+        commands: recorder.commands
+      )
+    end
 
-      # Create recorder for verification
-      recorder = Recorder.new
+    def perform_verification(_record_name, record_path, options)
+      record = Record.load_or_create(record_path)
 
-      if mode == :playback
-        # Playback mode: return recorded output without running command
-        recorder.setup_playback_stub(command)
-
-        yield
-
-        # In playback mode, always verified
-        VerifyResult.new(
-          verified: true,
-          record_path: Pathname.new(record_path),
-          expected_output: command.stdout,
-          actual_output: command.stdout,
-          expected_stderr: command.stderr,
-          actual_stderr: command.stderr,
-          expected_status: command.status,
-          actual_status: command.status,
-          command_executed: false
-        )
-      elsif matcher
-        # Custom matcher verification
-        recorder.setup_verification_stub(command)
-
-        yield
-
-        # Call custom matcher - convert command back to hash format for matcher
-        recorded_data = command.to_h
-        verified = matcher.call(recorded_data, recorder.verification_data)
-
-        VerifyResult.new(
-          verified: verified,
-          record_path: Pathname.new(record_path),
-          expected_output: command.stdout,
-          actual_output: recorder.verification_data["stdout"],
-          expected_stderr: command.stderr,
-          actual_stderr: recorder.verification_data["stderr"],
-          expected_status: command.status,
-          actual_status: recorder.verification_data["status"]
-        )
-      else
-        # Default strict mode
-        recorder.setup_verification_stub(command)
-
-        yield
-
-        # Compare outputs
-        actual_stdout = recorder.verification_data["stdout"]
-        actual_stderr = recorder.verification_data["stderr"]
-        actual_status = recorder.verification_data["status"]
-
-        verified =
-          command.stdout == actual_stdout &&
-          command.stderr == actual_stderr &&
-          command.status == actual_status
-
-        VerifyResult.new(
-          verified: verified,
-          record_path: Pathname.new(record_path),
-          expected_output: command.stdout,
-          actual_output: actual_stdout,
-          expected_stderr: command.stderr,
-          actual_stderr: actual_stderr,
-          expected_status: command.status,
-          actual_status: actual_status
-        )
-      end
-    end
+      raise RecordNotFoundError, "Record not found: #{record_path}" unless record.exists?
+      raise RecordNotFoundError, "No commands found in record" if record.empty?
 
-    def verify!(record_name, mode: :strict, matcher: nil, &block)
-      result = verify(record_name, mode: mode, matcher: matcher, &block)
+      # For verification, we need to track all commands executed
+      recorder = Recorder.new(mode: :verify, record: record)
+      recorder.setup_replay_stubs
 
-      unless result.verified?
-        error_message = "Backspin verification failed!\n"
-        error_message += "Record: #{result.record_path}\n"
-        error_message += "Expected output:\n#{result.expected_output}\n"
-        error_message += "Actual output:\n#{result.actual_output}\n"
+      # Track verification results for each command
+      command_diffs = []
+      command_index = 0
+
+      # Override stubs to verify each command as it's executed
+      allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
+        recorded_command = record.commands[command_index]
 
-        if result.diff && !result.diff.empty?
-          error_message += "Diff:\n#{result.diff}\n"
+        if recorded_command.nil?
+          raise RecordNotFoundError, "No more recorded commands, but tried to execute: #{args.inspect}"
         end
 
-        if result.stderr_diff && !result.stderr_diff.empty?
-          error_message += "Stderr diff:\n#{result.stderr_diff}\n"
+        if recorded_command.method_class != Open3::Capture3
+          raise RecordNotFoundError, "Expected #{recorded_command.method_class.name} but got Open3.capture3"
         end
 
-        # Raise RSpec's expectation failure for proper integration
-        raise RSpec::Expectations::ExpectationNotMetError, error_message
-      end
+        # Execute the actual command
+        stdout, stderr, status = original_method.call(*args)
 
-      result
-    end
+        # Create verification result
+        actual_result = CommandResult.new(
+          stdout: stdout,
+          stderr: stderr,
+          status: status.exitstatus
+        )
 
-    private
+        # Create CommandDiff to track the comparison
+        command_diffs << CommandDiff.new(
+          recorded_command: recorded_command,
+          actual_result: actual_result,
+          matcher: options[:matcher]
+        )
 
-    def replay_record(record_path, &block)
-      record = Record.load_or_create(record_path)
-      unless record.exists?
-        raise RecordNotFoundError, "Record not found: #{record_path}"
+        command_index += 1
+        [stdout, stderr, status]
       end
 
-      if record.empty?
-        raise RecordNotFoundError, "No commands found in record"
-      end
+      allow_any_instance_of(Object).to receive(:system).and_wrap_original do |original_method, receiver, *args|
+        recorded_command = record.commands[command_index]
 
-      # Create recorder in replay mode
-      recorder = Recorder.new(mode: :replay, record: record)
-      recorder.setup_replay_stubs
+        if recorded_command.nil?
+          raise RecordNotFoundError, "No more recorded commands, but tried to execute: system #{args.inspect}"
+        end
 
-      block_return_value = yield
+        if recorded_command.method_class != ::Kernel::System
+          raise RecordNotFoundError, "Expected #{recorded_command.method_class.name} but got system"
+        end
 
-      # Return stdout, stderr, status if the block returned capture3 results
-      # Otherwise return the block's return value
-      if block_return_value.is_a?(Array) && block_return_value.size == 3 &&
-          block_return_value[0].is_a?(String) && block_return_value[1].is_a?(String)
-        # Convert status to integer for consistency
-        stdout, stderr, status = block_return_value
-        status_int = status.respond_to?(:exitstatus) ? status.exitstatus : status
-        [stdout, stderr, status_int]
-      else
-        block_return_value
-      end
-    end
+        # Execute the actual command
+        result = original_method.call(receiver, *args)
 
-    def record_and_save_record(record_path, filter: nil, &block)
-      # Create recorder to handle stubbing and command recording
-      recorder = Recorder.new
-      recorder.record_calls(:capture3, :system)
+        # Create verification result (system only gives us exit status)
+        actual_result = CommandResult.new(
+          stdout: "",
+          stderr: "",
+          status: result ? 0 : 1
+        )
 
-      block_return_value = yield
+        # Create CommandDiff to track the comparison
+        command_diffs << CommandDiff.new(
+          recorded_command: recorded_command,
+          actual_result: actual_result,
+          matcher: options[:matcher]
+        )
 
-      # Save commands using new format
-      FileUtils.mkdir_p(File.dirname(record_path))
-      # Don't load existing data when creating new record
-      record = Record.new(record_path)
-      record.clear  # Clear any loaded data
-      recorder.commands.each { |cmd| record.add_command(cmd) }
-      record.save(filter: filter)
+        command_index += 1
+        result
+      end
 
-      # Return appropriate value
-      if block_return_value.is_a?(Array) && block_return_value.size == 3
-        # Return stdout, stderr, status as integers
-        stdout, stderr, status = block_return_value
-        [stdout, stderr, status.respond_to?(:exitstatus) ? status.exitstatus : status]
-      else
-        block_return_value
+      # Execute block
+      output = yield
+
+      # Check if all commands were executed
+      if command_index < record.commands.size
+        raise RecordNotFoundError, "Expected #{record.commands.size} commands but only #{command_index} were executed"
       end
+
+      # Overall verification status
+      all_verified = command_diffs.all?(&:verified?)
+
+      RecordResult.new(
+        output: output,
+        mode: :verify,
+        verified: all_verified,
+        record_path: Pathname.new(record_path),
+        commands: record.commands,
+        command_diffs: command_diffs
+      )
     end
 
-    def record_new_episode(record_path, filter: nil, &block)
-      # For new_episodes mode, we'd need to track which commands have been seen
-      # For now, simplified implementation that just appends
+    def perform_playback(_record_name, record_path, _options)
       record = Record.load_or_create(record_path)
 
-      # Create recorder to handle stubbing and command recording
-      recorder = Recorder.new
-      recorder.record_calls(:capture3, :system)
+      raise RecordNotFoundError, "Record not found: #{record_path}" unless record.exists?
+      raise RecordNotFoundError, "No commands found in record" if record.empty?
 
-      result = yield
+      # Setup replay mode - this will handle returning values for all commands
+      recorder = Recorder.new(mode: :replay, record: record)
+      recorder.setup_replay_stubs
 
-      # Save all recordings (existing + new)
-      if recorder.commands.any?
-        recorder.commands.each { |cmd| record.add_command(cmd) }
-        record.save(filter: filter)
-      end
+      # Execute block (all commands will be stubbed with recorded values)
+      output = yield
 
-      # Return appropriate value
-      if result.is_a?(Array) && result.size == 3
-        stdout, stderr, status = result
-        [stdout, stderr, status.respond_to?(:exitstatus) ? status.exitstatus : status]
-      else
-        result
-      end
+      RecordResult.new(
+        output: output,
+        mode: :playback,
+        verified: true, # Always true for playback
+        record_path: Pathname.new(record_path),
+        commands: record.commands
+      )
     end
 
     def build_record_path(name)
       backspin_dir = configuration.backspin_dir
       backspin_dir.mkpath
 
-      File.join(backspin_dir, "#{name}.yaml")
+      File.join(backspin_dir, "#{name}.yml")
     end
   end
 end