rspec-instructure 1.3.3

data/lib/spec/matchers/respond_to.rb

@@ -0,0 +1,71 @@
+module Spec
+  module Matchers
+    
+    class RespondTo #:nodoc:
+      def initialize(*names)
+        @names = names
+        @expected_arity = nil
+        @names_not_responded_to = []
+      end
+      
+      def matches?(actual)
+        @actual = actual
+        @names.each do |name|
+          @names_not_responded_to << name unless actual.respond_to?(name) && matches_arity?(actual, name)
+        end
+        return @names_not_responded_to.empty?
+      end
+      
+      def failure_message_for_should
+        "expected #{@actual.inspect} to respond to #{@names_not_responded_to.collect {|name| name.inspect }.join(', ')}#{with_arity}"
+      end
+      
+      def failure_message_for_should_not
+        "expected #{@actual.inspect} not to respond to #{@names.collect {|name| name.inspect }.join(', ')}"
+      end
+      
+      def description
+        "respond to #{pp_names}#{with_arity}"
+      end
+      
+      def with(n)
+        @expected_arity = n
+        self
+      end
+      
+      def argument
+        self
+      end
+      alias :arguments :argument
+      
+    private
+      
+      def matches_arity?(actual, name)
+        @expected_arity.nil?? true : @expected_arity == actual.method(name).arity 
+      end
+      
+      def with_arity
+        @expected_arity.nil?? "" :
+          " with #{@expected_arity} argument#{@expected_arity == 1 ? '' : 's'}"
+      end
+      
+      def pp_names
+        # Ruby 1.9 returns the same thing for array.to_s as array.inspect, so just use array.inspect here
+        @names.length == 1 ? "##{@names.first}" : @names.inspect
+      end
+    end
+    
+    # :call-seq:
+    #   should respond_to(*names)
+    #   should_not respond_to(*names)
+    #
+    # Matches if the target object responds to all of the names
+    # provided. Names can be Strings or Symbols.
+    #
+    # == Examples
+    # 
+    def respond_to(*names)
+      Matchers::RespondTo.new(*names)
+    end
+  end
+end

data/lib/spec/matchers/satisfy.rb

@@ -0,0 +1,47 @@
+module Spec
+  module Matchers
+    
+    class Satisfy #:nodoc:
+      def initialize(&block)
+        @block = block
+      end
+      
+      def matches?(actual, &block)
+        @block = block if block
+        @actual = actual
+        @block.call(actual)
+      end
+      
+      def failure_message_for_should
+        "expected #{@actual} to satisfy block"
+      end
+
+      def failure_message_for_should_not
+        "expected #{@actual} not to satisfy block"
+      end
+    end
+    
+    # :call-seq:
+    #   should satisfy {}
+    #   should_not satisfy {}
+    #
+    # Passes if the submitted block returns true. Yields target to the
+    # block.
+    #
+    # Generally speaking, this should be thought of as a last resort when
+    # you can't find any other way to specify the behaviour you wish to
+    # specify.
+    #
+    # If you do find yourself in such a situation, you could always write
+    # a custom matcher, which would likely make your specs more expressive.
+    #
+    # == Examples
+    #
+    #   5.should satisfy { |n|
+    #     n > 3
+    #   }
+    def satisfy(&block)
+      Matchers::Satisfy.new(&block)
+    end
+  end
+end

data/lib/spec/matchers/simple_matcher.rb

@@ -0,0 +1,134 @@
+module Spec
+  module Matchers
+    class SimpleMatcher
+      attr_writer :failure_message, :negative_failure_message, :description
+      
+      def initialize(description, &match_block)
+        @description = description
+        @match_block = match_block
+        @failure_message = @negative_failure_message = nil
+      end
+
+      def matches?(given)
+        @given = given
+        case @match_block.arity
+        when 2
+          @match_block.call(@given, self)
+        else
+          @match_block.call(@given)
+        end
+      end
+      
+      def description
+        @description || explanation
+      end
+
+      def failure_message_for_should
+        @failure_message || (@description.nil? ? explanation : %[expected #{@description.inspect} but got #{@given.inspect}])
+      end
+
+      def failure_message_for_should_not
+        @negative_failure_message || (@description.nil? ? explanation : %[expected not to get #{@description.inspect}, but got #{@given.inspect}])
+      end
+
+      def explanation
+        "No description provided. See RDoc for simple_matcher()"
+      end
+    end
+  
+    # simple_matcher makes it easy for you to create your own custom matchers
+    # in just a few lines of code when you don't need all the power of a
+    # completely custom matcher object.
+    #
+    # The <tt>description</tt> argument will appear as part of any failure
+    # message, and is also the source for auto-generated descriptions.
+    #
+    # The <tt>match_block</tt> can have an arity of 1 or 2. The first block
+    # argument will be the given value. The second, if the block accepts it
+    # will be the matcher itself, giving you access to set custom failure
+    # messages in favor of the defaults.
+    #
+    # The <tt>match_block</tt> should return a boolean: <tt>true</tt>
+    # indicates a match, which will pass if you use <tt>should</tt> and fail
+    # if you use <tt>should_not</tt>. false (or nil) indicates no match,
+    # which will do the reverse: fail if you use <tt>should</tt> and pass if
+    # you use <tt>should_not</tt>.
+    #
+    # An error in the <tt>match_block</tt> will bubble up, resulting in a
+    # failure.
+    #
+    # == Example with default messages
+    #
+    #   def be_even
+    #     simple_matcher("an even number") { |given| given % 2 == 0 }
+    #   end
+    #                    
+    #   describe 2 do
+    #     it "should be even" do
+    #       2.should be_even
+    #     end
+    #   end
+    #
+    # Given an odd number, this example would produce an error message stating:
+    # expected "an even number", got 3.
+    #
+    # Unfortunately, if you're a fan of auto-generated descriptions, this will
+    # produce "should an even number." Not the most desirable result. You can
+    # control that using custom messages:
+    #
+    # == Example with custom messages
+    #
+    #   def rhyme_with(expected)
+    #     simple_matcher("rhyme with #{expected.inspect}") do |given, matcher|
+    #       matcher.failure_message = "expected #{given.inspect} to rhyme with #{expected.inspect}"
+    #       matcher.negative_failure_message = "expected #{given.inspect} not to rhyme with #{expected.inspect}"
+    #       given.rhymes_with? expected
+    #     end
+    #   end
+    #
+    #   # OR
+    #
+    #   def rhyme_with(expected)
+    #     simple_matcher do |given, matcher|
+    #       matcher.description = "rhyme with #{expected.inspect}"
+    #       matcher.failure_message = "expected #{given.inspect} to rhyme with #{expected.inspect}"
+    #       matcher.negative_failure_message = "expected #{given.inspect} not to rhyme with #{expected.inspect}"
+    #       given.rhymes_with? expected
+    #     end
+    #   end
+    #
+    #   describe "pecan" do
+    #     it "should rhyme with 'be gone'" do
+    #       nut = "pecan"
+    #       nut.extend Rhymer
+    #       nut.should rhyme_with("be gone")
+    #     end
+    #   end
+    #
+    # The resulting messages would be:
+    #   description:              rhyme with "be gone"
+    #   failure_message:          expected "pecan" to rhyme with "be gone"
+    #   negative failure_message: expected "pecan" not to rhyme with "be gone"
+    #
+    # == Wrapped Expectations
+    #
+    # Because errors will bubble up, it is possible to wrap other expectations
+    # in a SimpleMatcher.
+    #
+    #   def be_even
+    #     simple_matcher("an even number") { |given| (given % 2).should == 0 }
+    #   end
+    #
+    # BE VERY CAREFUL when you do this. Only use wrapped expectations for
+    # matchers that will always be used in only the positive
+    # (<tt>should</tt>) or negative (<tt>should_not</tt>), but not both.
+    # The reason is that is you wrap a <tt>should</tt> and call the wrapper
+    # with <tt>should_not</tt>, the correct result (the <tt>should</tt>
+    # failing), will fail when you want it to pass.
+    #
+    def simple_matcher(description=nil, &match_block)
+      Spec.deprecate("simple_matcher", "Matcher DSL (http://rspec.rubyforge.org/rspec/1.3.0/classes/Spec/Matchers.html)")
+      SimpleMatcher.new(description, &match_block)
+    end
+  end
+end

data/lib/spec/matchers/throw_symbol.rb

@@ -0,0 +1,100 @@
+module Spec
+  module Matchers
+
+    class ThrowSymbol #:nodoc:
+      def initialize(expected_symbol = nil, expected_arg=nil)
+        @expected_symbol = expected_symbol
+        @expected_arg = expected_arg
+        @caught_symbol = @caught_arg = nil
+      end
+
+      def matches?(given_proc)
+        begin
+          if @expected_symbol.nil?
+            given_proc.call
+          else
+            @caught_arg = catch :proc_did_not_throw_anything do
+              catch @expected_symbol do
+                given_proc.call
+                throw :proc_did_not_throw_anything, :nothing_thrown
+              end
+            end
+            @caught_symbol = @expected_symbol unless @caught_arg == :nothing_thrown
+          end
+
+        # Ruby 1.8 uses NameError with `symbol'
+        # Ruby 1.9 uses ArgumentError with :symbol
+        rescue NameError, ArgumentError => e
+          raise e unless e.message =~ /uncaught throw (`|\:)([a-zA-Z0-9_]*)(')?/
+          @caught_symbol = $2.to_sym
+        end
+        if @expected_symbol.nil?
+          !@caught_symbol.nil?
+        elsif @expected_arg.nil?
+          @caught_symbol == @expected_symbol
+        else
+          (@caught_symbol == @expected_symbol) & (@caught_arg == @expected_arg)
+        end
+      end
+
+      def failure_message_for_should
+        if @caught_symbol
+          "expected #{expected}, got #{@caught_symbol.inspect}"
+        else
+          "expected #{expected} but nothing was thrown"
+        end
+      end
+
+      def failure_message_for_should_not
+        if @expected_symbol
+          "expected #{expected} not to be thrown"
+        else
+          "expected no Symbol, got :#{@caught_symbol}"
+        end
+      end
+
+      def description
+        "throw #{expected}"
+      end
+
+      private
+
+        def expected
+          @expected_symbol.nil? ? "a Symbol" : "#{@expected_symbol.inspect}#{args}"
+        end
+
+        def args
+          @expected_arg.nil? ? "" : " with #{@expected_arg.inspect}"
+        end
+
+    end
+
+    # :call-seq:
+    #   should throw_symbol()
+    #   should throw_symbol(:sym)
+    #   should throw_symbol(:sym, arg)
+    #   should_not throw_symbol()
+    #   should_not throw_symbol(:sym)
+    #   should_not throw_symbol(:sym, arg)
+    #
+    # Given no argument, matches if a proc throws any Symbol.
+    #
+    # Given a Symbol, matches if the given proc throws the specified Symbol.
+    #
+    # Given a Symbol and an arg, matches if the given proc throws the
+    # specified Symbol with the specified arg.
+    #
+    # == Examples
+    #
+    #   lambda { do_something_risky }.should throw_symbol
+    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky)
+    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky, culprit)
+    #
+    #   lambda { do_something_risky }.should_not throw_symbol
+    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
+    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky, culprit)
+    def throw_symbol(expected_symbol = nil, expected_arg=nil)
+      Matchers::ThrowSymbol.new(expected_symbol, expected_arg)
+    end
+  end
+end

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