spy 0.0.1 → 0.1.0

data/.yardopts

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

data/Gemfile

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

data/README.md

@@ -1,23 +1,39 @@
 # Spy
 
-Spy is a lightweight doubles 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+.
+
+Spy features that were completed were tested against the rspec-mocks tests so it covers all cases that rspec-mocks does.
 
 Inspired by the spy api of the jasmine javascript testing framework.
 
 ## Why use this instead of rspec-mocks, mocha, or etc
 
-* Raise error when you try to stub/spy a method that doesn't exist
+* Spy will raise error when you try to stub/spy a method that doesn't exist
   * when you change your method name your unit tests will break
+  * no more fantasy tests
 * Spy arity matches original method
   * Your tests will raise an error if you use the wrong arity
 * Spy visibility matches original method
   * Your tests will raise an error if you try to call the method incorrectly
 * Simple call log api
   * easier to read tests
-  * less need to look at test framework documentation
+  * use ruby to test ruby instead of a dsl
 * no expectations
   * really who thought that was a good idea?
-* absolutely no polution of global object space unless you want to
+* absolutely no polution of global object space
+* no polution of instance variables for stubbed objects
+
+Fail faster, code faster.
+
+## Why not to use this
+
+* Api is not stable
+* 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
 
 ## Installation
 
@@ -35,63 +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.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.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

data/lib/spy.rb

@@ -1,229 +1,119 @@
-require "spy/version"
+require "spy/core_ext/marshal"
+require "spy/agency"
+require "spy/constant"
 require "spy/double"
-require "spy/dsl"
-
-class Spy
-  CallLog = Struct.new(:object, :args, :block)
-
-  attr_reader :base_object, :method_name, :calls, :original_method
-  def initialize(object, method_name)
-    @base_object, @method_name = object, method_name
-    reset!
-  end
-
-  # hooks the method into the object and stashes original method if it exists
-  # @param opts [Hash{force => false, visibility => nil}] set :force => true if you want it to ignore if the method exists, or visibility to [:public, :protected, :private] to overwride current visibility
-  # @return self
-  def hook(opts = {})
-    raise "#{method_name} method has already been hooked" if hooked?
-    raise "#{base_object} method '#{method_name}' has already been hooked" if self.class.get(base_object, method_name)
-    opts[:force] ||= base_object.is_a?(Double)
-    if base_object.respond_to?(method_name, true) || !opts[:force]
-      @original_method = base_object.method(method_name)
-    end
+require "spy/nest"
+require "spy/subroutine"
+require "spy/version"
 
-    opts[:visibility] ||= method_visibility
+module Spy
+  SECRET_SPY_KEY = Object.new
+  class << self
+    # create a spy on given object
+    # @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)
+      end.flatten
 
-    if original_method && original_method.owner == base_object.singleton_class
-      base_object.singleton_class.send(:remove_method, method_name)
+      spies.size > 1 ? spies : spies.first
     end
 
-    __method_spy__ = self
-    base_object.define_singleton_method(method_name) do |*__spy_args, &block|
-      if __spy_args.first === __method_spy__.class.__secret_method_key__
-        __method_spy__
-      else
-        __method_spy__.record(self,__spy_args,block)
+    # removes the spy from the from the given object
+    # @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)
+        if spy
+          spy.unhook
+        else
+          raise "Spy was not found"
+        end
       end
-    end
-
-    base_object.singleton_class.send(opts[:visibility], method_name) if opts[:visibility]
 
-    @hooked = true
-    self
-  end
-
-  # unhooks method from object
-  # @return self
-  def unhook
-    raise "#{method_name} method has not been hooked" unless hooked?
-    base_object.singleton_class.send(:remove_method, method_name)
-    if original_method && original_method.owner == base_object.singleton_class
-      base_object.define_singleton_method(method_name, original_method)
-      base_object.singleton_class.send(method_visibility, method_name) if method_visibility
-    end
-    clear_method!
-    self
-  end
-
-  # is the spy hooked?
-  # @return Boolean
-  def hooked?
-    @hooked
-  end
-
-
-  # sets the return value of given spied method
-  # @params return value
-  # @params return block
-  # @return self
-  def and_return(value = nil, &block)
-    if block_given?
-      raise ArgumentError.new("value and block conflict. Choose one") if !value.nil?
-      @plan = block
-    else
-      @plan = Proc.new { value }
+      removed_spies.size > 1 ? removed_spies : removed_spies.first
     end
-    self
-  end
 
-  # tells the spy to call the original method
-  # @return self
-  def and_call_through
-    raise "can only call through if original method is set" unless method_visibility
-    if original_method
-      @plan = original_method
-    else
-      @plan = Proc.new do |*args, &block|
-        base_object.send(:method_missing, method_name, *args, &block)
+    # 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)
+        base_module = Object
       end
-    end
-    self
-  end
-
-  def has_been_called?
-    calls.size > 0
-  end
-
-  # check if the method was called with the exact arguments
-  def has_been_called_with?(*args)
-    calls.any? do |call_log|
-      call_log.args == args
-    end
-  end
-
-  # record that the method has been called. You really shouldn't use this
-  # method.
-  def record(object, args, block)
-    check_arity!(args.size)
-    calls << CallLog.new(object, args, block)
-    @plan.call(*args, &block) if @plan
-  end
-
-  # reset the call log
-  def reset!
-    @calls = []
-    clear_method!
-    true
-  end
-
-  private
-
-  def clear_method!
-    @hooked = false
-    @original_method = @arity_range = @method_visibility = nil
-  end
-
-  def method_visibility
-    @method_visibility ||=
-        if base_object.respond_to?(method_name)
-          if original_method && original_method.owner.protected_method_defined?(method_name)
-            :protected
-          else
-            :public
+      spies = constant_names.map do |constant_name|
+        case constant_name
+        when String, Symbol
+          Constant.on(base_module, constant_name)
+        when Hash
+          constant_name.map do |name, result|
+            on_const(base_module, name).and_return(result)
           end
-        elsif base_object.respond_to?(method_name, true)
-          :private
+        else
+          raise ArgumentError.new "#{constant_name.class} is an invalid input, #on only accepts String, Symbol, and Hash"
         end
-  end
+      end.flatten
 
-  def check_arity!(arity)
-    return unless arity_range
-    if arity < arity_range.min
-      raise ArgumentError.new("wrong number of arguments (#{arity} for #{arity_range.min})")
-    elsif arity > arity_range.max
-      raise ArgumentError.new("wrong number of arguments (#{arity} for #{arity_range.max})")
+      spies.size > 1 ? spies : spies.first
     end
-  end
 
-  def arity_range
-    @arity_range ||=
-      if original_method
-        min = max = 0
-        original_method.parameters.each do |type,_|
-          case type
-          when :req
-            min += 1
-            max += 1
-          when :opt
-            max += 1
-          when :rest
-            max = Float::INFINITY
+    # 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
+        when String, Symbol
+          Constant.off(base_module, constant_name)
+        when Hash
+          constant_name.map do |name, result|
+            off_const(base_module, name).and_return(result)
           end
+        else
+          raise ArgumentError.new "#{constant_name.class} is an invalid input, #on only accepts String, Symbol, and Hash"
         end
-        (min..max)
-      end
-  end
-
-  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>]
-    def on(base_object, *method_names)
-      spies = method_names.map do |method_name|
-        create_and_hook_spy(base_object, method_name)
       end.flatten
 
       spies.size > 1 ? spies : spies.first
     end
 
-    # removes the spy from the
-    def off(base_object, *method_names)
-      removed_spies = method_names.map do |method_name|
-        unhook_and_remove_spy(base_object, method_name)
-      end.flatten
-
-      raise "No spies found" if removed_spies.empty?
-      removed_spies.size > 1 ? removed_spies : removed_spies.first
-    end
-
-    # get all hooked methods
-    # @return [Array<Spy>]
-    def all
-      @all ||= []
-    end
-
     # unhook all methods
     def teardown
-      all.each(&:unhook)
-      reset
-    end
-
-    # reset all hooked methods
-    def reset
-      @all = nil
+      Agency.instance.dissolve!
     end
 
-    # (see Double#new)
+    # returns a double
+    # (see Double#initizalize)
     def double(*args)
       Double.new(*args)
     end
 
-    # @private
-    def __secret_method_key__
-      @__secret_method_key__ ||= Object.new
-    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|
-        if base_object.singleton_methods.include?(method_name.to_sym) && base_object.method(method_name).parameters == [[:rest, :__spy_args], [:block, :block]]
-          base_object.send(method_name, __secret_method_key__)
-        end
+        Subroutine.get(base_object, method_name)
+      end
+
+      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)
       end
 
       spies.size > 1 ? spies : spies.first
@@ -234,26 +124,14 @@ class Spy
     def create_and_hook_spy(base_object, method_name, opts = {})
       case method_name
       when String, Symbol
-        spy = new(base_object, method_name).hook(opts)
-        all << spy
-        spy
+        Subroutine.new(base_object, method_name).hook(opts)
       when Hash
         method_name.map do |name, result|
           create_and_hook_spy(base_object, name, opts).and_return(result)
         end
       else
-        raise ArgumentError.new "#{method_name.class} is an invalid class, #on only accepts String, Symbol, and Hash"
-      end
-    end
-
-    def unhook_and_remove_spy(base_object, method_name)
-      removed_spies = []
-      all.delete_if do |spy|
-        if spy.base_object == base_object && spy.method_name == method_name
-          removed_spies << spy.unhook
-        end
+        raise ArgumentError.new "#{method_name.class} is an invalid input, #on only accepts String, Symbol, and Hash"
       end
-      removed_spies
     end
   end
 end