ageweke-rspec 1.2.9

data/lib/spec/matchers/wrap_expectation.rb

@@ -0,0 +1,55 @@
+module Spec
+  module Matchers
+    # wraps an expectation in a block that will return true if the
+    # expectation passes and false if it fails (without bubbling up
+    # the failure).
+    #     
+    # This is intended to be used in the context of a simple matcher,
+    # and is especially useful for wrapping multiple expectations or
+    # one or more assertions from test/unit extensions when running
+    # with test/unit.
+    #
+    # == Examples
+    #
+    #   def eat_cheese(cheese)
+    #     simple_matcher do |mouse, matcher|
+    #       matcher.failure_message = "expected #{mouse} to eat cheese"
+    #       wrap_expectation do |matcher|
+    #         assert_eats_cheese(mouse)
+    #       end
+    #     end
+    #   end
+    #
+    #   describe Mouse do
+    #     it "eats cheese" do
+    #       Mouse.new.should eat_cheese
+    #     end
+    #   end
+    #
+    # You might be wondering "why would I do this if I could just say"
+    # assert_eats_cheese?", a fair question, indeed. You might prefer
+    # to replace the word assert with something more aligned with the
+    # rest of your code examples. You are using rspec, after all.
+    #
+    # The other benefit you get is that you can use the negative version
+    # of the matcher:
+    #
+    #   describe Cat do
+    #     it "does not eat cheese" do
+    #       Cat.new.should_not eat_cheese
+    #     end
+    #   end
+    #
+    # So in the event there is no assert_does_not_eat_cheese available,
+    # you're all set!
+    def wrap_expectation(matcher, &block)
+      begin
+        block.call(matcher)
+        return true
+      rescue Exception => e
+        matcher.failure_message = e.message
+        return false
+      end
+    end
+  end
+end

data/lib/spec/mocks.rb

@@ -0,0 +1,200 @@
+require 'spec/mocks/framework'
+require 'spec/mocks/extensions/object'
+
+module Spec
+  # == Mocks and Stubs
+  #
+  # RSpec will create Mock Objects and Stubs for you at runtime, or attach stub/mock behaviour
+  # to any of your real objects (Partial Mock/Stub). Because the underlying implementation
+  # for mocks and stubs is the same, you can intermingle mock and stub
+  # behaviour in either dynamically generated mocks or your pre-existing classes.
+  # There is a semantic difference in how they are created, however,
+  # which can help clarify the role it is playing within a given spec.
+  #
+  # == Mock Objects
+  # 
+  # Mocks are objects that allow you to set and verify expectations that they will
+  # receive specific messages during run time. They are very useful for specifying how the subject of
+  # the spec interacts with its collaborators. This approach is widely known as "interaction
+  # testing".
+  # 
+  # Mocks are also very powerful as a design tool. As you are
+  # driving the implementation of a given class, Mocks provide an anonymous
+  # collaborator that can change in behaviour as quickly as you can write an expectation in your
+  # spec. This flexibility allows you to design the interface of a collaborator that often
+  # does not yet exist. As the shape of the class being specified becomes more clear, so do the
+  # requirements for its collaborators - often leading to the discovery of new types that are
+  # needed in your system.
+  # 
+  # Read Endo-Testing[http://www.mockobjects.com/files/endotesting.pdf] for a much
+  # more in depth description of this process.
+  # 
+  # == Stubs
+  # 
+  # Stubs are objects that allow you to set "stub" responses to
+  # messages. As Martin Fowler points out on his site,
+  # mocks_arent_stubs[http://www.martinfowler.com/articles/mocksArentStubs.html].
+  # Paraphrasing Fowler's paraphrasing
+  # of Gerard Meszaros: Stubs provide canned responses to messages they might receive in a test, while
+  # mocks allow you to specify and, subsquently, verify that certain messages should be received during
+  # the execution of a test.
+  # 
+  # == Partial Mocks/Stubs
+  # 
+  # RSpec also supports partial mocking/stubbing, allowing you to add stub/mock behaviour
+  # to instances of your existing classes. This is generally
+  # something to be avoided, because changes to the class can have ripple effects on
+  # seemingly unrelated specs. When specs fail due to these ripple effects, the fact
+  # that some methods are being mocked can make it difficult to understand why a
+  # failure is occurring.
+  # 
+  # That said, partials do allow you to expect and
+  # verify interactions with class methods such as +#find+ and +#create+
+  # on Ruby on Rails model classes.
+  # 
+  # == Further Reading
+  # 
+  # There are many different viewpoints about the meaning of mocks and stubs. If you are interested
+  # in learning more, here is some recommended reading:
+  # 
+  # * Mock Objects: http://www.mockobjects.com/
+  # * Endo-Testing: http://www.mockobjects.com/files/endotesting.pdf
+  # * Mock Roles, Not Objects: http://www.mockobjects.com/files/mockrolesnotobjects.pdf
+  # * Test Double Patterns: http://xunitpatterns.com/Test%20Double%20Patterns.html
+  # * Mocks aren't stubs: http://www.martinfowler.com/articles/mocksArentStubs.html
+  #
+  # == Creating a Mock
+  #
+  # You can create a mock in any specification (or setup) using:
+  #
+  #   mock(name, options={})
+  #
+  # The optional +options+ argument is a +Hash+. Currently the only supported
+  # option is +:null_object+. Setting this to true instructs the mock to ignore
+  # any messages it hasn’t been told to expect – and quietly return itself. For example:
+  #
+  #   mock("person", :null_object => true)
+  #
+  # == Creating a Stub
+  #
+  # You can create a stub in any specification (or setup) using:
+  #
+  #   stub(name, stub_methods_and_values_hash)
+  #
+  # For example, if you wanted to create an object that always returns
+  # "More?!?!?!" to "please_sir_may_i_have_some_more" you would do this:
+  #
+  #   stub("Mr Sykes", :please_sir_may_i_have_some_more => "More?!?!?!")
+  #
+  # == Creating a Partial Mock
+  #
+  # You don't really "create" a partial mock, you simply add method stubs and/or
+  # mock expectations to existing classes and objects:
+  #
+  #   Factory.should_receive(:find).with(id).and_return(value)
+  #   obj.stub!(:to_i).and_return(3)
+  #   etc ...
+  #
+  # == Expecting Messages
+  #
+  #   my_mock.should_receive(:sym)
+  #   my_mock.should_not_receive(:sym)
+  #   
+  # == Expecting Arguments
+  #
+  #   my_mock.should_receive(:sym).with(*args)
+  #   my_mock.should_not_receive(:sym).with(*args)
+  #
+  # == Argument Matchers
+  #
+  # Arguments that are passed to #with are compared with actual arguments received
+  # using == by default. In cases in which you want to specify things about the arguments
+  # rather than the arguments themselves, you can use any of RSpec's Expression Matchers.
+  # They don't all make syntactic sense (they were primarily designed for use with
+  # Spec::Expectations), but you are free to create your own custom Spec::Matchers.
+  #
+  # Spec::Mocks does provide one additional Matcher method named #ducktype.
+  #
+  # In addition, Spec::Mocks adds some keyword Symbols that you can use to
+  # specify certain kinds of arguments:
+  #
+  #   my_mock.should_receive(:sym).with(no_args())
+  #   my_mock.should_receive(:sym).with(any_args())
+  #   my_mock.should_receive(:sym).with(1, kind_of(Numeric), "b") #2nd argument can any kind of Numeric
+  #   my_mock.should_receive(:sym).with(1, boolean(), "b") #2nd argument can true or false
+  #   my_mock.should_receive(:sym).with(1, /abc/, "b") #2nd argument can be any String matching the submitted Regexp
+  #   my_mock.should_receive(:sym).with(1, anything(), "b") #2nd argument can be anything at all
+  #   my_mock.should_receive(:sym).with(1, ducktype(:abs, :div), "b")
+  #                            #2nd argument can be object that responds to #abs and #div
+  #                                                                       
+  # == Receive Counts
+  #
+  #   my_mock.should_receive(:sym).once
+  #   my_mock.should_receive(:sym).twice
+  #   my_mock.should_receive(:sym).exactly(n).times
+  #   my_mock.should_receive(:sym).at_least(:once)
+  #   my_mock.should_receive(:sym).at_least(:twice)
+  #   my_mock.should_receive(:sym).at_least(n).times
+  #   my_mock.should_receive(:sym).at_most(:once)
+  #   my_mock.should_receive(:sym).at_most(:twice)
+  #   my_mock.should_receive(:sym).at_most(n).times
+  #   my_mock.should_receive(:sym).any_number_of_times
+  #
+  # == Ordering
+  #
+  #   my_mock.should_receive(:sym).ordered
+  #   my_mock.should_receive(:other_sym).ordered
+  #     #This will fail if the messages are received out of order
+  #
+  # == Setting Reponses
+  #
+  # Whether you are setting a mock expectation or a simple stub, you can tell the
+  # object precisely how to respond:
+  #
+  #   my_mock.should_receive(:sym).and_return(value)
+  #   my_mock.should_receive(:sym).exactly(3).times.and_return(value1, value2, value3)
+  #     # returns value1 the first time, value2 the second, etc
+  #   my_mock.should_receive(:sym).and_return { ... } #returns value returned by the block
+  #   my_mock.should_receive(:sym).and_raise(error)
+  #     #error can be an instantiated object or a class
+  #     #if it is a class, it must be instantiable with no args
+  #   my_mock.should_receive(:sym).and_throw(:sym)
+  #   my_mock.should_receive(:sym).and_yield(values,to,yield)
+  #   my_mock.should_receive(:sym).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+  #     # for methods that yield to a block multiple times
+  #
+  # Any of these responses can be applied to a stub as well, but stubs do
+  # not support any qualifiers about the message received (i.e. you can't specify arguments
+  # or receive counts):
+  #
+  #   my_mock.stub!(:sym).and_return(value)
+  #   my_mock.stub!(:sym).and_return(value1, value2, value3)
+  #   my_mock.stub!(:sym).and_raise(error)
+  #   my_mock.stub!(:sym).and_throw(:sym)
+  #   my_mock.stub!(:sym).and_yield(values,to,yield)
+  #   my_mock.stub!(:sym).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+  #
+  # == Arbitrary Handling
+  #
+  # Once in a while you'll find that the available expectations don't solve the
+  # particular problem you are trying to solve. Imagine that you expect the message
+  # to come with an Array argument that has a specific length, but you don't care
+  # what is in it. You could do this:
+  #
+  #   my_mock.should_receive(:sym) do |arg|
+  #     arg.should be_an_istance_of(Array)
+  #     arg.length.should == 7
+  #   end
+  #
+  # Note that this would fail if the number of arguments received was different from
+  # the number of block arguments (in this case 1).
+  #
+  # == Combining Expectation Details
+  #
+  # Combining the message name with specific arguments, receive counts and responses
+  # you can get quite a bit of detail in your expectations:
+  #
+  #   my_mock.should_receive(:<<).with("illegal value").once.and_raise(ArgumentError)
+  module Mocks
+  end
+end

data/lib/spec/mocks/argument_expectation.rb

@@ -0,0 +1,51 @@
+module Spec
+  module Mocks
+    
+    class ArgumentExpectation
+      attr_reader :args
+      
+      def initialize(args, &block)
+        @args = args
+        @matchers_block = block
+        @match_any_args = false
+        @matchers = nil
+        
+        if ArgumentMatchers::AnyArgsMatcher === args.first
+          @match_any_args = true
+        elsif ArgumentMatchers::NoArgsMatcher === args.first
+          @matchers = []
+        else
+          @matchers = args.collect {|arg| matcher_for(arg)}
+        end
+      end
+      
+      def matcher_for(arg)
+        return ArgumentMatchers::MatcherMatcher.new(arg)   if is_matcher?(arg)
+        return ArgumentMatchers::RegexpMatcher.new(arg) if arg.is_a?(Regexp)
+        return ArgumentMatchers::EqualityProxy.new(arg)
+      end
+      
+      def is_matcher?(obj)
+        return obj.respond_to?(:matches?) & obj.respond_to?(:description)
+      end
+      
+      def args_match?(given_args)
+        match_any_args? || matchers_block_matches?(given_args) || matchers_match?(given_args)
+      end
+      
+      def matchers_block_matches?(given_args)
+        @matchers_block ? @matchers_block.call(*given_args) : nil
+      end
+      
+      def matchers_match?(given_args)
+        @matchers == given_args
+      end
+      
+      def match_any_args?
+        @match_any_args
+      end
+      
+    end
+    
+  end
+end

data/lib/spec/mocks/argument_matchers.rb

@@ -0,0 +1,237 @@
+module Spec
+  module Mocks
+
+    # ArgumentMatchers are messages that you can include in message
+    # expectations to match arguments against a broader check than simple
+    # equality.
+    #
+    # With the exception of any_args() and no_args(), the matchers
+    # are all positional - they match against the arg in the given position.
+    module ArgumentMatchers
+
+      class AnyArgsMatcher
+        def description
+          "any args"
+        end
+      end
+
+      class NoArgsMatcher
+        def description
+          "no args"
+        end
+      end
+
+      class AnyArgMatcher
+        def initialize(ignore)
+        end
+
+        def ==(other)
+          true
+        end
+        
+        def description
+          "anything"
+        end
+      end
+
+      class RegexpMatcher
+        def initialize(regexp)
+          @regexp = regexp
+        end
+
+        def ==(value)
+          return value =~ @regexp unless value.is_a?(Regexp)
+          value == @regexp
+        end
+      end
+
+      class BooleanMatcher
+        def initialize(ignore)
+        end
+
+        def ==(value)
+          TrueClass === value || FalseClass === value
+        end
+      end
+
+      class HashIncludingMatcher
+        def initialize(expected)
+          @expected = expected
+        end
+
+        def ==(actual)
+          @expected.each do | key, value |
+            return false unless actual.has_key?(key) && value == actual[key]
+          end
+          true
+        rescue NoMethodError => ex
+          return false
+        end
+
+        def description
+          "hash_including(#{@expected.inspect.sub(/^\{/,"").sub(/\}$/,"")})"
+        end
+      end
+      
+      class HashNotIncludingMatcher
+        def initialize(expected)
+          @expected = expected
+        end
+
+        def ==(actual)
+          @expected.each do | key, value |
+            return false if actual.has_key?(key) && value == actual[key]
+          end
+          true
+        rescue NoMethodError => ex
+          return false
+        end
+
+        def description
+          "hash_not_including(#{@expected.inspect.sub(/^\{/,"").sub(/\}$/,"")})"
+        end
+      end
+      
+      class DuckTypeMatcher
+        def initialize(*methods_to_respond_to)
+          @methods_to_respond_to = methods_to_respond_to
+        end
+
+        def ==(value)
+          @methods_to_respond_to.all? { |sym| value.respond_to?(sym) }
+        end
+      end
+
+      class MatcherMatcher
+        def initialize(matcher)
+          @matcher = matcher
+        end
+
+        def ==(value)
+          @matcher.matches?(value)
+        end
+      end
+
+      class EqualityProxy
+        def initialize(given)
+          @given = given
+        end
+
+        def ==(expected)
+          @given == expected
+        end
+      end
+      
+      class InstanceOf
+        def initialize(klass)
+          @klass = klass
+        end
+        
+        def ==(actual)
+          actual.instance_of?(@klass)
+        end
+      end
+      
+      class KindOf
+        def initialize(klass)
+          @klass = klass
+        end
+        
+        def ==(actual)
+          actual.kind_of?(@klass)
+        end
+      end
+
+      # :call-seq:
+      #   object.should_receive(:message).with(no_args())
+      #
+      # Passes if no arguments are passed along with the message
+      def no_args
+        NoArgsMatcher.new
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(any_args())
+      #
+      # Passes if object receives :message with any args at all. This is
+      # really a more explicit variation of object.should_receive(:message)
+      def any_args
+        AnyArgsMatcher.new
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(anything())
+      #
+      # Passes as long as there is an argument.
+      def anything
+        AnyArgMatcher.new(nil)
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(duck_type(:hello))
+      #   object.should_receive(:message).with(duck_type(:hello, :goodbye))
+      #
+      # Passes if the argument responds to the specified messages.
+      #
+      # == Examples
+      #
+      #   array = []
+      #   display = mock('display')
+      #   display.should_receive(:present_names).with(duck_type(:length, :each))
+      #   => passes
+      def duck_type(*args)
+        DuckTypeMatcher.new(*args)
+      end
+
+      # :call-seq:
+      #   object.should_receive(:message).with(boolean())
+      #
+      # Passes if the argument is boolean.
+      def boolean
+        BooleanMatcher.new(nil)
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(hash_including(:key => val))
+      #   object.should_receive(:message).with(hash_including(:key))
+      #   object.should_receive(:message).with(hash_including(:key, :key2 => val2))
+      # Passes if the argument is a hash that includes the specified key(s) or key/value
+      # pairs. If the hash includes other keys, it will still pass.
+      def hash_including(*args)
+        HashIncludingMatcher.new(anythingize_lonely_keys(*args))
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(hash_not_including(:key => val))
+      #   object.should_receive(:message).with(hash_not_including(:key))
+      #   object.should_receive(:message).with(hash_not_including(:key, :key2 => :val2))
+      #
+      # Passes if the argument is a hash that doesn't include the specified key(s) or key/value
+      def hash_not_including(*args)
+        HashNotIncludingMatcher.new(anythingize_lonely_keys(*args))
+      end
+      
+      # Passes if arg.instance_of?(klass)
+      def instance_of(klass)
+        InstanceOf.new(klass)
+      end
+      
+      alias_method :an_instance_of, :instance_of
+      
+      # Passes if arg.kind_of?(klass)
+      def kind_of(klass)
+        KindOf.new(klass)
+      end
+      
+      alias_method :a_kind_of, :kind_of
+      
+    private
+      
+      def anythingize_lonely_keys(*args)
+        hash = args.last.class == Hash ? args.delete_at(-1) : {}
+        args.each { | arg | hash[arg] = anything }
+        hash
+      end
+    end
+  end
+end