derickbailey-notamock 0.0.1

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,129 @@
+= 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.
+
+=== Yielding To Method Blocks
+
+There are many situation in which a stubbed method will be called with a block attached to it. For example, 
+if you are using the Net-SSH gem, you may have code like this:
+
+  Net::SSH.start(@server, @username, :password => @password) do |ssh|
+    ssh.exec!(cmd)
+  end
+
+To correctly stub and test the SSH.start method and the ssh.exec! method, you need to yield an object to the 
+block code, that supports a method called "exec!".
+
+To do this, you can call "yields(*args)" on a stubbed method. For example, you can can stub the SSH.start method
+and the exec! method, like this:
+
+  @sshstub = Net::SSH::Connection::Session.stub_instance(:exec! => nil)
+  Net::SSH.stub_method(:start).yields(@sshstub)
+
+When the .exec! method is called from withing the code block of SSH.start, the @sshstub object will be yielded to the
+block, allowing you to track the method, provide a stubbed block of code to execute, etc.
+
+In situations where you are calling .yields(*args), you can still provide a stub method block to replace the code
+that is executed when the stub method is called. There are multiple ways of doing this:
+
+  Net::SSH.stub_method(:start).yields(@sshstub) { puts 'this is the method stub code for .start' }
+  
+or
+
+  stub_block = lambda { puts 'this is the method stub code for .start' }
+  Net::SSH.stub_method(:start, &stub_block).yields(@sshstub)
+
+Both of these syntax forms will provide the exact same functionality - the block that puts the string of information
+will be executed when you call 'Net::SSH.start'
+
+== 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
+  
+==== Installation via Ruby Gems
+
+At the moment, there is no hosted gem for not_a_mock. However, you can easily build and install the gem from the source
+directly. To do so, follow these instructions:
+
+  1. clone the source code from git://github.com/derickbailey/not_a_mock.git
+  2. run 'rake jeweler:gemspec' in the root folder of your not_a_mock clone
+  3. run 'rake jeweler:build' in the root folder of your not_a_mock clone
+  4. run 'gem install -l pkg/NotAMock-#.#.#.gem' where #.#.# is the version number produced in step 3
+  
+After this you will be able to "include 'not_a_mock'" in your rspec tests, and configure rspec as shown for spec_helper.rb,
+above.
+
+== Contributing
+
+Send bugs, patches, and suggestions to Pete Yandell (pete@notahat.com)
+
+Thanks to Derick Bailey, 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
+
+namespace :jeweler do
+	require 'jeweler'	
+	Jeweler::Tasks.new do |gs|
+		gs.name = "derickbailey-notamock"
+		gs.summary = "A cleaner and DRYer alternative to mocking and stubbing with RSpec"
+		gs.description = "A cleaner and DRYer alternative to mocking and stubbing with RSpec, using Arrange-Act-Assert syntax"
+		gs.homepage = "http://github.com/derickbailey/not_a_mock"
+		gs.authors = ["Pete Yandell", "Derick Bailey"]
+		gs.has_rdoc = false	
+		gs.files.exclude("*.gemspec", ".gitignore")
+		gs.add_dependency('rspec', '>= 1.2.9')
+	end
+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 @@
+0.0.1

data/lib/not_a_mock.rb

@@ -0,0 +1,15 @@
+require 'not_a_mock/rspec_mock_framework_adapter'
+require 'not_a_mock/active_record_extensions'
+require 'not_a_mock/argument_constraint_extensions'
+require 'not_a_mock/call_recorder'
+require 'not_a_mock/matchers'
+require 'not_a_mock/matchers/anything_matcher'
+require 'not_a_mock/matchers/args_matcher'
+require 'not_a_mock/matchers/call_matcher'
+require 'not_a_mock/matchers/method_matcher'
+require 'not_a_mock/matchers/result_matcher'
+require 'not_a_mock/matchers/times_matcher'
+require 'not_a_mock/object_extensions'
+require 'not_a_mock/stubber'
+require 'not_a_mock/stubmethod'
+require 'not_a_mock/stub'

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,93 @@
+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)
+      end
+      object.instance_eval(<<-EOF, __FILE__, __LINE__)
+        def #{method} (*args, &block)
+          return_value = NotAMock::CallRecorder.instance.send(:record_and_send, self, :#{method}, args, &block)
+          return_value
+        end   
+      EOF
+    end
+
+    def record_and_send(object, method, args, &block)
+      result = object.send("__unlogged_#{method}", *args, &block)
+      @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.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