backspin 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9afcbf90256cbfd84f6b9694544282dc593fc715d9886a9e3a9ba54e064410fc
-  data.tar.gz: c3d6e95547f27364b4108b5f75641ed88a9e153f0e4ccdbed3d276e82dd5f99b
+  metadata.gz: 59bc6e711951434fc84dd2c2694f69aa5b00ef3bf878b81c5b4e97beeb430ad6
+  data.tar.gz: f9784962ef86ad73e0eb1c8388217700e477bc60ce0528b5dd16f08bc5c2f637
 SHA512:
-  metadata.gz: 2c7c36cee5518f0944896c04c96d36ae134d56928510ee01aef646a2eb0c036c723ab65aff64c6726751ce6b4c406de90f486e4da5bd3242344fd23d8e7792f1
-  data.tar.gz: 116e28fadefdc8651f648f25f0da4c347d86127448a34e0ca20a244f6bb0e7f101e140052e0f0e9029ec1693b40b6363ab3d7db6a0b7c2a0ab9252976ae64c33
+  metadata.gz: e4151f4a28909e1a80706a30520b268f5114124230df9869a3603d5502194f4885ca8dff19e15a9a8ffe5f559b14695614f9f113c66e82ccc105de5b7ae17006
+  data.tar.gz: a66f71d1a4b2e9404ca39178920d8b88686f5e8cec2fe62f282b1cda9de031c1041cdfa1007ee9dc725c24cfb1c4dad5445213091a20c0faf23165705a8d264e

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

data/CONTRIBUTING.md

@@ -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.0)
       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,8 @@
 # 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 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!
+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 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.
+**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 +24,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 `spec/backspin_data/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 +176,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 +220,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/lib/backspin/command.rb

@@ -1,14 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "command_result"
+
 module Backspin
   class Command
-    attr_reader :args, :stdout, :stderr, :status, :recorded_at, :method_class
+    attr_reader :args, :result, :recorded_at, :method_class
 
-    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, recorded_at: nil)
+    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, result: nil, recorded_at: nil)
       @method_class = method_class
       @args = args
-      @stdout = stdout
-      @stderr = stderr
-      @status = status
       @recorded_at = recorded_at
+
+      # Accept either a CommandResult or individual stdout/stderr/status
+      @result = result || CommandResult.new(
+        stdout: stdout || "",
+        stderr: stderr || "",
+        status: status || 0
+      )
+    end
+
+    def stdout
+      @result.stdout
+    end
+
+    def stderr
+      @result.stderr
+    end
+
+    def status
+      @result.status
     end
 
     # Convert to hash for YAML serialization
@@ -16,16 +36,14 @@ module Backspin
       data = {
         "command_type" => @method_class.name,
         "args" => scrub_args(@args),
-        "stdout" => Backspin.scrub_text(@stdout),
-        "stderr" => Backspin.scrub_text(@stderr),
-        "status" => @status,
+        "stdout" => Backspin.scrub_text(@result.stdout),
+        "stderr" => Backspin.scrub_text(@result.stderr),
+        "status" => @result.status,
         "recorded_at" => @recorded_at
       }
 
       # Apply filter if provided
-      if filter
-        data = filter.call(data)
-      end
+      data = filter.call(data) if filter
 
       data
     end
@@ -59,11 +77,12 @@ module Backspin
       return args unless Backspin.configuration.scrub_credentials && args
 
       args.map do |arg|
-        if arg.is_a?(String)
+        case arg
+        when String
           Backspin.scrub_text(arg)
-        elsif arg.is_a?(Array)
+        when Array
           scrub_args(arg)
-        elsif arg.is_a?(Hash)
+        when Hash
           arg.transform_values { |v| v.is_a?(String) ? Backspin.scrub_text(v) : v }
         else
           arg

data/lib/backspin/command_diff.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Represents the difference between a recorded command and actual execution
+  # Handles verification and diff generation for a single command
+  class CommandDiff
+    attr_reader :recorded_command, :actual_result, :matcher
+
+    def initialize(recorded_command:, actual_result:, matcher: nil)
+      @recorded_command = recorded_command
+      @actual_result = actual_result
+      @matcher = matcher
+    end
+
+    # @return [Boolean] true if the command output matches
+    def verified?
+      if matcher
+        matcher.call(recorded_command.to_h, actual_result.to_h)
+      else
+        recorded_command.result == actual_result
+      end
+    end
+
+    # @return [String, nil] Human-readable diff if not verified
+    def diff
+      return nil if verified?
+
+      parts = []
+
+      parts << stdout_diff if recorded_command.stdout != actual_result.stdout
+
+      parts << stderr_diff if recorded_command.stderr != actual_result.stderr
+
+      if recorded_command.status != actual_result.status
+        parts << "Exit status: expected #{recorded_command.status}, got #{actual_result.status}"
+      end
+
+      parts.join("\n\n")
+    end
+
+    # @return [String] Single line summary for error messages
+    def summary
+      if verified?
+        "✓ Command verified"
+      else
+        "✗ Command failed: #{failure_reason}"
+      end
+    end
+
+    private
+
+    def failure_reason
+      reasons = []
+      reasons << "stdout differs" if recorded_command.stdout != actual_result.stdout
+      reasons << "stderr differs" if recorded_command.stderr != actual_result.stderr
+      reasons << "exit status differs" if recorded_command.status != actual_result.status
+      reasons.join(", ")
+    end
+
+    def stdout_diff
+      "stdout diff:\n#{generate_line_diff(recorded_command.stdout, actual_result.stdout)}"
+    end
+
+    def stderr_diff
+      "stderr diff:\n#{generate_line_diff(recorded_command.stderr, actual_result.stderr)}"
+    end
+
+    def generate_line_diff(expected, actual)
+      expected_lines = (expected || "").lines
+      actual_lines = (actual || "").lines
+
+      diff_lines = []
+      max_lines = [expected_lines.length, actual_lines.length].max
+
+      max_lines.times do |i|
+        expected_line = expected_lines[i]
+        actual_line = actual_lines[i]
+
+        if expected_line != actual_line
+          diff_lines << "-#{expected_line.chomp}" if expected_line
+          diff_lines << "+#{actual_line.chomp}" if actual_line
+        end
+      end
+
+      diff_lines.join("\n")
+    end
+  end
+end

data/lib/backspin/command_result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Represents the result of executing a command
+  # Stores stdout, stderr, and exit status
+  class CommandResult
+    attr_reader :stdout, :stderr, :status
+
+    def initialize(stdout:, stderr:, status:)
+      @stdout = stdout
+      @stderr = stderr
+      @status = normalize_status(status)
+    end
+
+    # @return [Boolean] true if the command succeeded (exit status 0)
+    def success?
+      status.zero?
+    end
+
+    # @return [Boolean] true if the command failed (non-zero exit status)
+    def failure?
+      !success?
+    end
+
+    # @return [Hash] Hash representation of the result
+    def to_h
+      {
+        "stdout" => stdout,
+        "stderr" => stderr,
+        "status" => status
+      }
+    end
+
+    # Compare two results for equality
+    def ==(other)
+      return false unless other.is_a?(CommandResult)
+
+      stdout == other.stdout &&
+        stderr == other.stderr &&
+        status == other.status
+    end
+
+    def inspect
+      "#<Backspin::CommandResult status=#{status} stdout=#{stdout.inspect.truncate(50)} stderr=#{stderr.inspect.truncate(50)}>"
+    end
+
+    private
+
+    def normalize_status(status)
+      case status
+      when Integer
+        status
+      when Process::Status
+        status.exitstatus
+      else
+        status.respond_to?(:exitstatus) ? status.exitstatus : status.to_i
+      end
+    end
+  end
+end

data/lib/backspin/record.rb

@@ -4,6 +4,7 @@ module Backspin
   class NoMoreRecordingsError < StandardError; end
 
   class Record
+    FORMAT_VERSION = "2.0"
     attr_reader :path, :commands, :first_recorded_at
 
     def initialize(path)
@@ -22,10 +23,9 @@ module Backspin
 
     def save(filter: nil)
       FileUtils.mkdir_p(File.dirname(@path))
-      # New format: top-level metadata with commands array
       record_data = {
         "first_recorded_at" => @first_recorded_at,
-        "format_version" => "2.0",
+        "format_version" => FORMAT_VERSION,
         "commands" => @commands.map { |cmd| cmd.to_h(filter: filter) }
       }
       File.write(@path, record_data.to_yaml)