backspin 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f44a53c1983fd41c2660bc9652c158b2193e880e0e1339fa49c882d26fdd0852
-  data.tar.gz: 3b53d9ba92db35ad66c128bc049762e06c307472827fe2d4b795427c7e668bdf
+  metadata.gz: 055d320685da2ca9e280c3aa8bcb15edb101d788c4d8c4df8ff203d4c2c34dac
+  data.tar.gz: cf21c90a588ff5590844ae2a9c50a78707a5c71d44b43ad0d3a571fed0bbe4b5
 SHA512:
-  metadata.gz: 28909c63f9befbe8a0ae208328b9c527b3f1ca28417a66e96afad6ee9be41c2fa157ede63e4c5073f049ac59ab9c336a5fde7b97e109b7efc61480942ddc1a58
-  data.tar.gz: e63c8c4fff6ac690575ffadfe48efd6b4d0bc2267680e1c99637a888edcf3034bb315d96efedc400bfabdf5f8a9aa7912dfef03771b86a6a69769efe1bdcaac6
+  metadata.gz: 7c3a0941042e885d5370c4287fdd88323bc1b95d15a7c795afde0d08aa5efe050f7e54838a5774de967d4d633b9e30df82b5700d17c431fa8ea1cce79777bee9
+  data.tar.gz: 86584a95060fda843934065c2d9a3ca59acd12a1e21f70dcf3d9bd648f4cd1cec97ff21a57f98f8aa7a133865ccbb38438bdb05402f19e8292bed02c56d51bfe

data/.gem_release.yml

@@ -0,0 +1,13 @@
+# Configuration for gem-release
+bump:
+  commit: true
+  message: "Bump version to %{version}"
+  skip_ci: false
+  push: true
+
+tag:
+  tag: v%{version}
+  sign: false
+
+release:
+  host: https://rubygems.org

data/CHANGELOG.md

@@ -1,21 +1,19 @@
 # Changelog
 
-## [0.4.0] - 2025-06-06
+## 0.4.0 - 2025-06-06
 
 Simpler, unified API: `Backspin.run` and `Backspin run!` methods that automatically record on first use and verify on subsequent runs. `run!` will raise an error if results differ, whereas `run` will return the result for the caller to decide what to do with
 
-## [0.3.0] - 2025-06-05
+## 0.3.0 - 2025-06-05
 - Scrub credentials from command arguments
 
-## [0.2.0] - 2025-06-05
+## 0.2.0 - 2025-06-05
 - First public release of Backspin, extracteed from `name-TBD` CLI tool
 
-## [0.2.1] - 2025-06-04
+## 0.2.1 - 2025-06-04
 - major refactoring, add support for `system` calls
 
-## [0.1.0] - 2025-06-02
-
-### Added
+## 0.1.0 - 2025-06-02
 - Initial (internal) release of Backspin
 - `record` method to capture CLI command outputs
 - `verify` and `verify!` methods for output verification

data/CLAUDE.md

@@ -29,9 +29,13 @@ bin/rake release     # Release to RubyGems (updates version, tags, pushes)
 
 ### Code Quality
 ```bash
-bin/rake standard               # Run Standard Ruby linter
+script/lint                      # Run Standard Ruby linter
+script/lint --fix                # Auto-fix linting issues
+bin/rake standard                # Alternative: Run via Rake task
 ```
 
+**Important**: Always use `standardrb` for linting, never use `rubocop` directly. The project uses Standard Ruby for consistent code style.
+
 ## Architecture
 
 ### Core Components

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in backspin.gemspec
@@ -6,6 +8,6 @@ gemspec
 group :development do
   gem "rake", "~> 13.0"
   gem "rspec", "~> 3.0"
-  gem "timecop", "~> 0.9"
   gem "standard"
+  gem "timecop", "~> 0.9"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.4.1)
+    backspin (0.4.2)
       ostruct (~> 0.5.0)
       rspec-mocks (~> 3.0)
 
@@ -10,6 +10,7 @@ GEM
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
+    gem-release (2.2.4)
     json (2.12.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
@@ -78,6 +79,7 @@ PLATFORMS
 
 DEPENDENCIES
   backspin!
+  gem-release (~> 2.2)
   rake (~> 13.0)
   rspec (~> 3.0)
   standard

data/MATCH_ON_USAGE.md

@@ -0,0 +1,110 @@
+# Using match_on for Field-Specific Verification
+
+The `match_on` option allows you to use custom matchers for specific fields while maintaining exact equality checks for all other fields. This is useful when dealing with dynamic content like timestamps, process IDs, or version numbers.
+
+## Basic Usage
+
+### Single Field Matcher
+
+```ruby
+# Record a command with a timestamp
+Backspin.run("timestamp_test") do
+  Open3.capture3("date")
+end
+
+# Verify with a custom matcher for stdout
+result = Backspin.run("timestamp_test",
+  match_on: [:stdout, ->(recorded, actual) {
+    # Both should contain a day of the week
+    recorded.match?(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/) &&
+    actual.match?(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/)
+  }]) do
+  Open3.capture3("date")
+end
+```
+
+### Multiple Field Matchers
+
+```ruby
+# Match different fields with different rules
+result = Backspin.run("multi_field_test",
+  match_on: [
+    [:stdout, ->(recorded, actual) {
+      # Match process ID format
+      recorded.match?(/PID: \d+/) && actual.match?(/PID: \d+/)
+    }],
+    [:stderr, ->(recorded, actual) {
+      # Match error type, ignore details
+      recorded.include?("Error:") && actual.include?("Error:")
+    }]
+  ]) do
+  Open3.capture3("./my_script.sh")
+end
+```
+
+## Matcher Format
+
+The `match_on` option accepts two formats:
+
+1. **Single field**: `[:field_name, matcher_proc]`
+2. **Multiple fields**: `[[:field1, matcher1], [:field2, matcher2], ...]`
+
+Valid field names are:
+- `:stdout` - Standard output
+- `:stderr` - Standard error
+- `:status` - Exit status code
+
+## Matcher Proc
+
+The matcher proc receives two arguments:
+- `recorded_value` - The value from the saved recording
+- `actual_value` - The value from the current execution
+
+It should return `true` if the values match according to your criteria, `false` otherwise.
+
+## Examples
+
+### Matching Version Numbers
+
+```ruby
+# Match major version only
+match_on: [:stdout, ->(recorded, actual) {
+  recorded.match(/Version: (\d+)\./) && 
+  actual.match(/Version: (\d+)\./) &&
+  $1 == $1  # Major versions match
+}]
+```
+
+### Ignoring Timestamps
+
+```ruby
+# Match log format but ignore timestamp
+match_on: [:stdout, ->(recorded, actual) {
+  # Remove timestamps before comparing
+  recorded.gsub(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/, '') ==
+  actual.gsub(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/, '')
+}]
+```
+
+### Handling Dynamic IDs
+
+```ruby
+# Match API response structure, ignore dynamic IDs
+match_on: [:stdout, ->(recorded, actual) {
+  recorded_json = JSON.parse(recorded)
+  actual_json = JSON.parse(actual)
+  
+  # Compare structure, not values
+  recorded_json.keys.sort == actual_json.keys.sort
+}]
+```
+
+## Important Notes
+
+1. **Other fields must match exactly**: When using `match_on`, all fields not specified in the matcher list must match exactly. If stdout has a custom matcher but stderr doesn't, stderr must be identical to pass verification.
+
+2. **Precedence**: If both `matcher` and `match_on` options are provided, `matcher` takes precedence (for backward compatibility).
+
+3. **Error messages**: When verification fails with `match_on`, the error will indicate which fields failed and whether they failed exact matching or custom matching.
+
+4. **Works with run!**: The `match_on` option works with both `run` and `run!` methods.

data/Rakefile

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "standard/rake"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: [:spec, :standard]
+task default: %i[spec standard]
+
+load "release.rake" if File.exist?("release.rake")

data/backspin.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "lib/backspin/version"
 
 Gem::Specification.new do |spec|
@@ -16,14 +18,15 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rspec-mocks", "~> 3.0"
   spec.add_dependency "ostruct", "~> 0.5.0"
+  spec.add_dependency "rspec-mocks", "~> 3.0"
+
+  spec.add_development_dependency "gem-release", "~> 2.2"
 end

data/examples/match_on_example.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/inline"
+require "open3"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "backspin", path: ".."
+end
+
+# Example 1: Single field matcher
+puts "Example 1: Matching timestamps with custom matcher"
+puts "-" * 50
+
+# First run: Record the output
+result = Backspin.run("timestamp_example") do
+  Open3.capture3("date '+%Y-%m-%d %H:%M:%S'")
+end
+puts "Recorded: #{result.stdout.chomp}"
+
+# Sleep to ensure different timestamp
+sleep 1
+
+# Second run: Verify with custom matcher
+result = Backspin.run("timestamp_example",
+  match_on: [:stdout, lambda { |recorded, actual|
+    # Both should have the same date format
+    recorded.match?(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/) &&
+    actual.match?(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/)
+  }]) do
+  Open3.capture3("date '+%Y-%m-%d %H:%M:%S'")
+end
+
+puts "Current:  #{result.stdout.chomp}"
+puts "Verified: #{result.verified?}"
+puts
+
+# Example 2: Multiple field matchers
+puts "Example 2: Matching multiple fields with different patterns"
+puts "-" * 50
+
+# Record a command with dynamic content
+Backspin.run("multi_field_example") do
+  script = <<~BASH
+    echo "PID: $$"
+    echo "Error: Timeout at $(date '+%H:%M:%S')" >&2
+    exit 1
+  BASH
+  Open3.capture3("bash", "-c", script)
+end
+
+# Verify with different PID and timestamp
+result = Backspin.run("multi_field_example",
+  match_on: [
+    [:stdout, lambda { |recorded, actual|
+      # Both should have PID format
+      recorded.match?(/PID: \d+/) && actual.match?(/PID: \d+/)
+    }],
+    [:stderr, lambda { |recorded, actual|
+      # Both should have timeout error, ignore timestamp
+      recorded.match?(/Error: Timeout at/) && actual.match?(/Error: Timeout at/)
+    }]
+  ]) do
+  script = <<~BASH
+    echo "PID: $$"
+    echo "Error: Timeout at $(date '+%H:%M:%S')" >&2
+    exit 1
+  BASH
+  Open3.capture3("bash", "-c", script)
+end
+
+puts "Stdout:   #{result.stdout.chomp}"
+puts "Stderr:   #{result.stderr.chomp}"
+puts "Status:   #{result.status}"
+puts "Verified: #{result.verified?}"
+puts
+
+# Example 3: Mixed matching - some fields exact, some custom
+puts "Example 3: Mixed field matching"
+puts "-" * 50
+
+# Record with specific values
+Backspin.run("mixed_matching") do
+  script = <<~BASH
+    echo "Version: 1.2.3"
+    echo "Build: $(date +%s)"
+    echo "Status: OK"
+  BASH
+  Open3.capture3("bash", "-c", script)
+end
+
+# Verify - stdout uses custom matcher, stderr must match exactly
+result = Backspin.run("mixed_matching",
+  match_on: [:stdout, lambda { |recorded, actual|
+    # Version and Status must match, Build can differ
+    recorded_lines = recorded.lines
+    actual_lines = actual.lines
+
+    recorded_lines[0] == actual_lines[0] && # Version line must match
+    recorded_lines[1].start_with?("Build:") && actual_lines[1].start_with?("Build:") && # Build line format
+    recorded_lines[2] == actual_lines[2] # Status line must match
+  }]) do
+  script = <<~BASH
+    echo "Version: 1.2.3"
+    echo "Build: $(date +%s)"
+    echo "Status: OK"
+  BASH
+  Open3.capture3("bash", "-c", script)
+end
+
+puts "Output:\n#{result.stdout}"
+puts "Verified: #{result.verified?}"
+
+# Cleanup
+FileUtils.rm_rf("fixtures/backspin")

data/fixtures/backspin/all_and_fields.yml

@@ -0,0 +1,15 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,17 @@
+---
+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

@@ -0,0 +1,13 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - date
+  stdout: 'Tue Jun 10 22:50:14 CDT 2025
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/all_matcher_basic.yml

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,17 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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_no_short_circuit.yml

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,17 @@
+---
+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

@@ -0,0 +1,17 @@
+---
+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

@@ -0,0 +1,17 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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

@@ -0,0 +1,14 @@
+---
+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/field_matcher_demo.yml

@@ -0,0 +1,17 @@
+---
+first_recorded_at: '2025-06-10T11:02:02-05:00'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - sh
+  - "-c"
+  - echo 'output'; echo 'error' >&2; exit 42
+  stdout: 'output
+
+    '
+  stderr: 'error
+
+    '
+  status: 42
+  recorded_at: '2025-06-10T11:02:02-05:00'

data/fixtures/backspin/field_matcher_values.yml

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