backspin 0.10.0 → 0.12.0

data/lib/backspin/record.rb

@@ -4,8 +4,9 @@ module Backspin
   class RecordFormatError < StandardError; end
 
   class Record
-    FORMAT_VERSION = "4.0"
-    attr_reader :path, :snapshot, :recorded_at
+    FORMAT_VERSION = "4.1"
+    SUPPORTED_FORMAT_VERSIONS = ["4.0", FORMAT_VERSION].freeze
+    attr_reader :path, :snapshot, :first_recorded_at, :recorded_at, :record_count
 
     def self.load_or_create(path)
       record = new(path)
@@ -36,12 +37,16 @@ module Backspin
     def initialize(path)
       @path = path
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
     end
 
     def set_snapshot(snapshot)
       @snapshot = snapshot
-      @recorded_at ||= snapshot.recorded_at
+      snapshot_recorded_at = snapshot.recorded_at || Time.now.iso8601
+      @first_recorded_at ||= snapshot_recorded_at
+      @recorded_at = snapshot_recorded_at
       self
     end
 
@@ -49,17 +54,23 @@ module Backspin
       FileUtils.mkdir_p(File.dirname(@path))
       snapshot_data = @snapshot&.to_h
       snapshot_data = filter.call(deep_dup(snapshot_data)) if snapshot_data && filter
+      next_record_count = (@record_count || 0) + 1
       record_data = {
         "format_version" => FORMAT_VERSION,
+        "first_recorded_at" => @first_recorded_at,
         "recorded_at" => @recorded_at,
+        "record_count" => next_record_count,
         "snapshot" => snapshot_data
       }
       File.write(@path, record_data.to_yaml)
+      @record_count = next_record_count
     end
 
     def reload
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
       load_from_file if File.exist?(@path)
     end
 
@@ -73,13 +84,15 @@ module Backspin
 
     def clear
       @snapshot = nil
+      @first_recorded_at = nil
       @recorded_at = nil
+      @record_count = nil
     end
 
     def load_from_file
       data = YAML.load_file(@path.to_s)
 
-      unless data.is_a?(Hash) && data["format_version"] == FORMAT_VERSION
+      unless data.is_a?(Hash) && SUPPORTED_FORMAT_VERSIONS.include?(data["format_version"])
         raise RecordFormatError, "Invalid record format: expected format version #{FORMAT_VERSION}"
       end
 
@@ -88,7 +101,17 @@ module Backspin
         raise RecordFormatError, "Invalid record format: missing snapshot"
       end
 
-      @recorded_at = data["recorded_at"]
+      format_version = data["format_version"]
+      @recorded_at = data["recorded_at"] || snapshot_data["recorded_at"]
+      if format_version == FORMAT_VERSION
+        @first_recorded_at = data["first_recorded_at"]
+        @record_count = data["record_count"]
+      else
+        # Backfill metadata for v4.0 records.
+        @first_recorded_at = data["first_recorded_at"] || @recorded_at
+        @record_count = data.fetch("record_count", 1)
+      end
+      validate_metadata!
       @snapshot = Snapshot.from_h(snapshot_data)
     rescue Psych::SyntaxError => e
       raise RecordFormatError, "Invalid record format: #{e.message}"
@@ -96,6 +119,20 @@ module Backspin
 
     private
 
+    def validate_metadata!
+      unless @first_recorded_at.is_a?(String) && !@first_recorded_at.empty?
+        raise RecordFormatError, "Invalid record format: missing first_recorded_at"
+      end
+
+      unless @recorded_at.is_a?(String) && !@recorded_at.empty?
+        raise RecordFormatError, "Invalid record format: missing recorded_at"
+      end
+
+      unless @record_count.is_a?(Integer) && @record_count.positive?
+        raise RecordFormatError, "Invalid record format: record_count must be a positive integer"
+      end
+    end
+
     def deep_dup(value)
       case value
       when Hash

data/lib/backspin/version.rb

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

data/lib/backspin.rb

@@ -14,6 +14,8 @@ require "backspin/backspin_result"
 require "backspin/recorder"
 
 module Backspin
+  VALID_MODES = %i[auto record verify].freeze
+
   class RecordNotFoundError < StandardError; end
 
   class VerificationError < StandardError
@@ -120,11 +122,7 @@ module Backspin
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
 
-      record = if mode == :record
-        Record.create(record_name)
-      else
-        Record.load_or_create(record_path)
-      end
+      record = Record.load_or_create(record_path)
 
       recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on)
 
@@ -147,11 +145,7 @@ module Backspin
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
 
-      record = if mode == :record
-        Record.create(name)
-      else
-        Record.load_or_create(record_path)
-      end
+      record = Record.load_or_create(record_path)
 
       normalized_env = env.nil? ? nil : normalize_env(env)
 
@@ -250,8 +244,26 @@ module Backspin
     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
+      env_mode = mode_from_env
+      if env_mode && env_mode != :auto
+        configuration.logger&.debug { "event=mode_resolved mode=#{env_mode} source=env record=#{record_path}" }
+        return env_mode
+      end
+
+      resolved = File.exist?(record_path) ? :verify : :record
+      configuration.logger&.debug { "event=mode_resolved mode=#{resolved} source=auto record=#{record_path}" }
+      resolved
+    end
+
+    def mode_from_env
+      raw = ENV["BACKSPIN_MODE"]
+      return if raw.nil? || raw.strip.empty?
+
+      mode = raw.strip.downcase.to_sym
+      return mode if VALID_MODES.include?(mode)
+
+      raise ArgumentError,
+        "Invalid BACKSPIN_MODE value: #{raw.inspect}. Allowed values: auto, record, verify"
     end
 
     def validate_mode!(mode)

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.0"

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Rob Sanheim
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  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'
 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.
@@ -39,61 +53,26 @@ files:
 - 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
-- fixtures/backspin/all_checks_equality.yml
-- fixtures/backspin/all_for_logging.yml
-- fixtures/backspin/all_matcher_basic.yml
-- fixtures/backspin/all_matcher_custom.yml
-- fixtures/backspin/all_matcher_demo.yml
-- fixtures/backspin/all_matcher_test.yml
-- fixtures/backspin/all_mode_filter.yml
-- fixtures/backspin/all_no_short_circuit.yml
-- fixtures/backspin/all_pass_field_fail.yml
-- fixtures/backspin/all_short_circuit.yml
-- fixtures/backspin/all_skips_equality.yml
-- fixtures/backspin/all_with_equality.yml
-- fixtures/backspin/all_with_fields.yml
-- fixtures/backspin/combined_fail_demo.yml
-- fixtures/backspin/combined_matcher_demo.yml
-- fixtures/backspin/credential_filter.yml
-- fixtures/backspin/echo_hello.yml
-- fixtures/backspin/echo_verify.yml
-- fixtures/backspin/episodes_filter.yml
-- fixtures/backspin/failure_test.yml
-- fixtures/backspin/field_matcher_demo.yml
-- fixtures/backspin/field_matcher_values.yml
-- fixtures/backspin/full_data_filter.yml
-- fixtures/backspin/key_confusion_test.yml
-- fixtures/backspin/match_on_any_fail.yml
-- fixtures/backspin/match_on_bad_format.yml
-- fixtures/backspin/match_on_fail.yml
-- fixtures/backspin/match_on_invalid.yml
-- fixtures/backspin/match_on_multiple.yml
-- fixtures/backspin/match_on_nil.yml
-- fixtures/backspin/match_on_other_fields.yml
-- fixtures/backspin/match_on_run_bang.yml
-- fixtures/backspin/match_on_run_bang_fail.yml
-- fixtures/backspin/match_on_single.yml
-- fixtures/backspin/mixed_calls.yml
-- fixtures/backspin/multi_command.yml
-- fixtures/backspin/multi_command_filter.yml
-- fixtures/backspin/multi_field_filter.yml
-- fixtures/backspin/multi_system.yml
-- fixtures/backspin/nil_filter.yml
-- fixtures/backspin/none_mode_test.yml
-- fixtures/backspin/path_test.yml
-- fixtures/backspin/playback_system.yml
-- fixtures/backspin/playback_test.yml
-- fixtures/backspin/stderr_test.yml
-- fixtures/backspin/strict_test.yml
-- fixtures/backspin/string_symbol_test.yml
-- fixtures/backspin/system_echo.yml
-- fixtures/backspin/system_false.yml
-- fixtures/backspin/timestamp_test.yml
-- fixtures/backspin/verify_system.yml
-- fixtures/backspin/verify_system_diff.yml
-- fixtures/backspin/version_test.yml
+- fixtures/backspin/.gitkeep
+- fixtures/projects/dummy_cli_gem/.rspec
+- fixtures/projects/dummy_cli_gem/Gemfile
+- fixtures/projects/dummy_cli_gem/Gemfile.lock
+- fixtures/projects/dummy_cli_gem/LICENSE.txt
+- fixtures/projects/dummy_cli_gem/README.md
+- fixtures/projects/dummy_cli_gem/Rakefile
+- fixtures/projects/dummy_cli_gem/dummy_cli_gem.gemspec
+- fixtures/projects/dummy_cli_gem/exe/dummy_cli_gem
+- fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_echo.yml
+- fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_ls.yml
+- fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem.rb
+- fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/cli.rb
+- fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/version.rb
+- fixtures/projects/dummy_cli_gem/mise.toml
+- fixtures/projects/dummy_cli_gem/spec/dummy_cli_gem_backspin_spec.rb
+- fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_echo.yml
+- fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_ls.yml
+- fixtures/projects/dummy_cli_gem/spec/fixtures/listing_target/alpha.txt
+- fixtures/projects/dummy_cli_gem/spec/spec_helper.rb
 - lib/backspin.rb
 - lib/backspin/backspin_result.rb
 - lib/backspin/command_diff.rb
@@ -103,6 +82,7 @@ files:
 - lib/backspin/recorder.rb
 - lib/backspin/snapshot.rb
 - lib/backspin/version.rb
+- mise.toml
 - release.rake
 - script/lint
 - script/run_affected_tests

data/fixtures/backspin/all_and_fields.yml

@@ -1,15 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:27:40-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'valid'; exit 0
-  stdout: 'valid
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:27:40-05:00'

data/fixtures/backspin/all_bypass_equality.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:03-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - first output
-  stdout: 'first output
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:03-05:00'

data/fixtures/backspin/all_checks_equality.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'original'; echo 'original error' >&2
-  stdout: 'original
-
-    '
-  stderr: 'original error
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_for_logging.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - 'test output with : colons'
-  stdout: 'test output with : colons
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_basic.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello world
-  stdout: 'hello world
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_custom.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - 'echo ''PASS: test 1''; echo ''WARNING: minor issue'' >&2'
-  stdout: 'PASS: test 1
-
-    '
-  stderr: 'WARNING: minor issue
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_demo.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:02-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:02-05:00'

data/fixtures/backspin/all_matcher_test.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:00:57-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:00:57-05:00'

data/fixtures/backspin/all_mode_filter.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - "'second'"
-  stdout: 'filtered output 2
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_no_short_circuit.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:27:40-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:27:40-05:00'

data/fixtures/backspin/all_pass_field_fail.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello
-  stdout: 'hello
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_short_circuit.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_skips_equality.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'original'; echo 'original error' >&2
-  stdout: 'original
-
-    '
-  stderr: 'original error
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_with_equality.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:27:40-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'output1'; echo 'error1' >&2
-  stdout: 'output1
-
-    '
-  stderr: 'error1
-
-    '
-  status: 0
-  recorded_at: '2025-06-10T11:27:40-05:00'

data/fixtures/backspin/all_with_fields.yml

@@ -1,17 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - sh
-  - "-c"
-  - echo 'output'; echo 'error' >&2
-  stdout: 'output
-
-    '
-  stderr: 'error
-
-    '
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/combined_fail_demo.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:03-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:03-05:00'

data/fixtures/backspin/combined_matcher_demo.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-06-10T11:02:03-05:00'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - test
-  stdout: 'test
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-06-10T11:02:03-05:00'

data/fixtures/backspin/credential_filter.yml

@@ -1,18 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - "'My"
-  - API
-  - key
-  - is
-  - "********************'"
-  stdout: 'MY API KEY IS ********************
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/echo_hello.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello
-  stdout: 'hello
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/echo_verify.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - hello
-  stdout: 'hello
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/episodes_filter.yml

@@ -1,26 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - "'episode"
-  - 1'
-  stdout: 'EPISODE 1
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - "'episode"
-  - 2'
-  stdout: 'EPISODE 2
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/failure_test.yml

@@ -1,14 +0,0 @@
----
-first_recorded_at: '2025-05-01T12:00:00Z'
-format_version: '2.0'
-commands:
-- command_type: Open3::Capture3
-  args:
-  - echo
-  - expected
-  stdout: 'expected
-
-    '
-  stderr: ''
-  status: 0
-  recorded_at: '2025-05-01T12:00:00Z'