backspin 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59bc6e711951434fc84dd2c2694f69aa5b00ef3bf878b81c5b4e97beeb430ad6
-  data.tar.gz: f9784962ef86ad73e0eb1c8388217700e477bc60ce0528b5dd16f08bc5c2f637
+  metadata.gz: 055d320685da2ca9e280c3aa8bcb15edb101d788c4d8c4df8ff203d4c2c34dac
+  data.tar.gz: cf21c90a588ff5590844ae2a9c50a78707a5c71d44b43ad0d3a571fed0bbe4b5
 SHA512:
-  metadata.gz: e4151f4a28909e1a80706a30520b268f5114124230df9869a3603d5502194f4885ca8dff19e15a9a8ffe5f559b14695614f9f113c66e82ccc105de5b7ae17006
-  data.tar.gz: a66f71d1a4b2e9404ca39178920d8b88686f5e8cec2fe62f282b1cda9de031c1041cdfa1007ee9dc725c24cfb1c4dad5445213091a20c0faf23165705a8d264e
+  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
@@ -62,7 +66,7 @@ bin/rake standard               # Run Standard Ruby linter
 ### Testing Approach
 
 - Integration-focused tests that exercise the full stack
-- Default record directory is `spec/backspin_data` (can be configured)
+- Default record directory is `fixtures/backspin` (can be configured)
 - Tests use real shell commands (`echo`, `date`, etc.)
 - Configuration is reset between tests to avoid side effects
 - **Important**: Backspin specs MUST be as local and un-DRY as possible. Each spec should be self-contained with its own setup, expectations, and cleanup if needed. Avoid shared contexts or helpers that hide important test details.
@@ -76,7 +80,7 @@ bin/rake standard               # Run Standard Ruby linter
 4. Run tests with `rake spec`
 
 ### Debugging Tests
-- Records are saved to `spec/backspin_data/` by default
+- Records are saved to `fixtures/backspin/` by default
 - Check YAML files to see recorded command outputs
 
 ### Updating Credential Patterns

data/CONTRIBUTING.md

@@ -99,7 +99,7 @@ Backspin is a Ruby gem for characterization testing of command-line interfaces.
 
 #### Debugging Tests
 
-- Records are saved to `spec/backspin_data/` by default
+- Records are saved to `fixtures/backspin/` by default
 - Check YAML files to see recorded command outputs
 
 ## Testing
@@ -125,7 +125,7 @@ Backspin uses integration-focused tests that exercise the full stack. When writi
 - Avoid shared contexts or helpers that hide important test details
 - Use real shell commands (`echo`, `date`, etc.) for testing
 - Ensure configuration is reset between tests to avoid side effects
-- Verify new or updated test records in `spec/backspin_data/`
+- Verify new or updated test records in `fixtures/backspin/`
 
 Example test structure:
 

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.0)
+    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/README.md

@@ -1,4 +1,9 @@
-# Backspin   [![Gem Version](https://badge.fury.io/rb/backspin.svg)](https://badge.fury.io/rb/backspin) [![CircleCI](https://dl.circleci.com/status-badge/img/gh/rsanheim/backspin/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/rsanheim/backspin/tree/main)
+# Backspin 
+
+[![Ruby](https://img.shields.io/badge/ruby-%23CC342D.svg?style=flat&logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Gem Version](https://img.shields.io/gem/v/backspin)](https://rubygems.org/gems/backspin)
+[![CircleCI](https://img.shields.io/circleci/build/github/rsanheim/backspin/main)](https://circleci.com/gh/rsanheim/backspin)
+[![Last Commit](https://img.shields.io/github/last-commit/rsanheim/backspin/main)](https://github.com/rsanheim/backspin/commits/main)
 
 Backspin records and replays CLI interactions in Ruby for easy snapshot testing of command-line interfaces. Currently supports `Open3.capture3` and `system` and requires `rspec-mocks`.  More system calls and test integrations are welcome - send a PR!
 
@@ -62,7 +67,7 @@ end
 result = Backspin.run("echo_test", mode: :record) do
   Open3.capture3("echo hello")
 end
-# This will save the output to `spec/backspin_data/echo_test.yml`.
+# This will save the output to `fixtures/backspin/echo_test.yml`.
 
 # Explicit verify mode: Always verify against existing recording
 result = Backspin.run("echo_test", mode: :verify) do

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_mode_filter.yml

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

@@ -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'