much-stub 0.1.1 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 405abaae599baf274c0eea900413f3c534c3acf1a19b4a83a356f5c61640025b
-  data.tar.gz: e68b22427ea8c78b87023576611a94c750a9d4ed75989cc72b7cdc96a56ebf2d
+  metadata.gz: a6dc9e4397c7c270a2678eac9f4761adb80bdd842e6708417844855639c6acfa
+  data.tar.gz: 57f89b55ddaf3b17a2444f7bbd40d2e8f9b1ad3046d1634021412f8847df605b
 SHA512:
-  metadata.gz: d1cafda498eceb26c4d41a4b4867c0376dc36d34149454350e3ac4ef8a04623ee747a6d28639e417cac93eeb1f4950c1fda696153be860c61e9fef8be8f36a3e
-  data.tar.gz: 416559df2f95b8faa18fac713e924e5af8ac128b2b385a91623f32939396488f9f2a0ecef01649c3099b076e385270cbae2f5f79a84e0e26d54c689c193e7e7e
+  metadata.gz: b57f84be1092bba24dfd51ace398e8116941a16e17f8698436158309305672e55076b46bb4b5695763c97530f7cbfce6f974de6b331432336d7b0aad8a2ecfe0
+  data.tar.gz: 4705afaee215d93ed0a998949dd70dd2d13f03aa5fac9a31093940be16799ad43b2878df7870a046b79a1a4e2c9625bb0f5195896c371c24728600445c18c55a

data/Gemfile

@@ -1,5 +1,7 @@
 source "https://rubygems.org"
 
+ruby "~> 2.5"
+
 gemspec
 
-gem 'pry', "~> 0.9.0"
+gem "pry"

data/README.md

@@ -16,77 +16,327 @@ Note: this was originally implemented in and extracted from [Assert](https://git
 ```ruby
 # Given this object/API
 
-myclass = Class.new do
-  def mymeth; 'meth'; end
-  def myval(val); val; end
+my_class = Class.new do
+  def my_method
+    "my-method"
+  end
+
+  def my_value(value)
+    value
+  end
 end
-myobj = myclass.new
+my_object = my_class.new
 
-myobj.mymeth
-  # => 'meth'
-myobj.myval(123)
+my_object.my_method
+  # => "my-method"
+my_object.my_value(123)
   # => 123
-myobj.myval(456)
+my_object.my_value(456)
   # => 456
 
-# Create a new stub for the :mymeth method
+# Create a new stub for the :my_method method
 
-MuchStub.(myobj, :mymeth)
-myobj.mymeth
-  # => StubError: `mymeth` not stubbed.
-MuchStub.(myobj, :mymeth){ 'stub-meth' }
-myobj.mymeth
-  # => 'stub-meth'
-myobj.mymeth(123)
+MuchStub.(my_object, :my_method)
+my_object.my_method
+  # => StubError: `my_method` not stubbed.
+MuchStub.(my_object, :my_method){ "stubbed-method" }
+my_object.my_method
+  # => "stubbed-method"
+my_object.my_method(123)
   # => StubError: arity mismatch
-MuchStub.(myobj, :mymeth).with(123){ 'stub-meth' }
+MuchStub.(my_object, :my_method).with(123){ "stubbed-method" }
   # => StubError: arity mismatch
-MuchStub.stub_send(myobj, :mymeth) # call to the original method post-stub
-  # => 'meth'
 
-# Create a new stub for the :myval method
+# Call the original method after it has been stubbed.
+
+MuchStub.stub_send(my_object, :my_method)
+  # => "my-method"
+
+# Create a new stub for the :my_value method
 
-MuchStub.(myobj, :myval){ 'stub-meth' }
+MuchStub.(my_object, :my_value){ "stubbed-method" }
   # => StubError: arity mismatch
-MuchStub.(myobj, :myval).with(123){ |val| val.to_s }
-myobj.myval
+MuchStub.(my_object, :my_value).with(123){ |val| val.to_s }
+my_object.my_value
   # => StubError: arity mismatch
-myobj.myval(123)
-  # => '123'
-myobj.myval(456)
-  # => StubError: `myval(456)` not stubbed.
+my_object.my_value(123)
+  # => "123"
+my_object.my_value(456)
+  # => StubError: `my_value(456)` not stubbed.
 
-# Call to the original method post-stub
+# Call the original method after it has been stubbed.
 
-MuchStub.stub_send(myobj, :myval, 123)
+MuchStub.stub_send(my_object, :my_value, 123)
   # => 123
-MuchStub.stub_send(myobj, :myval, 456)
+MuchStub.stub_send(my_object, :my_value, 456)
   # => 456
 
 # Unstub individual stubs
 
-MuchStub.unstub(myobj, :mymeth)
-MuchStub.unstub(myobj, :myval)
+MuchStub.unstub(my_object, :my_method)
+MuchStub.unstub(my_object, :my_value)
 
 # OR blanket unstub all stubs
 
 MuchStub.unstub!
 
-# Original API is preserved after unstubbing
+# The original API/behavior is preserved after unstubbing
 
-myobj.mymeth
-  # => 'meth'
-myobj.myval(123)
+my_object.my_method
+  # => "my-method"
+my_object.my_value(123)
   # => 123
-myobj.myval(456)
+my_object.my_value(456)
   # => 456
 ```
 
+### Stubs for spying
+
+```ruby
+# Given this object/API
+
+my_class = Class.new do
+  def basic_method(value)
+    value
+  end
+
+  def iterator_method(items, &block)
+    items.each(&block)
+  end
+end
+my_object = my_class.new
+
+# Store method call arguments/blocks for spying.
+
+basic_method_called_with = nil
+MuchStub.(my_object, :basic_method) { |*args|
+  basic_method_called_with = MuchStub::Call.new(*args)
+}
+# OR
+MuchStub.(my_object, :basic_method).on_call { |call|
+  basic_method_called_with = call
+}
+# OR
+MuchStub.on_call(my_object, :basic_method) { |call|
+  # MucStub.on_call(...) { ... } is equivalent to
+  # MuchStub.(...).on_call { ... }
+  basic_method_called_with = call
+}
+
+my_object.basic_method(123)
+basic_method_called_with.args
+  # => [123]
+
+basic_method_called_with = nil
+MuchStub.(my_object, :basic_method).with(4, 5, 6) { |*args|
+  basic_method_called_with = MuchStub::Call.new(*args)
+}
+# OR
+MuchStub.(my_object, :basic_method).with(4, 5, 6).on_call { |call|
+  basic_method_called_with = call
+}
+
+my_object.basic_method(4, 5, 6)
+basic_method_called_with.args
+  # => [4,5,6]
+
+iterator_method_called_with = nil
+MuchStub.(my_object, :iterator_method) { |*args, &block|
+  iterator_method_called_with = MuchStub::Call.new(*args)
+}
+# OR
+MuchStub.(my_object, :iterator_method).on_call { |call|
+  iterator_method_called_with = call
+}
+
+my_object.iterator_method([1, 2, 3], &:to_s)
+iterator_method_called_with.args
+  # => [[1, 2, 3]]
+iterator_method_called_with.block
+  # => #<Proc:0x00007fb083a6feb0(&:to_s)>
+
+# Count method calls for spying.
+
+basic_method_call_count = 0
+MuchStub.(my_object, :basic_method) {
+  basic_method_call_count += 1
+}
+
+my_object.basic_method(123)
+basic_method_call_count
+  # => 1
+
+# Count method calls and store arguments for spying.
+
+basic_method_calls = []
+MuchStub.(my_object, :basic_method) { |*args|
+  basic_method_calls << MuchStub::Call.new(*args)
+}
+# OR
+MuchStub.(my_object, :basic_method).on_call { |call|
+  basic_method_calls << call
+}
+
+my_object.basic_method(123)
+basic_method_calls.size
+  # => 1
+basic_method_calls.first.args
+  # => [123]
+```
+
+### Stubs for test doubles.
+
+```ruby
+# Given this object/API ...
+
+my_class = Class.new do
+  def build_thing(thing_value);
+    Thing.new(value)
+  end
+end
+my_object = my_class.new
+
+# ... and this Test Double.
+class FakeThing
+  attr_reader :built_with
+
+  def initialize(*args)
+    @built_with = args
+  end
+end
+
+# Stub in the test double.
+
+MuchStub.(my_object, :build_thing) { |*args|
+  FakeThing.new(*args)
+}
+
+thing = my_object.build_thing(123)
+thing.built_with
+  # => [123]
+```
+
+### `MuchStub.tap`
+
+Use the `.tap` method to spy on method calls while preserving the original method return value and behavior.
+
+```ruby
+# Given this object/API
+
+my_class = Class.new do
+  def basic_method(value)
+    value.to_s
+  end
+end
+my_object = my_class.new
+
+# Normal stubs override the original behavior and return value...
+basic_method_called_with = nil
+MuchStub.(my_object, :basic_method) { |*args|
+  basic_method_called_with = args
+}
+
+# ... in this case not converting the value to a String and returning it and
+# instead returning the arguments passed to the method.
+my_object.basic_method(123)
+  # => [123]
+basic_method_called_with
+  # => [123]
+
+# Use `MuchStub.tap` to preserve the methods behavior and also spy.
+
+basic_method_called_with = nil
+MuchStub.tap(my_object, :basic_method) { |value, *args|
+  basic_method_called_with = MuchStub::Call.new(*args)
+}
+# OR
+MuchStub.tap_on_call(my_object, :basic_method) { |value, call|
+  basic_method_called_with = call
+}
+
+my_object.basic_method(123)
+  # => "123"
+basic_method_called_with.args
+  # => [123]
+```
+
+#### Late-bound stubs using `MuchStub.tap`
+
+Use the `.tap` method to stub any return values of method calls.
+
+```ruby
+# Given:
+
+class Thing
+  attr_reader :value
+
+  def initialize(value)
+    @value = value
+  end
+end
+
+my_class = Class.new do
+  def thing(value)
+    Thing.new(value)
+  end
+end
+my_object = my_class.new
+
+# Use `MuchStub.tap` to stub any thing instances created by `my_object.thing`
+# (and also spy on the call arguments)
+
+thing_built_with = nil
+MuchStub.tap(my_object, :thing) { |thing, *args|
+  thing_built_with = args
+  MuchStub.(thing, :value) { 456 }
+}
+
+thing = my_object.thing(123)
+  # => #<Thing:0x00007fd5ca9df510 @value=123>
+thing_built_with
+  # => [123]
+thing.value
+  # => 456
+```
+
+### `MuchStub.spy`
+
+Use the `.spy` method to spy on method calls. This is especially helpful for spying on _chained_ method calls.
+
+```ruby
+# Given this object/API
+
+myclass = Class.new do
+  def one; self; end
+  def two(val); self; end
+  def three; self; end
+  def ready?; false; end
+end
+myobj = myclass.new
+
+spy =
+  MuchStub.spy(myobj :one, :two, :three, ready?: true)
+
+assert_equal spy, myobj.one
+assert_equal spy, myobj.two("a")
+assert_equal spy, myobj.three
+
+assert_true myobj.one.two("b").three.ready?
+
+assert_kind_of MuchStub::CallSpy, spy
+assert_equal 2, spy.one_call_count
+assert_equal 2, spy.two_call_count
+assert_equal 2, spy.three_call_count
+assert_equal 1, spy.ready_predicate_call_count
+assert_equal ["b"], spy.two_last_called_with.args
+assert_true spy.ready_predicate_called?
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'much-stub'
+    gem "much-stub"
 
 And then execute:
 
@@ -100,6 +350,6 @@ Or install it yourself as:
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
+3. Commit your changes (`git commit -am "Added some feature"`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request

data/lib/much-stub.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require "much-stub/version"
 
-module MuchStub
+require "much-stub/call"
+require "much-stub/call_spy"
 
+module MuchStub
   def self.stubs
     @stubs ||= {}
   end
@@ -10,8 +14,10 @@ module MuchStub
     MuchStub::Stub.key(obj, meth)
   end
 
-  def self.call(*args, &block)
-    self.stub(*args, &block)
+  def self.arity_matches?(method, args)
+    return true if method.arity == args.size # mandatory args
+    return true if method.arity < 0 && args.size >= (method.arity+1).abs # variable args
+    return false
   end
 
   def self.stub(obj, meth, &block)
@@ -20,6 +26,18 @@ module MuchStub
     self.stubs[key].tap{ |s| s.do = block }
   end
 
+  def self.call(*args, &block)
+    self.stub(*args, &block)
+  end
+
+  def self.stub_on_call(*args, &on_call_block)
+    self.stub(*args).on_call(&on_call_block)
+  end
+
+  def self.on_call(*args, &on_call_block)
+    self.stub_on_call(*args, &on_call_block)
+  end
+
   def self.unstub(obj, meth)
     key = self.stub_key(obj, meth)
     (self.stubs.delete(key) || MuchStub::NullStub.new).teardown
@@ -37,8 +55,31 @@ module MuchStub
     stub.call_method(args, &block)
   end
 
-  class Stub
+  def self.tap(obj, meth, &tap_block)
+    self.stub(obj, meth) { |*args, &block|
+      self.stub_send(obj, meth, *args, &block).tap { |value|
+        tap_block.call(value, *args, &block) if tap_block
+      }
+    }
+  end
+
+  def self.tap_on_call(obj, meth, &on_call_block)
+    self.tap(obj, meth) { |value, *args, &block|
+      on_call_block.call(value, MuchStub::Call.new(*args, &block)) if on_call_block
+    }
+  end
 
+  def self.spy(obj, *meths, **return_values)
+    MuchStub::CallSpy.new(**return_values).call_spy_tap do |spy|
+      meths.each do |meth|
+        self.stub(obj, meth) { |*args, &block|
+          spy.__send__(meth, *args, &block)
+        }
+      end
+    end
+  end
+
+  class Stub
     def self.key(object, method_name)
       "--#{object.object_id}--#{method_name}--"
     end
@@ -69,11 +110,13 @@ module MuchStub
 
     def call(args, orig_caller = nil, &block)
       orig_caller ||= caller_locations
-      unless arity_matches?(args)
-        msg = "arity mismatch on `#{@method_name}`: " \
-              "expected #{number_of_args(@method.arity)}, " \
-              "called with #{args.size}"
-        raise StubArityError, msg, orig_caller.map(&:to_s)
+      unless MuchStub.arity_matches?(@method, args)
+        raise(
+          StubArityError.new(
+            @method,
+            args,
+            method_name: @method_name,
+            backtrace: orig_caller))
       end
       lookup(args, orig_caller).call(*args, &block)
     rescue NotStubbedError
@@ -83,13 +126,29 @@ module MuchStub
 
     def with(*args, &block)
       orig_caller = caller_locations
-      unless arity_matches?(args)
-        msg = "arity mismatch on `#{@method_name}`: " \
-              "expected #{number_of_args(@method.arity)}, " \
-              "stubbed with #{args.size}"
-        raise StubArityError, msg, orig_caller.map(&:to_s)
+      unless MuchStub.arity_matches?(@method, args)
+        raise(
+          StubArityError.new(
+            @method,
+            args,
+            method_name: @method_name,
+            backtrace: orig_caller))
       end
       @lookup[args] = block
+      self
+    end
+
+    def on_call(&on_call_block)
+      stub_block =
+        ->(*args, &block) {
+          on_call_block.call(MuchStub::Call.new(*args, &block)) if on_call_block
+        }
+      if @lookup.empty?
+        @do = stub_block
+      elsif @lookup.has_value?(nil)
+        @lookup.transform_values!{ |value| value.nil? ? stub_block : value }
+      end
+      self
     end
 
     def teardown
@@ -100,7 +159,7 @@ module MuchStub
     end
 
     def inspect
-      "#<#{self.class}:#{'0x0%x' % (object_id << 1)}" \
+      "#<#{self.class}:#{"0x0%x" % (object_id << 1)}" \
       " @method_name=#{@method_name.inspect}" \
       ">"
     end
@@ -137,7 +196,7 @@ module MuchStub
     end
 
     def lookup(args, orig_caller)
-      @lookup.fetch(args) do
+      @lookup.fetch(args) {
         self.do || begin
           msg = "#{inspect_call(args)} not stubbed."
           inspect_lookup_stubs.tap do |stubs|
@@ -145,13 +204,11 @@ module MuchStub
           end
           raise NotStubbedError, msg, orig_caller.map(&:to_s)
         end
-      end
-    end
-
-    def arity_matches?(args)
-      return true if @method.arity == args.size # mandatory args
-      return true if @method.arity < 0 && args.size >= (@method.arity+1).abs # variable args
-      return false
+      } ||
+        raise(
+          StubError,
+          "#{inspect_call(args)} stubbed with no block.",
+          orig_caller.map(&:to_s))
     end
 
     def inspect_lookup_stubs
@@ -159,37 +216,47 @@ module MuchStub
     end
 
     def inspect_call(args)
-      "`#{@method_name}(#{args.map(&:inspect).join(',')})`"
+      "`#{@method_name}(#{args.map(&:inspect).join(",")})`"
     end
-
-    def number_of_args(arity)
-      if arity < 0
-        "at least #{(arity + 1).abs}"
-      else
-        arity
-      end
-    end
-
   end
 
   StubError       = Class.new(ArgumentError)
   NotStubbedError = Class.new(StubError)
-  StubArityError  = Class.new(StubError)
+  StubArityError  =
+    Class.new(StubError) do
+      def initialize(method, args, method_name:, backtrace:)
+        msg = "arity mismatch on `#{method_name}`: " \
+              "expected #{number_of_args(method.arity)}, " \
+              "called with #{args.size}"
+
+        super(msg)
+        set_backtrace(Array(backtrace).map(&:to_s))
+      end
+
+      private
+
+      def number_of_args(arity)
+        if arity < 0
+          "at least #{(arity + 1).abs}"
+        else
+          arity
+        end
+      end
+    end
 
   NullStub = Class.new do
     def teardown; end # no-op
   end
 
   module ParameterList
-
-    LETTERS = ('a'..'z').to_a.freeze
+    LETTERS = ("a".."z").to_a.freeze
 
     def self.new(object, method_name)
       arity = get_arity(object, method_name)
       params = build_params_from_arity(arity)
-      params << '*args' if arity < 0
-      params << '&block'
-      params.join(', ')
+      params << "*args" if arity < 0
+      params << "&block"
+      params.join(", ")
     end
 
     private
@@ -210,9 +277,7 @@ module MuchStub
       number_of_letters, letter_index = param_index.divmod(LETTERS.size)
       LETTERS[letter_index] * number_of_letters
     end
-
   end
-
 end
 
 # Kernel#caller_locations polyfill for pre ruby 2.0.0