add documentation and and_return raises error if block is sent with wrong arity

Author: ryanong

.yardopts

@@ -0,0 +1 @@
+--markup=markdown

Gemfile

@@ -4,3 +4,5 @@ source 'https://rubygems.org'
 gemspec
 gem 'pry'
 gem 'pry-nav'
+gem 'yard'
+gem 'redcarpet'

README.md

@@ -1,8 +1,8 @@
 # Spy
 
-Spy is a lightweight stubbing framework that won't let your code mock your intelligence.
+Spy is a lightweight stubbing framework with support for method spies, constant stubs, and object doubles.
 
-Spy was designed for 1.9.3+ so there is no legacy tech debt.
+Spy was designed for 1.9.3+.
 
 Spy features that were completed were tested against the rspec-mocks tests so it covers all cases that rspec-mocks does.
 
@@ -33,10 +33,7 @@ Fail faster, code faster.
 * missing these features
   * Mocking null objects
   * argument matchers for Spy::Method#has\_been\_called\_with
-  * watch all calls to an object to check order in which they are called?
-    * is this useful?
-  * fail lazily on method call not on hook to allow for dynamic method creation?
-    * do more than 0.5% of develoeprs use this?
+  * watch all calls to an object to check order in which they are called
 
 ## Installation
 
@@ -54,64 +51,93 @@ Or install it yourself as:
 
 ## Usage
 
+### Method Stubs
+
+A method stub overrides a pre-existing method and records all calls to specified method. You can set the spy to return either the original method or your own custom implementation.
+
+Spy support 2 different ways of spying an existing method on an object.
 ```ruby
-class Person
-  def first_name
-    "John"
-  end
+Spy.on(book, title: "East of Eden")
+Spy.on(book, :title).and_return("East of Eden")
+Spy.on(book, :title).and_return { "East of Eden" }
+```
 
-  def last_name
-    "Smith"
-  end
+Spy will raise an error if you try to stub on a method that doesn't exist.
+You can force the creation of a sstub on method that didn't exist but it really isn't suggested.
 
-  def full_name
-    "#{first_name} #{last_name}"
-  end
+```ruby
+Spy.new(book, :flamethrower).hook(force:true).and_return("burnninante")
+```
 
-  def say(words)
-    puts words
-  end
+### Test Doubles
+
+A test double is an object that stands in for a real object.
+
+```ruby
+Spy.double("book")
+```
+
+Spy will let you stub on any method even if it doesn't exist if the object is a double.
+
+Spy comes with a shortcut to define an object with methods.
+
+```ruby
+Spy.double("book", title: "Grapes of Wrath", author: "John Steinbeck")
+```
+
+### Arbitrary Handling
+
+If you need to have a custom method based in the method inputs just send a block to #and\_return
+
+```ruby
+Spy.on(book, :read_page).and_return do |page, &block|
+  block.call
+  "awesome " * page
 end
 ```
 
-### Standalone
+An error will raise if the arity of the block is larger than the arity of the original method. However this can be overidden with the force argument.
 
 ```ruby
-person = Person.new
+Spy.on(book, :read_page).and_return(force: true) do |a, b, c, d|
+end
+```
 
-first_name_spy = Spy.on(person, :first_name)
-person.first_name            #=> nil
-first_name_spy.has_been_called?       #=> true
+### Method Spies
 
-Spy.get(person, :first_name) #=> first_name_spy
+When you stub a method it returns a spy. A spy records what calls have been made to a given method.
 
-Spy.off(person, :first_name)
-person.first_name          #=> "John"
+```ruby
+validator = Spy.double("validator")
+validate_spy = Spy.on(validator, :validate)
+validate_spy.has_been_called? #=> false
+validator.validate("01234")   #=> nil
+validate_spy.has_been_called? #=> true
+validate_spy.has_been_called_with?("01234) #=> true
+```
 
-first_name_spy.hook        #=> first_name_spy
-first_name_spy.and_return("Bob")
-person.first_name          #=> "Bob"
+### Calling through
+If you just want to make sure if a method is called and not override the output you can just use the and\_call\_through method
 
-Spy.teardown
-person.first_name #=> "John"
+```ruby
+Spy.on(book, :read_page).and_call_through
+```
 
-say_spy = Spy.on(person, :say)
-person.say("hello") {
-  "everything accepts a block in ruby"
-}
-say_spy.say("world")
+### Call Logs
 
-say_spy.has_been_called? #=> true
-say_spy.has_been_called_with?("hello") #=> true
-say_spy.calls.count               #=> 1
-say_spy.calls.first.args          #=> ["hello"]
-say_spy.calls.last.args           #=> ["world"]
+When a spy is called on it records a call log. A call log contains the object it was called on, the arguments and block that were sent to method and what it returned.
 
-call_log = say_spy.calls.first
-call_log.object     #=> #<Person:0x00000000b2b858>
-call_log.args       #=> ["hello"]
-call_log.block      #=> #<Proc:0x00000000b1a9e0>
-call_log.block.call #=> "everything accepts a block in ruby"
+```ruby
+read_page_spy = Spy.on(book, read_page: "hello world")
+book.read_page(5) { "this is a block" }
+book.read_page(3)
+book.read_page(7)
+read_page_spy.calls.size #=> 3
+first_call = read_page_spy.calls.first
+first_call.object #=> book
+first_call.args   #=> [5]
+first_call.block  #=> Proc.new { "this is a block" }
+first_call.result #=> "hello world"
 ```
 
 ### MiniTest

lib/spy.rb

@@ -2,7 +2,6 @@
 require "spy/agency"
 require "spy/constant"
 require "spy/double"
-require "spy/dsl"
 require "spy/nest"
 require "spy/subroutine"
 require "spy/version"
@@ -11,10 +10,9 @@ module Spy
   SECRET_SPY_KEY = Object.new
   class << self
     # create a spy on given object
-    # @params base_object
-    # @params *method_names [Symbol] will spy on these methods
-    # @params *method_names [Hash] will spy on these methods and also set default return values
-    # @return [Spy, Array<Spy>]
+    # @param base_object
+    # @param method_names *[Hash,Symbol] will spy on these methods and also set default return values
+    # @return [Subroutine, Array<Subroutine>]
     def on(base_object, *method_names)
       spies = method_names.map do |method_name|
         create_and_hook_spy(base_object, method_name)
@@ -24,9 +22,9 @@ def on(base_object, *method_names)
     end
 
     # removes the spy from the from the given object
-    # @params base_object
-    # @params *method_names
-    # @return [Spy, Array<Spy>]
+    # @param base_object
+    # @param method_names *[Symbol]
+    # @return [Subroutine, Array<Subroutine>]
     def off(base_object, *method_names)
       removed_spies = method_names.map do |method_name|
         spy = Subroutine.get(base_object, method_name)
@@ -40,6 +38,10 @@ def off(base_object, *method_names)
       removed_spies.size > 1 ? removed_spies : removed_spies.first
     end
 
+    # create a stub for constants on given module
+    # @param base_module [Module]
+    # @param constant_names *[Symbol, Hash]
+    # @return [Constant, Array<Constant>]
     def on_const(base_module, *constant_names)
       if base_module.is_a? Symbol
         constant_names.unshift(base_module)
@@ -61,6 +63,10 @@ def on_const(base_module, *constant_names)
       spies.size > 1 ? spies : spies.first
     end
 
+    # removes stubs from given module
+    # @param base_module [Module]
+    # @param constant_names *[Symbol]
+    # @return [Constant, Array<Constant>]
     def off_const(base_module, *constant_names)
       spies = constant_names.map do |constant_name|
         case constant_name
@@ -83,14 +89,16 @@ def teardown
       Agency.instance.dissolve!
     end
 
-    # (see Double#new)
+    # returns a double
+    # (see Double#initizalize)
     def double(*args)
       Double.new(*args)
     end
 
     # retrieve the spy from an object
-    # @params base_object
-    # @method_names *[Symbol, Hash]
+    # @param base_object
+    # @param method_names *[Symbol]
+    # @return [Subroutine, Array<Subroutine>]
     def get(base_object, *method_names)
       spies = method_names.map do |method_name|
         Subroutine.get(base_object, method_name)
@@ -99,6 +107,10 @@ def get(base_object, *method_names)
       spies.size > 1 ? spies : spies.first
     end
 
+    # retrieve the constant spies from an object
+    # @param base_module
+    # @param constant_names *[Symbol]
+    # @return [Constant, Array<Constant>]
     def get_const(base_module, *constant_names)
       spies = constant_names.map do |method_name|
         Constant.get(base_module, constant_name)

lib/spy/dsl.rb

@@ -1,7 +1,11 @@
 module Spy
   class Subroutine
-    CallLog = Struct.new(:object, :args, :block)
+    CallLog = Struct.new(:object, :args, :block, :result)
     attr_reader :base_object, :method_name, :calls, :original_method, :opts
+
+    # set what object and method the spy should watch
+    # @param object
+    # @param method_name <Symbol>
     def initialize(object, method_name)
       @was_hooked = false
       @base_object, @method_name = object, method_name
@@ -58,20 +62,32 @@ def hooked?
       self == self.class.get(base_object, method_name)
     end
 
-    # sets the return value of given spied method
-    # @params return value
-    # @params return block
+    # @overload and_return(value)
+    # @overload and_return(&block)
+    #
+    # Tells the spy to return a value when the method is called.
+    #
     # @return self
-    def and_return(value = nil, &block)
+    def and_return(value = nil)
       if block_given?
-        raise ArgumentError.new("value and block conflict. Choose one") if !value.nil?
-        @plan = block
+        @plan = Proc.new
+        if value.nil? || value.is_a?(Hash) && value.has_key?(:force)
+          if !(value.is_a?(Hash) && value[:force]) &&
+              original_method &&
+              original_method.arity >=0 &&
+              @plan.arity > original_method.arity
+            raise ArgumentError.new "The original method only has an arity of #{original_method.arity} you have an arity of #{@plan.arity}"
+          end
+        else
+          raise ArgumentError.new("value and block conflict. Choose one") if !value.nil?
+        end
       else
         @plan = Proc.new { value }
       end
       self
     end
 
+    # Tells the object to yield one or more args to a block when the message is received.
     def and_yield(*args)
       yield eval_context = Object.new if block_given?
       @plan = Proc.new do |&block|
@@ -124,9 +140,9 @@ def has_been_called_with?(*args)
     # method.
     def invoke(object, args, block)
       check_arity!(args.size)
-      calls << CallLog.new(object, args, block)
-      default_return_val = nil
-      @plan ? @plan.call(*args, &block) : default_return_val
+      result = @plan ? @plan.call(*args, &block) : nil
+      calls << CallLog.new(object, args, block, result)
+      result
     end
 
     # reset the call log
@@ -139,7 +155,7 @@ def reset!
     private
 
     def call_with_yield(&block)
-      raise "no block sent"  unless block
+      raise "no block sent" unless block
       value = nil
       @args_to_yield.each do |args|
         if block.arity > -1 && args.length != block.arity

lib/spy/subroutine.rb

@@ -67,14 +67,26 @@ def test_spy_and_return_returns_the_set_value
     def test_spy_and_return_can_call_a_block
       result = "hello world"
 
-      spy_on(@pen, :write).and_return do |string|
+      spy_on(@pen, :write).and_return {}.and_return do |string|
         string.reverse
       end
 
       assert_equal result.reverse, @pen.write(result)
       assert_empty @pen.written
     end
 
+    def test_spy_and_return_can_call_a_block_raises_when_there_is_an_arity_mismatch
+      write_spy = spy_on(@pen, :write)
+      write_spy.and_return do |*args|
+      end
+      write_spy.and_return do |string, *args|
+      end
+      assert_raises ArgumentError do
+        write_spy.and_return do |string, b|
+        end
+      end
+    end
+
     def test_spy_and_return_can_call_a_block_that_recieves_a_block
       string = "hello world"