impersonator 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c27e2c12811df79ee6ecda2a617b9952ac98dff360ca3e08d725832d54cf5b03
-  data.tar.gz: d40825fb2fbbdc7ac842bf58864acc2c02f2dd72b3a228b1ee0ee9ded86f891b
+  metadata.gz: 44894f5dac3e7080abf3ffebf05ea83a876394629f60f9e486319f8e4e5304e2
+  data.tar.gz: 994a96556cef09050e108cfd55539af2f61507afae6298a994da811f187076bb
 SHA512:
-  metadata.gz: e8039d138b2f899a27d9476873ce687586a5322a7d0846a2828207592f51fd6a80f134a54fc7dce99cc8ea1d8581cdae25f62382e2129054d2148d1d05360543
-  data.tar.gz: e39e557b268d09c24206d7db469fa7dd931002e0cf9b6b72b70e25ba2f87270f43b176170b43e83ae7b8fa0e26999c7e956afb1b5ac83a1fd2f0327359124e94
+  metadata.gz: 83d2e1d38817599af079e1160c519a9529a820485ee851e7d9934a897f3f81ba97f3dc6add6c4e3f59f73d88095442971f9f4231666337cc75d9dd1cc7468b5b
+  data.tar.gz: 7c8b47fb88e82aca2d80ffc27f09c1ae37842d0ca2a0356fdaed50bc9d5cb9bb659c6687759ea21c95949af215c16a8572b09dfc975e54c839461a17d71757a7

data/.rubocop.yml

@@ -4,7 +4,7 @@ Style/FrozenStringLiteralComment:
   Enabled: false
 
 Metrics/LineLength:
-  Enabled: false
+  Max: 105
 
 Metrics/AbcSize:
   Enabled: false

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.2
+
+- [Add YARD documentation](https://github.com/jorgemanrubia/impersonator/pull/3)
+
+## 0.1.1
+
+- Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    impersonator (0.1.1)
+    impersonator (0.1.2)
       zeitwerk (~> 2.1.6)
 
 GEM
@@ -41,7 +41,7 @@ GEM
       rubocop (>= 0.60.0)
     ruby-progressbar (1.10.1)
     unicode-display_width (1.6.0)
-    zeitwerk (2.1.6)
+    zeitwerk (2.1.8)
 
 PLATFORMS
   ruby

data/impersonator.gemspec

@@ -9,7 +9,8 @@ Gem::Specification.new do |spec|
   spec.email         = ['jorge.manrubia@gmail.com']
 
   spec.summary       = 'Generate test stubs that replay recorded interactions'
-  spec.description   = 'Record and replay object interactions. Ideal for mocking not-http services when testing (just because, for http, VCR is probably what you want)'
+  spec.description   = 'Record and replay object interactions. Ideal for mocking not-http services'\
+                       ' when testing (just because, for http, VCR is probably what you want)'
   spec.homepage      = 'https://github.com/jorgemanrubia/impersonator'
   spec.license       = 'MIT'
 

data/lib/impersonator/api.rb

@@ -1,7 +1,16 @@
 module Impersonator
+  # Public API exposed by the global `Impersonator` module.
   module Api
+    # Wraps the execution of the yielded code withing a new {Recording recording} titled with the
+    # passed label.
+    #
+    # @param [String] label The label for the recording
+    # @param [Boolean] disabled `true` will disable replay mode and always execute code in *record*
+    #   mode. `false` by default
     def recording(label, disabled: false)
-      @current_recording = ::Impersonator::Recording.new(label, disabled: disabled, recordings_path: configuration.recordings_path)
+      @current_recording = ::Impersonator::Recording.new label,
+                                                         disabled: disabled,
+                                                         recordings_path: configuration.recordings_path
       @current_recording.start
       yield
       @current_recording.finish
@@ -9,14 +18,28 @@ module Impersonator
       @current_recording = nil
     end
 
+    # The current recording, if any, or `nil` otherwise.
+    #
+    # @return [Recording, nil]
     def current_recording
       @current_recording
     end
 
+    # Configures how Impersonator works by yielding a {Configuration configuration} object
+    # you can use to tweak settings.
+    #
+    # ```
+    # Impersonator.configure do |config|
+    #   config.recordings_path = 'my/own/recording/path'
+    # end
+    # ```
+    #
+    # @yieldparam config [Configuration]
     def configure
       yield configuration
     end
 
+    # @return [Configuration]
     def configuration
       @configuration ||= Configuration.new
     end
@@ -36,14 +59,17 @@ module Impersonator
     #   impersonator = Impersonator.impersonate(:add, :subtract) { Calculator.new }
     #   impersonator.add(3, 4)
     #
-    # Notice that the actual object won't be instantiated in record mode. For that reason, the impersonated
-    # object will only respond to the list of impersonated methods.
+    # Notice that the actual object won't be instantiated in record mode. For that reason, the
+    # impersonated object will only respond to the list of impersonated methods.
     #
     # If you need to invoke other (not impersonated) methods see #impersonate_method instead.
     #
-    # @return [Object] the impersonated object
+    # @param [Array<Symbols, Strings>] methods list of methods to impersonate
+    # @return [Proxy] the impersonated proxy object
     def impersonate(*methods)
-      raise ArgumentError, 'Provide a block to instantiate the object to impersonate in record mode' unless block_given?
+      unless block_given?
+        raise ArgumentError, 'Provide a block to instantiate the object to impersonate in record mode'
+      end
 
       object_to_impersonate = if current_recording&.record_mode?
                                 yield
@@ -55,14 +81,20 @@ module Impersonator
 
     # Impersonates a list of methods of a given object
     #
-    # The returned object will impersonate the list of methods and will delegate the rest of method calls
-    # to the actual object.
+    # The returned object will impersonate the list of methods and will delegate the rest of method
+    # calls to the actual object.
     #
-    # @return [Object] the impersonated object
+    # @param [Object] actual_object The actual object to impersonate
+    # @param [Array<Symbols, Strings>] methods list of methods to impersonate
+    # @return [Proxy] the impersonated proxy object
     def impersonate_methods(actual_object, *methods)
-      raise Impersonator::Errors::ConfigurationError, 'You must start a recording to impersonate objects. Use Impersonator.recording {}' unless @current_recording
+      unless @current_recording
+        raise Impersonator::Errors::ConfigurationError, 'You must start a recording to impersonate'\
+              ' objects. Use Impersonator.recording {}'
+      end
 
-      ::Impersonator::Proxy.new(actual_object, recording: current_recording, impersonated_methods: methods)
+      ::Impersonator::Proxy.new(actual_object, recording: current_recording,
+                                               impersonated_methods: methods)
     end
   end
 end

data/lib/impersonator/block_invocation.rb

@@ -1,3 +1,4 @@
 module Impersonator
+  # A block invocation
   BlockInvocation = Struct.new(:arguments, keyword_init: true)
 end

data/lib/impersonator/block_spy.rb

@@ -1,5 +1,7 @@
 module Impersonator
+  # An spy object that can collect {BlockInvocation block invocations}
   BlockSpy = Struct.new(:block_invocations, :actual_block, keyword_init: true) do
+    # @return [Proc] a proc that will collect {BlockInvocation block invocations}
     def block
       @block ||= proc do |*arguments|
         self.block_invocations ||= []

data/lib/impersonator/configuration.rb

@@ -1,5 +1,8 @@
 module Impersonator
+  # General configuration settings for Impersonator
   Configuration = Struct.new(:recordings_path, keyword_init: true) do
+    # @!attribute recordings_path [String] The path where recordings are saved to
+
     DEFAULT_RECORDINGS_FOLDER = 'recordings'.freeze
 
     def initialize(*)

data/lib/impersonator/double.rb

@@ -1,5 +1,7 @@
 module Impersonator
+  # A simple double implementation. It will generate empty stubs for the passed list of methods
   class Double
+    # @param [Array<String, Symbol>] methods The list of methods this double will respond to
     def initialize(*methods)
       define_methods(methods)
     end

data/lib/impersonator/errors/configuration_error.rb

@@ -1,5 +1,6 @@
 module Impersonator
   module Errors
+    # Indicates a configuration error
     class ConfigurationError < StandardError
     end
   end

data/lib/impersonator/errors/method_invocation_error.rb

@@ -1,5 +1,6 @@
 module Impersonator
   module Errors
+    # Unexpected method invocation error
     class MethodInvocationError < StandardError
     end
   end

data/lib/impersonator/has_logger.rb

@@ -1,4 +1,7 @@
 module Impersonator
+  # A mixin that will add a method `logger` to access a logger instance
+  #
+  # @see ::Impersonator.logger
   module HasLogger
     def logger
       ::Impersonator.logger

data/lib/impersonator/method.rb

@@ -1,5 +1,12 @@
 module Impersonator
+  # A method instance
   Method = Struct.new(:name, :arguments, :block, :matching_configuration, keyword_init: true) do
+    # @!attribute name [String] Method name
+    # @!attribute arguments [Array<Object>] Arguments passed to the method invocation
+    # @!attribute arguments [#call] The block passed to the method
+    # @!attribute matching_configuration [MethodMatchingConfiguration] The configuration that will
+    #   be used to match the method invocation at replay mode
+
     def to_s
       string = name.to_s
 
@@ -10,6 +17,9 @@ module Impersonator
       string
     end
 
+    # The spy used to spy the block yield invocations
+    #
+    # @return [BlockSpy]
     def block_spy
       return nil if !@block_spy && !block
 
@@ -38,7 +48,8 @@ module Impersonator
         other_arguments.delete_at(ignored_position)
       end
 
-      name == other_method.name && my_arguments == other_arguments && !block_spy == !other_method.block_spy
+      name == other_method.name && my_arguments == other_arguments &&
+        !block_spy == !other_method.block_spy
     end
   end
 end

data/lib/impersonator/method_invocation.rb

@@ -1,3 +1,4 @@
 module Impersonator
+  # A method invocation groups a {Method method instance} and a return value
   MethodInvocation = Struct.new(:method_instance, :return_value, keyword_init: true)
 end

data/lib/impersonator/method_matching_configuration.rb

@@ -1,4 +1,5 @@
 module Impersonator
+  # Configuration options for matching methods
   class MethodMatchingConfiguration
     attr_reader :ignored_positions
 
@@ -6,6 +7,9 @@ module Impersonator
       @ignored_positions = []
     end
 
+    # Configure positions to ignore
+    #
+    # @param [Array<Integer>] positions The positions of arguments to ignore (0 being the first one)
     def ignore_arguments_at(*positions)
       ignored_positions.push(*positions)
     end

data/lib/impersonator/proxy.rb

@@ -1,9 +1,17 @@
 module Impersonator
+  # A proxy represents the impersonated object at both record and replay times.
+  #
+  # For not impersonated methods, it will just delegate to the impersonate object. For impersonated
+  # methods, it will interact with the {Recording recording} for recording or replaying the object
+  # interactions.
   class Proxy
     include HasLogger
 
     attr_reader :impersonated_object
 
+    # @param [Object] impersonated_object
+    # @param [Recording] recording
+    # @param [Array<Symbol, String>] impersonated_methods The methods to impersonate
     def initialize(impersonated_object, recording:, impersonated_methods:)
       validate_object_has_methods_to_impersonate!(impersonated_object, impersonated_methods)
 
@@ -25,6 +33,16 @@ module Impersonator
       impersonated_object.respond_to_missing?(method_name, *args)
     end
 
+    # Configure matching options for a given method
+    #
+    # ```ruby
+    # impersonator.configure_method_matching_for(:add) do |config|
+    #   config.ignore_arguments_at 0
+    # end
+    # ```
+    #
+    # @param [String, Symbol] method The method to configure matching options for
+    # @yieldparam config [MethodMatchingConfiguration]
     def configure_method_matching_for(method)
       method_matching_configurations_by_method[method.to_sym] ||= MethodMatchingConfiguration.new
       yield method_matching_configurations_by_method[method]
@@ -39,15 +57,21 @@ module Impersonator
         !object.respond_to?(method.to_sym)
       end
 
-      raise Impersonator::Errors::ConfigurationError, "These methods to impersonate does not exist: #{missing_methods.inspect}" unless missing_methods.empty?
+      unless missing_methods.empty?
+        raise Impersonator::Errors::ConfigurationError, 'These methods to impersonate does not'\
+                      "exist: #{missing_methods.inspect}"
+      end
     end
 
     def invoke_impersonated_method(method_name, *args, &block)
-      method = Method.new(name: method_name, arguments: args, block: block, matching_configuration: method_matching_configurations_by_method[method_name.to_sym])
+      matching_configuration = method_matching_configurations_by_method[method_name.to_sym]
+      method = Method.new(name: method_name, arguments: args, block: block,
+                          matching_configuration: matching_configuration)
       if recording.replay_mode?
         recording.replay(method)
       else
-        @impersonated_object.send(method_name, *args, &method&.block_spy&.block).tap do |return_value|
+        spiable_block = method&.block_spy&.block
+        @impersonated_object.send(method_name, *args, &spiable_block).tap do |return_value|
           recording.record(method, return_value)
         end
       end

data/lib/impersonator/recording.rb

@@ -1,17 +1,23 @@
 # frozen_string_literal: true
 
 module Impersonator
+  # A recording is responsible for saving interactions at record time, and replaying them at
+  # replay time.
   class Recording
     include HasLogger
 
     attr_reader :label
 
+    # @param [String] label
+    # @param [Boolean] disabled `true` for always working in *record* mode. `false` by default
+    # @param [String] the path to save recordings to
     def initialize(label, disabled: false, recordings_path:)
       @label = label
       @recordings_path = recordings_path
       @disabled = disabled
     end
 
+    # Start a recording/replay session
     def start
       logger.debug "Starting recording #{label}..."
       if can_replay?
@@ -21,15 +27,23 @@ module Impersonator
       end
     end
 
+    # Record a {MethodInvocation method invocation} with a given return value
+    # @param [Method] method
+    # @param [Object] return_value
     def record(method, return_value)
       method_invocation = MethodInvocation.new(method_instance: method, return_value: return_value)
 
       @method_invocations << method_invocation
     end
 
+    # Replay a method invocation
+    # @param [Method] method
     def replay(method)
       method_invocation = @method_invocations.shift
-      raise Impersonator::Errors::MethodInvocationError, "Unexpected method invocation received: #{method}" unless method_invocation
+      unless method_invocation
+        raise Impersonator::Errors::MethodInvocationError, 'Unexpected method invocation received:'\
+              "#{method}"
+      end
 
       validate_method_signature!(method, method_invocation.method_instance)
       replay_block(method_invocation, method)
@@ -37,6 +51,7 @@ module Impersonator
       method_invocation.return_value
     end
 
+    # Finish a record/replay session.
     def finish
       logger.debug "Recording #{label} finished"
       if record_mode?
@@ -46,10 +61,16 @@ module Impersonator
       end
     end
 
+    # Return whether it is currently at replay mode
+    #
+    # @return [Boolean]
     def replay_mode?
       @replay_mode
     end
 
+    # Return whether it is currently at record mode
+    #
+    # @return [Boolean]
     def record_mode?
       !replay_mode?
     end
@@ -88,8 +109,9 @@ module Impersonator
 
     def finish_in_replay_mode
       unless @method_invocations.empty?
-        raise Impersonator::Errors::MethodInvocationError, "Expecting #{@method_invocations.length} method invocations"\
-                                                            " that didn't happen: #{@method_invocations.inspect}"
+        raise Impersonator::Errors::MethodInvocationError,
+              "Expecting #{@method_invocations.length} method invocations"\
+              " that didn't happen: #{@method_invocations.inspect}"
       end
     end
 

data/lib/impersonator/version.rb

@@ -1,3 +1,3 @@
 module Impersonator
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.1.2'.freeze
 end

data/lib/impersonator.rb

@@ -11,6 +11,9 @@ loader.setup
 module Impersonator
   extend Api
 
+  # The gem logger instance
+  #
+  # @return [::Logger]
   def self.logger
     @logger ||= ::Logger.new(STDOUT).tap do |logger|
       logger.level = Logger::WARN

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: impersonator
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Jorge Manrubia
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-06-18 00:00:00.000000000 Z
+date: 2019-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -94,6 +94,8 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt