backspin 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9afcbf90256cbfd84f6b9694544282dc593fc715d9886a9e3a9ba54e064410fc
-  data.tar.gz: c3d6e95547f27364b4108b5f75641ed88a9e153f0e4ccdbed3d276e82dd5f99b
+  metadata.gz: f44a53c1983fd41c2660bc9652c158b2193e880e0e1339fa49c882d26fdd0852
+  data.tar.gz: 3b53d9ba92db35ad66c128bc049762e06c307472827fe2d4b795427c7e668bdf
 SHA512:
-  metadata.gz: 2c7c36cee5518f0944896c04c96d36ae134d56928510ee01aef646a2eb0c036c723ab65aff64c6726751ce6b4c406de90f486e4da5bd3242344fd23d8e7792f1
-  data.tar.gz: 116e28fadefdc8651f648f25f0da4c347d86127448a34e0ca20a244f6bb0e7f101e140052e0f0e9029ec1693b40b6363ab3d7db6a0b7c2a0ab9252976ae64c33
+  metadata.gz: 28909c63f9befbe8a0ae208328b9c527b3f1ca28417a66e96afad6ee9be41c2fa157ede63e4c5073f049ac59ab9c336a5fde7b97e109b7efc61480942ddc1a58
+  data.tar.gz: e63c8c4fff6ac690575ffadfe48efd6b4d0bc2267680e1c99637a888edcf3034bb315d96efedc400bfabdf5f8a9aa7912dfef03771b86a6a69769efe1bdcaac6

data/.circleci/config.yml

@@ -7,6 +7,7 @@ orbs:
 
 jobs:
   build:
+    resource_class: medium
     parameters:
       ruby-version:
         type: string
@@ -15,7 +16,8 @@ jobs:
 
     steps:
       - checkout
-      - ruby/install-deps
+      - ruby/install-deps:
+          key: gems-v1-ruby<< parameters.ruby-version >>
       - run:
           name: Run specs and lint
           command: bundle exec rake

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [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
 - Scrub credentials from command arguments
 

data/CLAUDE.md

@@ -17,14 +17,14 @@ bin/setup
 ### Testing
 ```bash
 bin/rake spec                    # Run all tests
-rspec spec/[file]           # Run specific test file
-rspec spec/[file]:[line]    # Run specific test
+bin/rspec spec/[file]           # Run specific test file
+bin/rspec spec/[file]:[line]    # Run specific test
 ```
 
 ### Building and Releasing
 ```bash
-bundle exec rake install     # Install gem locally for testing
-bundle exec rake release     # Release to RubyGems (updates version, tags, pushes)
+bin/rake install     # Install gem locally for testing
+bin/rake release     # Release to RubyGems (updates version, tags, pushes)
 ```
 
 ### Code Quality
@@ -62,7 +62,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 +76,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:
 
@@ -161,7 +161,6 @@ end
 
 - Keep changes focused and atomic
 - Include tests for new functionality
-- Maintain backward compatibility when possible
 - Update examples in README.md if changing public APIs
 - Ensure CI passes (tests against Ruby 3.2, 3.3, and 3.4)
 
@@ -203,8 +202,7 @@ We welcome feature requests! When proposing new features:
 1. Check existing issues to avoid duplicates
 2. Describe the use case and motivation
 3. Provide code examples of how the feature would work
-4. Consider backward compatibility
-5. Be open to discussion and alternative approaches
+4. Be open to discussion and alternative approaches
 
 ## Additional Resources
 

data/Gemfile

@@ -7,5 +7,5 @@ group :development do
   gem "rake", "~> 13.0"
   gem "rspec", "~> 3.0"
   gem "timecop", "~> 0.9"
-  gem "standard", "~> 1.0"
+  gem "standard"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.3.0)
+    backspin (0.4.1)
       ostruct (~> 0.5.0)
       rspec-mocks (~> 3.0)
 
@@ -80,7 +80,7 @@ DEPENDENCIES
   backspin!
   rake (~> 13.0)
   rspec (~> 3.0)
-  standard (~> 1.0)
+  standard
   timecop (~> 0.9)
 
 BUNDLED WITH

data/README.md

@@ -1,8 +1,13 @@
-# 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 
 
-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 flexible test integration are welcome - PRs welcome!
+[![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)
 
-**NOTE:** Backspin is in early development (version 0.2.x), and you can expect the API to change. It is being developed along-side in-production CLI apps, so the API will be refined and improved as we get to 1.0.
+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!
+
+**NOTE:** Backspin should be considered alpha quality software while pre v1.0. It is in heavy development, and you can expect the API to change. It is being developed in conjunction with production CLI apps, so the API will be refined and improved as we get to 1.0.
 
 Inspired by [VCR](https://github.com/vcr/vcr) and other [golden master](https://en.wikipedia.org/wiki/Golden_master_(software_development)) libraries.
 
@@ -24,73 +29,147 @@ And then run `bundle install`.
 
 ## Usage
 
-### Recording CLI interactions
+### Quick Start
+
+The simplest way to use Backspin is with the `run` method, which automatically records on the first execution and verifies on subsequent runs:
 
 ```ruby
-require "backspin" 
+require "backspin"
+
+# First run: records the output
+result = Backspin.run("my_command") do
+  Open3.capture3("echo hello world")
+end
 
-# Record a command's output
-result = Backspin.call("echo_hello") do
-  stdout, stderr, status = Open3.capture3("echo hello")
-  # This will save the output to `spec/backspin_data/echo_hello.yaml`.
+# Subsequent runs: verifies the output matches
+result = Backspin.run("my_command") do
+  Open3.capture3("echo hello world")
 end
 
+# Use run! to automatically fail tests on mismatch
+Backspin.run!("my_command") do
+  Open3.capture3("echo hello mars")
+end
+# Raises an error because stdout will not match the recorded output
 ```
 
-### Verifying CLI output
+### Recording Modes
+
+Backspin supports different modes for controlling how commands are recorded and verified:
 
 ```ruby
-# Verify that a command produces the expected output
-result = Backspin.verify("echo_hello") do
+# Auto mode (default): Record on first run, verify on subsequent runs
+result = Backspin.run("my_command") do
+  Open3.capture3("echo hello")
+end
+
+# Explicit record mode: Always record, overwriting existing recordings
+result = Backspin.run("echo_test", mode: :record) do
   Open3.capture3("echo hello")
 end
+# 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
+  Open3.capture3("echo hello")
+end
 expect(result.verified?).to be true
+
+# Playback mode: Return recorded output without running the command
+result = Backspin.run("slow_command", mode: :playback) do
+  Open3.capture3("slow_command")  # Not executed - returns recorded output
+end
 ```
 
-### Using verify! for automatic test failures
+### Using run! for automatic test failures
+
+The `run!` method works exactly like `run` but automatically fails the test if verification fails:
 
 ```ruby
 # Automatically fail the test if output doesn't match
-Backspin.verify!("echo_hello") do
+Backspin.run!("echo_test") do
   Open3.capture3("echo hello")
 end
+# Raises an error with detailed diff if verification fails from recorded data in "echo_test.yml"
 ```
 
-### Playback mode for fast tests
+### Custom matchers
+
+For cases where exact matching isn't suitable, you can provide custom verification logic:
 
 ```ruby
-# Return recorded output without running the command
-result = Backspin.verify("slow_command", mode: :playback) do
-  Open3.capture3("slow_command")  # Not executed - will playback from the record yaml (assuming it exists)
+# Use custom logic to verify output
+result = Backspin.run("version_check", 
+                     matcher: ->(recorded, actual) {
+                       # Just check that both start with "ruby"
+                       recorded["stdout"].start_with?("ruby") && 
+                       actual["stdout"].start_with?("ruby")
+                     }) do
+  Open3.capture3("ruby --version")
 end
 ```
 
-### Custom matchers
+### Working with the Result Object
+
+The API returns a `RecordResult` object with helpful methods:
 
 ```ruby
-# Use custom logic to verify output
-Backspin.verify("version_check", 
-                matcher: ->(recorded, actual) {
-                  # Just check that both start with "ruby"
-                  recorded["stdout"].start_with?("ruby") && 
-                  actual["stdout"].start_with?("ruby")
-                }) do
-  Open3.capture3("ruby --version")
+result = Backspin.run("my_test") do
+  Open3.capture3("echo out; echo err >&2; exit 42")
 end
+
+# Check the mode
+result.recorded?  # true on first run
+result.verified?  # true/false on subsequent runs, nil when recording
+result.playback?  # true in playback mode
+
+# Access output (first command for single commands)
+result.stdout     # "out\n"
+result.stderr     # "err\n" 
+result.status     # 42
+result.success?   # false (non-zero exit)
+result.output     # The raw return value from the block
+
+# Debug information
+result.record_path  # Path to the YAML file
+result.error_message  # Human-readable error if verification failed
+result.diff  # Diff between expected and actual output
 ```
 
-### VCR-style use_record
+### Multiple Commands
 
-_The plan is to make something like this the main entry point API for ease of use_
+Backspin automatically records and verifies all commands executed in a block:
 
 ```ruby
-# Record on first run, replay on subsequent runs
-Backspin.use_record("my_command", record: :once) do
-  Open3.capture3("echo hello")
+result = Backspin.run("multi_command_test") do
+  # All of these commands will be recorded
+  version, = Open3.capture3("ruby --version")
+  files, = Open3.capture3("ls -la")
+  system("echo 'Processing...'")  # Note: system doesn't capture output
+  data, stderr, = Open3.capture3("curl https://api.example.com/data")
+  
+  # Return whatever you need
+  { version: version.strip, file_count: files.lines.count, data: data }
 end
+
+# Access individual command results
+result.commands.size       # 4
+result.multiple_commands?  # true
+
+# For multiple commands, use these accessors
+result.all_stdout  # Array of stdout from each command
+result.all_stderr  # Array of stderr from each command
+result.all_status  # Array of exit statuses
+
+# Or access specific commands
+result.commands[0].stdout  # Ruby version output
+result.commands[1].stdout  # ls output
+result.commands[2].status  # system call exit status (stdout is empty)
+result.commands[3].stderr  # curl errors if any
 ```
 
+When verifying multiple commands, Backspin ensures all commands match in the exact order they were recorded. If any command differs, you'll get a detailed error showing which commands failed.
+
 ### Credential Scrubbing
 
 If the CLI interaction you are recording contains sensitive data in stdout or stderr, you should be careful to make sure it is not recorded to yaml!
@@ -102,7 +181,7 @@ A tool like [trufflehog](https://github.com/trufflesecurity/trufflehog) or [gitl
 
 ```ruby
 # This will automatically scrub AWS keys, API tokens, passwords, etc.
-Backspin.call("aws_command") do
+Backspin.run("aws_command") do
   Open3.capture3("aws s3 ls")
 end
 
@@ -146,4 +225,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/rsanhe
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/backspin.gemspec

@@ -20,8 +20,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir = "bin"
-  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  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"

data/bin/rake

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

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/credential_filter.yml

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

@@ -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/echo_verify.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/episodes_filter.yml

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

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

data/fixtures/backspin/full_data_filter.yml

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

data/fixtures/backspin/mixed_calls.yml

@@ -0,0 +1,24 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - echo
+  - from
+  - system
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - from
+  - capture3
+  stdout: 'from capture3
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/multi_command.yml

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

data/fixtures/backspin/multi_command_filter.yml

@@ -0,0 +1,26 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'Count:"
+  - 42'
+  stdout: 'Count: X
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'Total:"
+  - 100'
+  stdout: 'Total: X
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/multi_field_filter.yml

@@ -0,0 +1,13 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - bash
+  - "-c"
+  - echo 'out' && echo 'err' >&2 && exit 1
+  stdout: modified stdout
+  stderr: modified stderr
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/multi_system.yml

@@ -0,0 +1,20 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - echo
+  - first
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'
+- command_type: Kernel::System
+  args:
+  - echo
+  - second
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'