betamax 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f89807eb4aa9a8365294d743efddad3a94a6a6c9078615731bebc2fa1cf93f6
+  data.tar.gz: 31a8decf2ca628028820007eff48e83cbe45758fab781bc87503c3c172e61c8a
+SHA512:
+  metadata.gz: 92208fdfd5c7bff89094c394827da00a06425f3c0037e9caa498230a1afb3dec467ab5b32325018c0ce2162095ad9ae1c59be4ab36f8943699ffafffdf13407a
+  data.tar.gz: cf74600f45a068b9b01b3d268211d3992e6d836d7e80d2f8baafe446a80628588669cb68530e2cb1bea63bd3fca6ea2a5509009562d2bbdb67df538cfdc6650d

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-15
+
+- Initial release

data/README.md

@@ -0,0 +1,35 @@
+# Betamax
+
+TODO: Delete this and the text below, and describe your gem
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/betamax`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Aesthetikx/betamax.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new :spec
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/betamax/errors.rb

@@ -0,0 +1,59 @@
+module Betamax
+  module Errors
+    class Error < StandardError; end
+
+    class NoTapeInserted < Error
+      def initialize message = "No tape inserted"
+        super
+      end
+    end
+
+    class PlaybackError < Error; end
+
+    class PlaybackFinished < PlaybackError
+      def initialize method_name
+        super "Received #{method_name} but playback has finished"
+      end
+    end
+
+    class MethodMismatch < PlaybackError
+      def initialize expected:, actual:
+        super "Expected method #{expected} but received #{actual}"
+      end
+    end
+
+    class UnexpectedBlock < PlaybackError
+      def initialize method_name
+        super "Method #{method_name} was called with a block but was recorded without one"
+      end
+    end
+
+    class BlockExpected < PlaybackError
+      def initialize method_name
+        super "Method #{method_name} was called without a block but was recorded with one"
+      end
+    end
+
+    class ArgumentMismatch < PlaybackError
+      def initialize method_name, expected:, actual:
+        super "Method #{method_name} argument mismatch: " \
+              "expected #{expected.inspect}, got #{actual.inspect}"
+      end
+    end
+
+    class KeywordArgumentMismatch < PlaybackError
+      def initialize method_name, expected_key:, expected_value:, actual_key:, actual_value:
+        super "Method #{method_name} keyword argument mismatch: " \
+              "expected #{expected_key}: #{expected_value.inspect}, " \
+              "got #{actual_key}: #{actual_value.inspect}"
+      end
+    end
+
+    class UnusedRecordings < PlaybackError
+      def initialize unused_methods
+        method_names = unused_methods.map(&:method_name).join(", ")
+        super "Recording has #{unused_methods.size} unused method(s): #{method_names}"
+      end
+    end
+  end
+end

data/lib/betamax/method_player.rb

@@ -0,0 +1,123 @@
+module Betamax
+  class MethodPlayer
+    attr_reader :recording
+
+    def initialize recording:
+      @recording = recording
+      @playback_index = 0
+    end
+
+    def fully_consumed?
+      @playback_index == @recording.size &&
+        @recording.all? { |record| nested_fully_consumed? record }
+    end
+
+    def unused_recordings
+      unused = @recording[@playback_index..] || []
+      nested_unused = @recording.first(@playback_index).flat_map do |record|
+        unused_from_record record
+      end
+      unused + nested_unused
+    end
+
+    def call(method_name, *args, **kwargs, &)
+      record = advance_playback! method_name
+
+      validate_method_name! record.method_name, method_name
+      validate_args! method_name, args, record.args
+      validate_kwargs! method_name, kwargs, record.kwargs
+      validate_block! method_name, block_given?, record.block_given
+
+      replay_yieldings(record.block_yieldings, &)
+
+      record.result
+    end
+
+    private
+
+    def nested_fully_consumed? record
+      consumed?(record.result) &&
+        record.block_yieldings.all? { |yielding| yielding_consumed? yielding }
+    end
+
+    def yielding_consumed? yielding
+      yielding.args.all? { |arg| consumed? arg } &&
+        yielding.kwargs.values.all? { |value| consumed? value }
+    end
+
+    def consumed? object
+      return true unless object.instance_of? RecordedObject
+
+      object._betamax_recorder.fully_consumed?
+    end
+
+    def unused_from_record record
+      result_unused = unused_from_object record.result
+      yielding_unused = record.block_yieldings.flat_map do |yielding|
+        unused_from_yielding yielding
+      end
+      result_unused + yielding_unused
+    end
+
+    def unused_from_yielding yielding
+      args_unused = yielding.args.flat_map { |arg| unused_from_object arg }
+      kwargs_unused = yielding.kwargs.values.flat_map { |value| unused_from_object value }
+      args_unused + kwargs_unused
+    end
+
+    def unused_from_object object
+      return [] unless object.instance_of? RecordedObject
+
+      object._betamax_recorder.unused_recordings
+    end
+
+    def replay_yieldings block_yieldings
+      block_yieldings.each do |yielding|
+        yield(*yielding.args, **yielding.kwargs)
+      end
+    end
+
+    def advance_playback! method_name
+      @recording[@playback_index].tap do |record|
+        raise Errors::PlaybackFinished, method_name if record.nil?
+
+        @playback_index += 1
+      end
+    end
+
+    def validate_method_name! expected, actual
+      return if expected == actual
+
+      raise Errors::MethodMismatch.new expected:, actual:
+    end
+
+    def validate_args! method_name, actual_args, expected_args
+      max_size = [actual_args.size, expected_args.size].max
+      max_size.times do |i|
+        actual = actual_args[i]
+        expected = expected_args[i]
+        next if actual == expected
+
+        raise Errors::ArgumentMismatch.new method_name, expected:, actual:
+      end
+    end
+
+    def validate_kwargs! method_name, actual_kwargs, expected_kwargs
+      all_keys = (actual_kwargs.keys | expected_kwargs.keys)
+      all_keys.each do |key|
+        actual_value = actual_kwargs[key]
+        expected_value = expected_kwargs[key]
+        next if actual_value == expected_value
+
+        raise Errors::KeywordArgumentMismatch.new method_name,
+                                                  expected_key: key, expected_value:,
+                                                  actual_key: key, actual_value:
+      end
+    end
+
+    def validate_block! method_name, actual_block_given, expected_block_given
+      raise Errors::BlockExpected, method_name if expected_block_given && !actual_block_given
+      raise Errors::UnexpectedBlock, method_name if actual_block_given && !expected_block_given
+    end
+  end
+end

data/lib/betamax/method_recorder.rb

@@ -0,0 +1,55 @@
+module Betamax
+  class MethodRecorder
+    PRIMITIVE_TYPES = [Integer, Float, String, Symbol, TrueClass, FalseClass, NilClass].freeze
+
+    attr_reader :recording
+
+    def initialize object:, recording: []
+      @object = object
+      @recording = recording
+    end
+
+    def call(method_name, *args, **kwargs, &) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      block_yieldings = []
+
+      result = if block_given?
+                 @object.send(method_name, *args, **kwargs) do |*block_args, **block_kwargs|
+                   wrapped_args = block_args.map { |arg| wrap_object arg }
+                   wrapped_kwargs = block_kwargs.transform_values { |value| wrap_object value }
+
+                   yielding = RecordedYielding.new args: wrapped_args, kwargs: wrapped_kwargs
+                   block_yieldings << yielding
+
+                   yield(*wrapped_args, **wrapped_kwargs)
+                 end
+               else
+                 @object.send(method_name, *args, **kwargs, &)
+               end
+
+      wrapped_result = wrap_object result
+
+      @recording << RecordedMethod.new(
+        method_name:,
+        args:,
+        kwargs:,
+        block_given: block_given?,
+        block_yieldings:,
+        result: wrapped_result
+      )
+
+      wrapped_result
+    end
+
+    private
+
+    def wrap_object object
+      case object
+      when *PRIMITIVE_TYPES
+        object
+      else
+        recorder = MethodRecorder.new object:, recording: []
+        RecordedObject.new object:, recorder:
+      end
+    end
+  end
+end

data/lib/betamax/player.rb

@@ -0,0 +1,54 @@
+module Betamax
+  class Player
+    attr_reader :tape, :root_proxy, :tapes_folder
+
+    def initialize example, tapes_folder:
+      @example = example
+      @tapes_folder = tapes_folder
+      @tape = Tape.from_rspec_example(example, tapes_folder:)
+      @root_proxy = nil
+    end
+
+    def play
+      insert_tape
+      @example.run
+      eject_tape unless @example.exception
+    end
+
+    def record object
+      recorder = if @tape.exists?
+                   MethodPlayer.new recording: @tape.recording
+                 else
+                   MethodRecorder.new object:, recording: @tape.recording
+                 end
+
+      @root_proxy = RecordedObject.new object:, recorder:
+    end
+
+    private
+
+    def insert_tape
+      @tape.load
+      Fiber[:betamax_player] = self
+    end
+
+    def eject_tape
+      Fiber[:betamax_player] = nil
+
+      if @tape.exists?
+        verify_fully_consumed!
+      elsif @root_proxy
+        @tape.save @root_proxy
+      end
+    end
+
+    def verify_fully_consumed!
+      return unless @root_proxy
+
+      recorder = @root_proxy._betamax_recorder
+      return if recorder.fully_consumed?
+
+      raise Errors::UnusedRecordings, recorder.unused_recordings
+    end
+  end
+end

data/lib/betamax/recorded_method.rb

@@ -0,0 +1,14 @@
+module Betamax
+  RecordedMethod = Data.define :method_name, :args, :kwargs, :block_given, :block_yieldings, :result
+
+  # Implement YAML serialization / deserialization
+  RecordedMethod.include Module.new {
+    def init_with coder
+      initialize **coder.map
+    end
+
+    def encode_with coder
+      coder.map = to_h
+    end
+  }
+end

data/lib/betamax/recorded_object.rb

@@ -0,0 +1,34 @@
+module Betamax
+  class RecordedObject
+    attr_reader :_betamax_recorder
+
+    def initialize object:, recorder:
+      @_betamax_object = object
+      @_betamax_recorder = recorder
+    end
+
+    def respond_to_missing? method_name, _include_private = false
+      @_betamax_object.respond_to? method_name
+    end
+
+    def method_missing(...)
+      @_betamax_recorder.call(...)
+    end
+  end
+
+  # Implement YAML serialization / deserialization
+  RecordedObject.include Module.new {
+    def init_with coder
+      recording = coder.map.fetch :recording
+      recorder = MethodPlayer.new recording: recording
+      initialize object: nil, recorder: recorder
+    end
+
+    def encode_with coder
+      coder.map = {
+        class_name: @_betamax_object.class.name,
+        recording: @_betamax_recorder.recording
+      }
+    end
+  }
+end

data/lib/betamax/recorded_yielding.rb

@@ -0,0 +1,14 @@
+module Betamax
+  RecordedYielding = Data.define :args, :kwargs
+
+  # Implement YAML serialization / deserialization
+  RecordedYielding.include Module.new {
+    def init_with coder
+      initialize **coder.map
+    end
+
+    def encode_with coder
+      coder.map = to_h
+    end
+  }
+end

data/lib/betamax/recording.rb

@@ -0,0 +1,20 @@
+module Betamax
+  Recording = Data.define :version, :objects
+
+  Recording::VERSION = 1.0
+
+  # Implement YAML serialization / deserialization
+  Recording.include Module.new {
+    def init_with coder
+      initialize **coder.map
+    end
+
+    def encode_with coder
+      coder.map = to_h
+    end
+
+    def default_recording
+      objects.fetch(:default)._betamax_recorder.recording
+    end
+  }
+end

data/lib/betamax/rspec.rb

@@ -0,0 +1,17 @@
+module Betamax
+  module RSpec
+    DEFAULT_TAPES_FOLDER = Pathname.new "spec/betamax_tapes/"
+
+    def play_rspec example, tapes_folder: DEFAULT_TAPES_FOLDER
+      Player.new(example, tapes_folder:).play
+    end
+
+    def install_rspec!
+      ::RSpec.configure do |config|
+        config.around :each, :betamax do |example|
+          Betamax.play_rspec example
+        end
+      end
+    end
+  end
+end

data/lib/betamax/tape.rb

@@ -0,0 +1,89 @@
+require "fileutils"
+require "yaml"
+
+module Betamax
+  class Tape
+    PERMITTED_YAML_CLASSES = [
+      Betamax::Recording,
+      Betamax::RecordedObject,
+      Betamax::RecordedMethod,
+      Betamax::RecordedYielding,
+      Symbol
+    ].freeze
+
+    attr_reader :path, :recording
+
+    def initialize path
+      @path = Pathname.new path
+      @recording = nil
+    end
+
+    def self.from_rspec_example example, tapes_folder:
+      name = cassette_name_for example.metadata
+      name.gsub! "::", "_"
+      name.gsub!(/[\s-]+/, "_")
+      name.gsub! %r{[^a-zA-Z0-9_/]}, ""
+
+      filename = Pathname.new(name).sub_ext ".yaml"
+      full_path = tapes_folder / filename
+
+      new full_path
+    end
+
+    def self.cassette_name_for metadata
+      # Build name from example group hierarchy + example description
+      description_parts = []
+
+      # Add the example description first
+      description_parts << metadata[:description] if metadata[:description]
+
+      # Walk up the example group hierarchy
+      current = metadata[:example_group]
+      while current
+        description_parts.unshift current[:description] if current[:description]
+        current = current[:parent_example_group]
+      end
+
+      description_parts.join "/"
+    end
+
+    def load
+      FileUtils.mkdir_p @path.dirname
+
+      if exists?
+        load_existing_recording
+      else
+        prepare_new_recording
+      end
+
+      self
+    end
+
+    def save proxy
+      return if exists? # Don't overwrite existing recordings
+
+      recording = Betamax::Recording.new \
+        version: Recording::VERSION,
+        objects: { default: proxy }
+
+      File.open @path, "w" do |file|
+        file.puts recording.to_yaml
+      end
+    end
+
+    def exists?
+      File.exist? @path
+    end
+
+    private
+
+    def load_existing_recording
+      raw = YAML.safe_load_file @path, permitted_classes: PERMITTED_YAML_CLASSES
+      @recording = raw.default_recording
+    end
+
+    def prepare_new_recording
+      @recording = []
+    end
+  end
+end

data/lib/betamax/version.rb

@@ -0,0 +1,3 @@
+module Betamax
+  VERSION = "0.1.0".freeze
+end

data/lib/betamax.rb

@@ -0,0 +1,33 @@
+require "pathname"
+
+require_relative "betamax/errors"
+require_relative "betamax/method_player"
+require_relative "betamax/method_recorder"
+require_relative "betamax/player"
+require_relative "betamax/recorded_method"
+require_relative "betamax/recorded_object"
+require_relative "betamax/recorded_yielding"
+require_relative "betamax/recording"
+require_relative "betamax/rspec"
+require_relative "betamax/tape"
+require_relative "betamax/version"
+
+module Betamax
+  extend RSpec
+
+  module_function
+
+  def record object
+    player = current_player
+
+    raise Errors::NoTapeInserted unless player
+
+    player.record object
+  end
+
+  def current_player
+    Fiber[:betamax_player]
+  end
+end
+
+Betamax.install_rspec! if defined? RSpec

data/sig/betamax.rbs

@@ -0,0 +1,4 @@
+module Betamax
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: betamax
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- John DeSilva
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Betamax allows for the recording and playback of arbitrary Ruby objects
+  to simplify testing external dependencies
+email:
+- john@aesthetikx.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/betamax.rb
+- lib/betamax/errors.rb
+- lib/betamax/method_player.rb
+- lib/betamax/method_recorder.rb
+- lib/betamax/player.rb
+- lib/betamax/recorded_method.rb
+- lib/betamax/recorded_object.rb
+- lib/betamax/recorded_yielding.rb
+- lib/betamax/recording.rb
+- lib/betamax/rspec.rb
+- lib/betamax/tape.rb
+- lib/betamax/version.rb
+- sig/betamax.rbs
+homepage: https://github.com/Aesthetikx/betamax
+licenses: []
+metadata:
+  homepage_uri: https://github.com/Aesthetikx/betamax
+  source_code_uri: https://github.com/Aesthetikx/betamax
+  changelog_uri: https://github.com/Aesthetikx/betamax/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Record and playback of arbitrary Ruby objects
+test_files: []