not_a_mock 1.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+rdoc
+coverage
+pkg

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Peter Yandell
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,82 @@
+= Not A Mock
+
+A cleaner and DRYer alternative to mocking and stubbing with RSpec.
+
+http://notahat.com/not_a_mock
+
+== A Quick Introduction
+
+=== Mocking (Not)
+
+When you're setting up for a spec, you can ask that method calls on an object be recorded:
+
+  object.track_methods(:name, :length)
+  
+Once your code has run, you can make assertions about what methods were called, what arguments
+they took, their results, etc.
+
+  object.should have_received(:length).without_args.and_returned(42)
+  object.should have_received(:name).twice
+  
+See NotAMock::Matchers for an explanation of the available assertions, plus
+Object#track_methods and Object#untrack_methods.
+  
+=== Stubbing
+
+==== Stubbing Methods
+
+You can replace a method on an object with a stub version like this:
+
+  object.stub_method(:method => return_value)
+  
+Any call to +method+ after this will return +return_value+ without invoking
+the method's usual code.
+  
+Calls to stub methods are recorded as if you had called +track_methods+
+on them, so you can make assertions about them as shown above.
+  
+See Object#stub_methods, Object#unstub_methods.
+
+==== Stubbing Objects
+
+You can also replace an entire object with a stub version like this:
+
+  my_object = MyClass.stub_instance(:method_a => return_value, :method_b => return_value, ...)
+
+The returned +my_object+ is a stub instance of MyClass with the given methods
+defined to provide the corresponding return values.
+  
+See Object.stub_instance.
+
+==== Stubbing ActiveRecord Instances
+
+When you call +stub_instance+ on an ActiveRecord::Base subclass,
+Not A Mock automatically provides an +id+ method and generates an
+id for the object.
+
+== Installation
+
+(The following describes using NotAMock with Rails. It should also be possible
+to use it outside of Rails, but I haven't tried it.)
+
+First, install the rspec and rspec_on_rails plugins:
+
+  ruby script/plugin install http://rspec.rubyforge.org/svn/tags/CURRENT/rspec
+  ruby script/plugin install http://rspec.rubyforge.org/svn/tags/CURRENT/rspec_on_rails
+  ruby script/generate rspec
+
+(See http://rspec.info/documentation/rails/install.html for more details.)
+  
+Second, install the not_a_mock plugin:
+
+  ruby script/plugin install git://github.com/notahat/not_a_mock.git
+
+Finally, add the following to your project's spec/spec_helper.rb:
+
+  config.mock_with NotAMock::RspecMockFrameworkAdapter
+
+== Contributing
+
+Send bugs, patches, and suggestions to Pete Yandell (pete@notahat.com)
+
+Thanks to Pat Allan and Steve Hayes for contributing patches.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+
+desc "Default: run specs"
+task :default => :spec
+
+desc "Run all the specs for the notamock plugin."
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--colour']
+  t.rcov = true
+end
+
+desc "Generate documentation for the notamock plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'NotAMock'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('MIT-LICENSE')
+  rdoc.rdoc_files.include('TODO')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "not_a_mock"
+    gemspec.summary = "A cleaner and DRYer alternative to mocking and stubbing with RSpec"
+    gemspec.email = "pete@notahat.com"
+    gemspec.homepage = "http://notahat.com/not_a_mock"
+    gemspec.authors = ["Pete Yandell"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end

data/TODO

@@ -0,0 +1,49 @@
+== To Do
+
+=== Recording calls that throw exceptions
+
+Currently calls to methods that throw exceptions are not recorded. It would
+be good if they were, and if assertions could be made against them, e.g.
+
+  object.should have_received(:gsub).and_raised(ArgumentError)
+  
+=== Stubbing and recording of methods that take blocks
+
+You can't stub or record calls for methods that take blocks. This is very
+difficult to fix in Ruby 1.8, but will be much easier in 1.9.
+
+=== Better Error Messages
+
+Error messages are pretty smart already. If I call:
+
+  object.should have_received(:gsub).with("Hello", "Goodbye").and_returned("Goodbye, world!")
+  
+I might get an error like:
+
+  Object received gsub, but not with arguments ["Hello", "Goodbye"].
+
+It would be much more useful if the error message told you the arguments
+it actually received as well.
+  
+=== Order Assertions
+
+I should be able to write something like this to assert that the calls
+happened in order:
+
+  in_order do
+    object_a.should have_received(:message_a)
+    object_b.should have_received(:message_b)
+    object_a.should have_received(:message_c)
+  end
+
+=== Smarter ActiveRecord stubbing
+
+I often find myself doing something like this before a test:
+
+  @comment  = Comment.stub_object(:body => "Great!")
+  @comments = Object.stub_object(:find => [@comment])
+  @article  = Article.stub_object(:title => "Hello, world!", :comments => @comments)
+  Article.stub_method(:find => @article)
+
+I'd like to find a way to make this neater, auto-generate the stub
+relationship, etc.

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/not_a_mock/active_record_extensions.rb

@@ -0,0 +1,12 @@
+module ActiveRecord # :nodoc:
+  class Base
+    
+    def self.stub_instance(methods = {})
+      @@__stub_object_id ||= 1000
+      @@__stub_object_id += 1
+      methods = methods.merge(:id => @@__stub_object_id, :to_param => @@__stub_object_id.to_s)
+      NotAMock::Stub.new(self, methods)
+    end
+    
+  end
+end

data/lib/not_a_mock/argument_constraint_extensions.rb

@@ -0,0 +1,32 @@
+require 'set'
+
+module Spec #:nodoc:
+  module Mocks #:nodoc:
+    class AnyOrderArgConstraint #:nodoc:
+      def initialize(array)
+        @array = array
+      end
+      
+      def ==(arg)
+        Set.new(@array) == Set.new(arg)
+      end
+        
+      def inspect
+        "in_any_order(#{@array.inspect})"
+      end
+    end
+    
+    module ArgumentMatchers #:nodoc:
+      class AnyArgMatcher #:nodoc:
+        def inspect
+          'anything'
+        end
+      end
+
+      def in_any_order(array)
+        Spec::Mocks::AnyOrderArgConstraint.new(array)
+      end
+    end
+
+  end
+end

data/lib/not_a_mock/call_recorder.rb

@@ -0,0 +1,88 @@
+require 'singleton'
+require 'not_a_mock/object_extensions'
+
+module NotAMock
+  # The CallRecorder is a singleton that keeps track of all the call
+  # recording hooks installed, and keeps a central record of calls.
+  class CallRecorder
+    include Singleton
+  
+    def initialize
+      @calls = []
+      @tracked_methods = []
+    end
+  
+    # An array of recorded calls in chronological order.
+    #
+    # Each call is represented by a hash, in this format:
+    #   { :object => example_object, :method => :example_method, :args => ["example argument"], :result => "example result" }
+    attr_reader :calls
+    
+    # Return an array of all the calls made to any method of +object+, in chronological order.
+    def calls_by_object(object)
+      @calls.select {|call| call[:object] == object }
+    end
+    
+    # Return an array of all the calls made to +method+ of +object+, in chronological order.
+    def calls_by_object_and_method(object, method)
+      @calls.select {|call| call[:object] == object && call[:method] == method }
+    end
+  
+    # Patch +object+ so that future calls to +method+ will be recorded.
+    #
+    # You should call Object#track_methods rather than calling this directly.
+    def track_method(object, method) #:nodoc:
+      unless @tracked_methods.include?([object, method])
+        @tracked_methods << [object, method]
+        add_hook(object, method)
+      end
+    end
+  
+    # Remove the patch from +object+ so that future calls to +method+
+    # will not be recorded.
+    #
+    # You should call Object#track_methods rather than calling this directly.
+    def untrack_method(object, method) #:nodoc:
+      if @tracked_methods.delete([object, method])
+        remove_hook(object, method)
+      end
+    end
+    
+    # Stop recording all calls.
+    def untrack_all
+      @tracked_methods.each do |object, method|
+        remove_hook(object, method) 
+      end
+      @tracked_methods = []
+    end
+    
+    # Remove all patches so that calls are no longer recorded, and clear the call log.
+    def reset
+      untrack_all
+      @calls = []
+    end
+
+  private
+
+    def add_hook(object, method)
+      object.meta_eval do
+        alias_method("__unlogged_#{method}", method)
+        define_method(method) {|*args| CallRecorder.instance.send(:record_and_send, self, method, args) }
+      end
+    end
+
+    def record_and_send(object, method, args)
+      result = object.send("__unlogged_#{method}", *args)
+      @calls << { :object => object, :method => method, :args => args, :result => result }
+      result
+    end
+  
+    def remove_hook(object, method)
+      object.meta_eval do
+        alias_method(method, "__unlogged_#{method}")
+        remove_method("__unlogged_#{method}")
+      end
+    end
+
+  end
+end

data/lib/not_a_mock/matchers/anything_matcher.rb

@@ -0,0 +1,28 @@
+require 'not_a_mock/matchers/call_matcher'
+
+module NotAMock
+  module Matchers
+    # Matcher for
+    #   object.should have_been_called
+    class AnythingMatcher < CallMatcher
+  
+      def initialize(parent = nil)
+        super parent
+      end
+  
+      def matches_without_parents?
+        @calls = CallRecorder.instance.calls_by_object(@object)
+        !@calls.empty?
+      end
+  
+      def failure_message_without_parents
+        if matched?
+          " was called"
+        else
+          " was never called"
+        end
+      end
+  
+    end
+  end
+end

data/lib/not_a_mock/matchers/args_matcher.rb

@@ -0,0 +1,74 @@
+require 'not_a_mock/matchers/call_matcher'
+
+module NotAMock
+  module Matchers
+    # Matcher for
+    #  with(...)
+    #
+    # == Argument Matchers
+    #
+    # Not A Mock supports the use of RSpec's patterns for argument matching
+    # in mocks, and extends them. The most useful are listed below.
+    #
+    # === Anything Matcher
+    #
+    # The +anything+ pattern will match any value. For example:
+    #
+    #   object.should have_received(:message).with(1, anything, 3)
+    #
+    # will match the following calls:
+    #
+    #   object.message(1, 2, 3)
+    #   object.message(1, 'Boo!', 3)
+    #
+    # but not:
+    #
+    #    object.message(3, 2, 1)
+    #    object.message(1, 2, 3, 4)
+    #
+    # === In Any Order Matcher
+    #
+    # The +in_any_order+ pattern will match an array argument, but won't care
+    # about order of elements in the array. For example:
+    #
+    #   object.should have_received(:message).with(in_any_order([3, 2, 1]))
+    #
+    # will match the following calls:
+    #
+    #   object.message([3, 2, 1])
+    #   object.message([1, 2, 3])
+    #
+    # but not:
+    #
+    #   object.message([1, 2, 3, 4])
+    class ArgsMatcher < CallMatcher
+  
+      def initialize(args, parent = nil)
+        super parent
+        @args = args
+      end
+  
+      def matches_without_parents?
+        @calls = @parent.calls.select {|entry| @args == entry[:args] }
+        !@calls.empty?
+      end
+  
+      def failure_message_without_parents
+        if matched?
+          if @args.empty?
+            ", without args"
+          else
+            ", with args #{@args.inspect}"
+          end
+        else
+          if @args.empty?
+            ", but not without args"
+          else
+            ", but not with args #{@args.inspect}"
+          end
+        end
+      end
+  
+    end
+  end
+end

data/lib/not_a_mock/matchers/call_matcher.rb

@@ -0,0 +1,64 @@
+module NotAMock
+  module Matchers
+    class CallMatcher
+  
+      def initialize(parent = nil)
+        @parent = parent
+      end
+  
+      def matches?(object)
+        @object = object
+        @matched = parent_matches? && matches_without_parents?
+      end
+  
+      def matched?; @matched end
+      
+      attr_reader :calls
+  
+      def failure_message
+        if parent_matched?
+          parent_failure_message + failure_message_without_parents
+        else
+          parent_failure_message
+        end
+      end
+      
+      def negative_failure_message
+        failure_message
+      end
+
+      def with(*args)
+        ArgsMatcher.new(args, self)
+      end
+  
+      def without_args
+        ArgsMatcher.new([], self)
+      end
+  
+      def and_returned(result)
+        ResultMatcher.new(result, self)
+      end
+  
+      def exactly(n)
+        TimesMatcher.new(n, self)
+      end
+      def once;  exactly(1) end
+      def twice; exactly(2) end
+  
+    protected
+    
+      def parent_matches?
+        @parent.nil? || @parent.matches?(@object)
+      end
+      
+      def parent_matched?
+        @parent.nil? || @parent.matched?
+      end
+      
+      def parent_failure_message
+        @parent ? @parent.failure_message : @object.inspect
+      end
+
+    end
+  end
+end

data/lib/not_a_mock/matchers/method_matcher.rb

@@ -0,0 +1,29 @@
+require 'not_a_mock/matchers/call_matcher'
+
+module NotAMock
+  module Matchers
+    # Matcher for
+    #   object.should have_received(...)
+    class MethodMatcher < CallMatcher
+  
+      def initialize(method, parent = nil)
+        super parent
+        @method = method
+      end
+  
+      def matches_without_parents?
+        @calls = CallRecorder.instance.calls_by_object_and_method(@object, @method)
+        !@calls.empty?
+      end
+  
+      def failure_message_without_parents
+        if matched?
+          " received #{@method}"
+        else
+          " didn't receive #{@method}"
+        end
+      end
+  
+    end
+  end
+end

data/lib/not_a_mock/matchers/result_matcher.rb

@@ -0,0 +1,29 @@
+require 'not_a_mock/matchers/call_matcher'
+
+module NotAMock
+  module Matchers
+    # Matcher for
+    #   and_returned(...)
+    class ResultMatcher < CallMatcher
+  
+      def initialize(result, parent = nil)
+        super parent
+        @result = result
+      end
+  
+      def matches_without_parents?
+        @calls = @parent.calls.select {|entry| entry[:result] == @result }
+        !@calls.empty?
+      end
+  
+      def failure_message_without_parents
+        if matched?
+          ", and returned #{@result.inspect}"
+        else
+          ", but didn't return #{@result.inspect}"
+        end
+      end
+  
+    end
+  end
+end

data/lib/not_a_mock/matchers/times_matcher.rb

@@ -0,0 +1,46 @@
+require 'not_a_mock/matchers/call_matcher'
+
+module NotAMock
+  module Matchers
+    # Matcher for +once+, +twice+, and
+    #   exactly(n).times
+    class TimesMatcher < CallMatcher
+  
+      def initialize(times, parent = nil)
+        super parent
+        @times = times
+      end
+  
+      def matches_without_parents?
+        @calls = @parent.calls
+        @calls.length == @times
+      end
+  
+      def failure_message_without_parents
+        if matched?
+          ", #{times_in_english(@parent.calls.length)}"
+        else
+          ", but #{times_in_english(@parent.calls.length, true)}"
+        end
+      end
+  
+      def times
+        self
+      end
+  
+    private
+
+      def times_in_english(times, only = false)
+        case times
+          when 1
+            only ? "only once" : "once"
+          when 2
+            "twice"
+          else
+            "#{times} times"
+        end
+      end
+  
+    end
+  end
+end

data/lib/not_a_mock/matchers.rb

@@ -0,0 +1,68 @@
+module NotAMock
+  # == Message Assertions
+  # 
+  # You can assert that an object should have received particular messages:
+  # 
+  #   object.should have_received(:message)
+  #   object.should_not have_received(:message)
+  # 
+  # Further restrictions cannot be added after +should_not have_received+.
+  # 
+  # You can also make general assertions about whether an object should have
+  # received any messages:
+  # 
+  #   object.should have_been_called
+  #   object.should_not have_been_called
+  # 
+  # == Argument Assertions
+  # 
+  # You can assert that a call was made with or without arguments:
+  # 
+  #   object.should have_received(:message).with(arg1, arg2, ...)
+  #   object.should have_received(:message).without_args
+  #
+  # See NotAMock::Matchers::ArgsMatcher for more information.
+  # 
+  # == Return Value Assertions
+  # 
+  #   object.should have_received(:message).and_returned(return_value)
+  #   object.should have_received(:message).with(arg1, arg2, ...).and_returned(return_value)
+  # 
+  # == Count Assertions
+  # 
+  #   object.should have_received(:message).once
+  #   object.should have_received(:message).with(arg1, arg2, ...).twice
+  #   object.should have_received(:message).with(arg1, arg2, ...).and_returned(return_value).exactly(n).times
+  #   object.should have_been_called.exactly(n).times
+  # 
+  # Any count specifier must go at the end of the expression.
+  # 
+  # The exception to this rule is +once+, which allows things like this:
+  # 
+  #   object.should have_received(:message).once.with(arg1, arg2, ...).and_returned(return_value)
+  # 
+  # which verifies that +message+ was called only once, and that call had
+  # the given arguments and return value.
+  # 
+  # Note that this is subtly different from:
+  # 
+  #   object.should have_received(:message).with(arg1, arg2, ...).and_returned(return_value).once
+  # 
+  # which verifies that +message+ was called with the given arguments and
+  # return value only once. It may, however, have been called with different
+  # arguments and return value at other times.
+  #
+  # == Assertion Failures
+  #
+  # FIXME: Write some docs about the nice error messages.
+  module Matchers
+  end
+end
+
+def have_been_called
+  NotAMock::Matchers::AnythingMatcher.new
+end
+
+def have_received(method)
+  NotAMock::Matchers::MethodMatcher.new(method)
+end