backspin 0.7.1 → 0.9.0

data/lib/backspin.rb

@@ -4,17 +4,14 @@ require "yaml"
 require "fileutils"
 require "open3"
 require "pathname"
-require "ostruct"
-require "rspec/mocks"
 require "backspin/version"
 require "backspin/configuration"
-require "backspin/command_result"
-require "backspin/command"
+require "backspin/snapshot"
 require "backspin/matcher"
 require "backspin/command_diff"
 require "backspin/record"
+require "backspin/backspin_result"
 require "backspin/recorder"
-require "backspin/record_result"
 
 module Backspin
   class RecordNotFoundError < StandardError; end
@@ -31,18 +28,15 @@ module Backspin
       result.diff
     end
 
-    def recorded_commands
-      result.command_diffs.map(&:recorded_command)
+    def expected_snapshot
+      result.expected
     end
 
-    def actual_commands
-      result.command_diffs.map(&:actual_command)
+    def actual_snapshot
+      result.actual
     end
   end
 
-  # Include RSpec mocks methods
-  extend RSpec::Mocks::ExampleMethods
-
   class << self
     def configuration
       return @configuration if @configuration
@@ -72,136 +66,167 @@ module Backspin
 
     # Primary API - records on first run, verifies on subsequent runs
     #
+    # @param command [String, Array] Command to execute via Open3.capture3
+    # @param name [String] Name for the record file
+    # @param env [Hash] Environment variables to pass to Open3.capture3
+    # @param mode [Symbol] Recording mode - :auto, :record, :verify
+    # @param matcher [Proc, Hash] Custom matcher for verification
+    # @param filter [Proc] Custom filter for recorded data
+    # @return [BackspinResult] Aggregate result for this run
+    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, &block)
+      if block_given?
+        raise ArgumentError, "command must be omitted when using a block" unless command.nil?
+        raise ArgumentError, "env is not supported when using a block" unless env.nil?
+
+        return perform_capture(name, mode: mode, matcher: matcher, filter: filter, &block)
+      end
+
+      raise ArgumentError, "command is required" if command.nil?
+
+      perform_command_run(command, name: name, env: env, mode: mode, matcher: matcher, filter: filter)
+    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 mode [Symbol] Recording mode - :auto, :record, :verify
     # @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
-    #     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, mode: :auto, matcher: nil, filter: nil, &block)
+    # @return [BackspinResult] Aggregate result for this run
+    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?
 
+      perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, &block)
+    end
+
+    private
+
+    def perform_capture(record_name, mode:, matcher:, filter:, &block)
       record_path = Record.build_record_path(record_name)
       mode = determine_mode(mode, record_path)
+      validate_mode!(mode)
 
-      # 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
       result = case mode
       when :record
-        recorder.setup_recording_stubs(:capture3, :system)
-        recorder.perform_recording(&block)
+        recorder.perform_capture_recording(&block)
       when :verify
-        recorder.perform_verification(&block)
-      when :playback
-        recorder.perform_playback(&block)
+        recorder.perform_capture_verification(&block)
       else
         raise ArgumentError, "Unknown mode: #{mode}"
       end
 
-      # Check if we should raise on verification failure
-      if configuration.raise_on_verification_failure && result.verified? == false
-        error_message = "Backspin verification failed!\n"
-        error_message += "Record: #{result.record.path}\n"
-        error_message += "\n#{result.error_message}" if result.error_message
-
-        raise RSpec::Expectations::ExpectationNotMetError, error_message
-      end
-
-      result
-    end
-
-    # Strict version of run that raises on verification failure
-    #
-    # @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 output and status
-    # @raise [RSpec::Expectations::ExpectationNotMetError] If verification fails
-    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"
-        error_message += "Record: #{result.record.path}\n"
-
-        # Use the error_message from the result which is now properly formatted
-        error_message += "\n#{result.error_message}" if result.error_message
-
-        raise RSpec::Expectations::ExpectationNotMetError, error_message
-      end
+      raise_on_verification_failure!(result)
 
       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)
+    def perform_command_run(command, name:, env:, mode:, matcher:, filter:)
+      record_path = Record.build_record_path(name)
       mode = determine_mode(mode, record_path)
+      validate_mode!(mode)
 
-      # Create or load the record based on mode
       record = if mode == :record
-        Record.create(record_name)
+        Record.create(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)
+      normalized_env = env.nil? ? nil : normalize_env(env)
 
-      # Execute the appropriate mode
       result = case mode
       when :record
-        recorder.perform_capture_recording(&block)
+        stdout, stderr, status = execute_command(command, normalized_env)
+        actual_snapshot = Snapshot.new(
+          command_type: Open3::Capture3,
+          args: command,
+          env: normalized_env,
+          stdout: stdout,
+          stderr: stderr,
+          status: status.exitstatus,
+          recorded_at: Time.now.iso8601
+        )
+        record.set_snapshot(actual_snapshot)
+        record.save(filter: filter)
+        BackspinResult.new(
+          mode: :record,
+          record_path: record.path,
+          actual: actual_snapshot,
+          output: [stdout, stderr, status]
+        )
       when :verify
-        recorder.perform_capture_verification(&block)
-      when :playback
-        recorder.perform_capture_playback(&block)
+        raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
+        raise RecordNotFoundError, "No snapshot found in record #{record.path}" if record.empty?
+
+        expected_snapshot = record.snapshot
+        unless expected_snapshot.command_type == Open3::Capture3
+          raise RecordFormatError, "Invalid record format: expected Open3::Capture3 for run"
+        end
+
+        stdout, stderr, status = execute_command(command, normalized_env)
+        actual_snapshot = Snapshot.new(
+          command_type: Open3::Capture3,
+          args: command,
+          env: normalized_env,
+          stdout: stdout,
+          stderr: stderr,
+          status: status.exitstatus
+        )
+        command_diff = CommandDiff.new(expected: expected_snapshot, actual: actual_snapshot, matcher: matcher)
+        BackspinResult.new(
+          mode: :verify,
+          record_path: record.path,
+          actual: actual_snapshot,
+          expected: expected_snapshot,
+          verified: command_diff.verified?,
+          command_diff: command_diff,
+          output: [stdout, stderr, status]
+        )
       else
         raise ArgumentError, "Unknown mode: #{mode}"
       end
 
-      # Check if we should raise on verification failure
-      if configuration.raise_on_verification_failure && result.verified? == false
-        error_message = "Backspin verification failed!\n"
-        error_message += "Record: #{result.record.path}\n"
-        error_message += result.error_message || "Output verification failed"
+      raise_on_verification_failure!(result)
 
-        # Include diff if available
-        if result.diff
-          error_message += "\n\nDiff:\n#{result.diff}"
-        end
+      result
+    end
 
-        raise VerificationError.new(error_message, result: result)
-      end
+    def normalize_env(env)
+      raise ArgumentError, "env must be a Hash" unless env.is_a?(Hash)
 
-      result
+      env.empty? ? nil : env
     end
 
-    private
+    def execute_command(command, env)
+      case command
+      when String
+        env ? Open3.capture3(env, command) : Open3.capture3(command)
+      when Array
+        raise ArgumentError, "command array cannot be empty" if command.empty?
+        env ? Open3.capture3(env, *command) : Open3.capture3(*command)
+      else
+        raise ArgumentError, "command must be a String or Array"
+      end
+    end
+
+    def raise_on_verification_failure!(result)
+      return unless configuration.raise_on_verification_failure && result.verified? == false
+
+      error_message = "Backspin verification failed!\n"
+      error_message += "Record: #{result.record_path}\n"
+      details = result.error_message || result.diff
+      error_message += "\n#{details}" if details
+
+      raise VerificationError.new(error_message, result: result)
+    end
 
     def determine_mode(mode_option, record_path)
       return mode_option if mode_option && mode_option != :auto
@@ -209,5 +234,13 @@ module Backspin
       # Auto mode: record if file doesn't exist, verify if it does
       File.exist?(record_path) ? :verify : :record
     end
+
+    def validate_mode!(mode)
+      return if %i[record verify].include?(mode)
+
+      raise ArgumentError, "Playback mode is not supported" if mode == :playback
+
+      raise ArgumentError, "Unknown mode: #{mode}"
+    end
   end
 end

metadata

@@ -1,42 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Rob Sanheim
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: ostruct
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec-mocks
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3'
+dependencies: []
 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.
@@ -50,6 +22,7 @@ files:
 - ".gem_release.yml"
 - ".gitignore"
 - ".rspec"
+- ".ruby-version"
 - ".standard.yml"
 - CHANGELOG.md
 - CLAUDE.md
@@ -64,6 +37,7 @@ files:
 - bin/rake
 - bin/rspec
 - bin/setup
+- docs/backspin-result-api-sketch.md
 - examples/match_on_example.rb
 - fixtures/backspin/all_and_fields.yml
 - fixtures/backspin/all_bypass_equality.yml
@@ -121,14 +95,13 @@ files:
 - fixtures/backspin/verify_system_diff.yml
 - fixtures/backspin/version_test.yml
 - lib/backspin.rb
-- lib/backspin/command.rb
+- lib/backspin/backspin_result.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
+- lib/backspin/snapshot.rb
 - lib/backspin/version.rb
 - release.rake
 - script/lint
@@ -154,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Record and replay CLI interactions for testing
 test_files: []

data/lib/backspin/command.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "command_result"
-
-module Backspin
-  class Command
-    attr_reader :args, :result, :recorded_at, :method_class
-
-    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, result: nil, recorded_at: nil)
-      @method_class = method_class
-      @args = args
-      @recorded_at = recorded_at
-
-      # Accept either a CommandResult or individual stdout/stderr/status
-      @result = result || CommandResult.new(stdout: stdout || "", stderr: stderr || "", status: status || 0)
-    end
-
-    def stdout
-      @result.stdout
-    end
-
-    def stderr
-      @result.stderr
-    end
-
-    def status
-      @result.status
-    end
-
-    # Convert to hash for YAML serialization
-    def to_h(filter: nil)
-      data = {
-        "command_type" => @method_class.name,
-        "args" => scrub_args(@args),
-        "stdout" => Backspin.scrub_text(@result.stdout),
-        "stderr" => Backspin.scrub_text(@result.stderr),
-        "status" => @result.status,
-        "recorded_at" => @recorded_at
-      }
-
-      # Apply filter if provided
-      data = filter.call(data) if filter
-
-      data
-    end
-
-    # Create from hash (for loading from YAML)
-    def self.from_h(data)
-      # Determine method class from command_type
-      method_class = case data["command_type"]
-      when "Open3::Capture3"
-        Open3::Capture3
-      when "Kernel::System"
-        ::Kernel::System
-      when "Backspin::Capturer"
-        Backspin::Capturer
-      else
-        # Default to capture3 for backwards compatibility
-        Open3::Capture3
-      end
-
-      new(
-        method_class: method_class,
-        args: data["args"],
-        stdout: data["stdout"],
-        stderr: data["stderr"],
-        status: data["status"],
-        recorded_at: data["recorded_at"]
-      )
-    end
-
-    private
-
-    def scrub_args(args)
-      return args unless Backspin.configuration.scrub_credentials && args
-
-      args.map do |arg|
-        case arg
-        when String
-          Backspin.scrub_text(arg)
-        when Array
-          scrub_args(arg)
-        when Hash
-          arg.transform_values { |v| v.is_a?(String) ? Backspin.scrub_text(v) : v }
-        else
-          arg
-        end
-      end
-    end
-  end
-end
-
-# Define the Open3::Capture3 class for identification
-module Open3
-  class Capture3; end
-end
-
-# Define the Kernel::System class for identification
-module ::Kernel
-  class System; end
-end
-
-# Define the Backspin::Capturer class for identification
-module Backspin
-  class Capturer; end
-end

data/lib/backspin/command_result.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Backspin
-  # Represents the result of executing a command
-  # Stores stdout, stderr, and exit status
-  class CommandResult
-    attr_reader :stdout, :stderr, :status
-
-    def initialize(stdout:, stderr:, status:)
-      @stdout = stdout
-      @stderr = stderr
-      @status = normalize_status(status)
-    end
-
-    # @return [Boolean] true if the command succeeded (exit status 0)
-    def success?
-      status.zero?
-    end
-
-    # @return [Boolean] true if the command failed (non-zero exit status)
-    def failure?
-      !success?
-    end
-
-    # @return [Hash] Hash representation of the result
-    def to_h
-      {
-        "stdout" => stdout,
-        "stderr" => stderr,
-        "status" => status
-      }
-    end
-
-    # Compare two results for equality
-    def ==(other)
-      return false unless other.is_a?(CommandResult)
-
-      stdout == other.stdout && stderr == other.stderr && status == other.status
-    end
-
-    def inspect
-      "#<Backspin::CommandResult status=#{status} stdout=#{stdout} stderr=#{stderr}>"
-    end
-
-    private
-
-    def normalize_status(status)
-      case status
-      when Integer
-        status
-      when Process::Status
-        status.exitstatus
-      else
-        status.respond_to?(:exitstatus) ? status.exitstatus : status.to_i
-      end
-    end
-  end
-end