backspin 0.9.0 → 0.11.0

data/lib/backspin/snapshot.rb

@@ -7,12 +7,13 @@ module Backspin
 
     def initialize(command_type:, args:, env: nil, stdout: "", stderr: "", status: 0, recorded_at: nil)
       @command_type = command_type
-      @args = args
-      @env = env
-      @stdout = stdout || ""
-      @stderr = stderr || ""
+      @args = sanitize_args(args)
+      @env = env.nil? ? nil : sanitize_env(env)
+      @stdout = Backspin.scrub_text((stdout || "").dup).freeze
+      @stderr = Backspin.scrub_text((stderr || "").dup).freeze
       @status = status || 0
-      @recorded_at = recorded_at
+      @recorded_at = recorded_at.nil? ? nil : recorded_at.dup.freeze
+      @serialized_hash = build_serialized_hash
     end
 
     def success?
@@ -23,20 +24,8 @@ module Backspin
       !success?
     end
 
-    def to_h(filter: nil)
-      data = {
-        "command_type" => command_type.name,
-        "args" => scrub_args(args),
-        "stdout" => Backspin.scrub_text(stdout),
-        "stderr" => Backspin.scrub_text(stderr),
-        "status" => status,
-        "recorded_at" => recorded_at
-      }
-
-      data["env"] = scrub_env(env) if env
-      data = filter.call(data) if filter
-
-      data
+    def to_h
+      @serialized_hash
     end
 
     def self.from_h(data)
@@ -62,6 +51,19 @@ module Backspin
 
     private
 
+    def build_serialized_hash
+      data = {
+        "command_type" => command_type.name,
+        "args" => args,
+        "stdout" => stdout,
+        "stderr" => stderr,
+        "status" => status,
+        "recorded_at" => recorded_at
+      }
+      data["env"] = env if env
+      deep_freeze(data)
+    end
+
     def scrub_args(value)
       return value unless Backspin.configuration.scrub_credentials && value
 
@@ -82,6 +84,37 @@ module Backspin
 
       value.transform_values { |entry| entry.is_a?(String) ? Backspin.scrub_text(entry) : entry }
     end
+
+    def sanitize_args(value)
+      deep_freeze(scrub_args(deep_dup(value)))
+    end
+
+    def sanitize_env(value)
+      deep_freeze(scrub_env(deep_dup(value)))
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each_value { |v| deep_freeze(v) }
+      when Array
+        value.each { |v| deep_freeze(v) }
+      end
+      value.freeze
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |entry| deep_dup(entry) }
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
   end
 end
 

data/lib/backspin/version.rb

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

data/lib/backspin.rb

@@ -71,19 +71,30 @@ module Backspin
     # @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
+    # @param filter [Proc] Custom filter for recorded data/canonicalization
+    # @param filter_on [Symbol] Filter application mode - :both (default), :record
     # @return [BackspinResult] Aggregate result for this run
-    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, &block)
+    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
+      validate_filter_on!(filter_on)
+
       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)
+        return perform_capture(name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
       end
 
       raise ArgumentError, "command is required" if command.nil?
 
-      perform_command_run(command, name: name, env: env, mode: mode, matcher: matcher, filter: filter)
+      perform_command_run(
+        command,
+        name: name,
+        env: env,
+        mode: mode,
+        matcher: matcher,
+        filter: filter,
+        filter_on: filter_on
+      )
     end
 
     # Captures all stdout/stderr output from a block
@@ -91,29 +102,27 @@ module Backspin
     # @param record_name [String] Name for the record file
     # @param mode [Symbol] Recording mode - :auto, :record, :verify
     # @param matcher [Proc, Hash] Custom matcher for verification
-    # @param filter [Proc] Custom filter for recorded data
+    # @param filter [Proc] Custom filter for recorded data/canonicalization
+    # @param filter_on [Symbol] Filter application mode - :both (default), :record
     # @return [BackspinResult] Aggregate result for this run
-    def capture(record_name, mode: :auto, matcher: nil, filter: nil, &block)
+    def capture(record_name, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
       raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
       raise ArgumentError, "block is required" unless block_given?
+      validate_filter_on!(filter_on)
 
-      perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, &block)
+      perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
     end
 
     private
 
-    def perform_capture(record_name, mode:, matcher:, filter:, &block)
+    def perform_capture(record_name, mode:, matcher:, filter:, filter_on:, &block)
       record_path = Record.build_record_path(record_name)
       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)
+      recorder = Recorder.new(record: record, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on)
 
       result = case mode
       when :record
@@ -129,16 +138,12 @@ module Backspin
       result
     end
 
-    def perform_command_run(command, name:, env:, mode:, matcher:, filter:)
+    def perform_command_run(command, name:, env:, mode:, matcher:, filter:, filter_on:)
       record_path = Record.build_record_path(name)
       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)
 
@@ -180,7 +185,13 @@ module Backspin
           stderr: stderr,
           status: status.exitstatus
         )
-        command_diff = CommandDiff.new(expected: expected_snapshot, actual: actual_snapshot, matcher: matcher)
+        command_diff = CommandDiff.new(
+          expected: expected_snapshot,
+          actual: actual_snapshot,
+          matcher: matcher,
+          filter: filter,
+          filter_on: filter_on
+        )
         BackspinResult.new(
           mode: :verify,
           record_path: record.path,
@@ -242,5 +253,11 @@ module Backspin
 
       raise ArgumentError, "Unknown mode: #{mode}"
     end
+
+    def validate_filter_on!(filter_on)
+      return if %i[both record].include?(filter_on)
+
+      raise ArgumentError, "Unknown filter_on: #{filter_on}. Must be :both or :record"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -39,61 +39,7 @@ 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
 - lib/backspin.rb
 - lib/backspin/backspin_result.rb
 - lib/backspin/command_diff.rb

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'