much-stub 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
---- 
-SHA1: 
-  metadata.gz: e5d7e06636c2654760be8dee2fbe8c80d9b86ef4
-  data.tar.gz: ebca2dede9dd9f9305548d3d8eb9db88a4ec1bae
-SHA512: 
-  metadata.gz: 6e4b733a9dccaa7babf00419d86f7e6d112d1a84cfe306c854509e9109bedbaae1c22f2ed4d83edd95f05c571c9ce804251bd0ca75a790478703bf4a703497d8
-  data.tar.gz: b41abee2b1ed680b2df84d1eb08c5854beb98001a5b774c4ef2311e583200b96cbdb2ccf1872068c98d050107a1e3fc23eecc02e283fe01cb8e211ce2365b875
+---
+SHA256:
+  metadata.gz: f4801d3a180d37bd01d02a52d1c524d38f432e4bb287a87d1e7753825efb180a
+  data.tar.gz: 422762b6602a2f05725fd61561e745bced7430b3e459ee7198a670ce86e922bd
+SHA512:
+  metadata.gz: 3eb227fd853591c057e7869a6331cbd36ba0a308eb4a0a3a32313ea779ec740f89e32a297160fb40bd3400222af83693830c260df3c461d79d40e72d45d1df24
+  data.tar.gz: 8b7ab33cb886b60f4242bdaa6a1bcf9a5d1666c2b37a335eb01ab032d59841ff648b5bed5ffded02dfd40f2fe4451e1649ae45488a133c6773ef00670ae760d7

data/Gemfile

@@ -2,4 +2,4 @@ source "https://rubygems.org"
 
 gemspec
 
-gem 'pry', "~> 0.9.0"
+gem "pry", "~> 0.12.2"

data/README.md

@@ -14,62 +14,329 @@ Note: this was originally implemented in and extracted from [Assert](https://git
 ## Usage
 
 ```ruby
-myclass = Class.new do
-  def mymeth; 'meth'; end
-  def myval(val); val; end
+# Given this object/API
+
+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
 
-MuchStub.stub(myobj, :mymeth)
-myobj.mymeth
-  # => StubError: `mymeth` not stubbed.
-MuchStub.stub(myobj, :mymeth){ 'stub-meth' }
-myobj.mymeth
-  # => 'stub-meth'
-myobj.mymeth(123)
+# Create a new stub for the :my_method method
+
+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.stub(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'
 
-MuchStub.stub(myobj, :myval){ 'stub-meth' }
+# 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.(my_object, :my_value){ "stubbed-method" }
   # => StubError: arity mismatch
-MuchStub.stub(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.
-MuchStub.stub_send(myobj, :myval, 123) # call to the original method post-stub
+my_object.my_value(123)
+  # => "123"
+my_object.my_value(456)
+  # => StubError: `my_value(456)` not stubbed.
+
+# Call the original method after it has been stubbed.
+
+MuchStub.stub_send(my_object, :my_value, 123)
   # => 123
-MuchStub.stub_send(myobj, :myval, 456)
+MuchStub.stub_send(my_object, :my_value, 456)
   # => 456
 
-MuchStub.unstub(myobj, :mymeth)
-MuchStub.unstub(myobj, :myval)
+# Unstub individual stubs
+
+MuchStub.unstub(my_object, :my_method)
+MuchStub.unstub(my_object, :my_value)
 
-myobj.mymeth
-  # => 'meth'
-myobj.myval(123)
+# OR blanket unstub all stubs
+
+MuchStub.unstub!
+
+# The original API/behavior is preserved after unstubbing
+
+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:
 
@@ -83,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,19 +1,44 @@
 require "much-stub/version"
 
-module MuchStub
+require "much-stub/call"
+require "much-stub/call_spy"
 
+module MuchStub
   def self.stubs
     @stubs ||= {}
   end
 
+  def self.stub_key(obj, meth)
+    MuchStub::Stub.key(obj, meth)
+  end
+
+  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)
-    (self.stubs[MuchStub::Stub.key(obj, meth)] ||= begin
-      MuchStub::Stub.new(obj, meth, caller_locations)
-    end).tap{ |s| s.do = block }
+    key = self.stub_key(obj, meth)
+    self.stubs[key] ||= MuchStub::Stub.new(obj, meth, caller_locations)
+    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)
-    (self.stubs.delete(MuchStub::Stub.key(obj, meth)) || MuchStub::NullStub.new).teardown
+    key = self.stub_key(obj, meth)
+    (self.stubs.delete(key) || MuchStub::NullStub.new).teardown
   end
 
   def self.unstub!
@@ -28,8 +53,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
@@ -60,27 +108,45 @@ 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 => exception
+    rescue NotStubbedError
       @lookup.rehash
       lookup(args, orig_caller).call(*args, &block)
     end
 
     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
@@ -91,7 +157,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
@@ -128,7 +194,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|
@@ -136,13 +202,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
@@ -150,37 +214,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
@@ -201,9 +275,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