dchelimsky-rspec 1.1.10

data/lib/spec/matchers/throw_symbol.rb

@@ -0,0 +1,74 @@
+module Spec
+  module Matchers
+    
+    class ThrowSymbol #:nodoc:
+      def initialize(expected=nil)
+        @expected = expected
+        @actual = nil
+      end
+      
+      def matches?(given_proc)
+        begin
+          given_proc.call
+        rescue NameError => e
+          raise e unless e.message =~ /uncaught throw/
+          @actual = e.name.to_sym
+        ensure
+          if @expected.nil?
+            return @actual.nil? ? false : true
+          else
+            return @actual == @expected
+          end
+        end
+      end
+
+      def failure_message
+        if @actual
+          "expected #{expected}, got #{@actual.inspect}"
+        else
+          "expected #{expected} but nothing was thrown"
+        end
+      end
+      
+      def negative_failure_message
+        if @expected
+          "expected #{expected} not to be thrown"
+        else
+          "expected no Symbol, got :#{@actual}"
+        end
+      end
+      
+      def description
+        "throw #{expected}"
+      end
+      
+      private
+      
+        def expected
+          @expected.nil? ? "a Symbol" : @expected.inspect
+        end
+      
+    end
+ 
+    # :call-seq:
+    #   should throw_symbol()
+    #   should throw_symbol(:sym)
+    #   should_not throw_symbol()
+    #   should_not throw_symbol(:sym)
+    #
+    # Given a Symbol argument, matches if the given proc throws the specified Symbol.
+    #
+    # Given no argument, matches if a proc throws any Symbol.
+    #
+    # == Examples
+    #
+    #   lambda { do_something_risky }.should throw_symbol
+    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky)
+    #
+    #   lambda { do_something_risky }.should_not throw_symbol
+    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
+    def throw_symbol(sym=nil)
+      Matchers::ThrowSymbol.new(sym)
+    end
+  end
+end

data/lib/spec/matchers.rb

@@ -0,0 +1,162 @@
+require 'spec/matchers/simple_matcher'
+require 'spec/matchers/be'
+require 'spec/matchers/be_close'
+require 'spec/matchers/change'
+require 'spec/matchers/eql'
+require 'spec/matchers/equal'
+require 'spec/matchers/exist'
+require 'spec/matchers/has'
+require 'spec/matchers/have'
+require 'spec/matchers/include'
+require 'spec/matchers/match'
+require 'spec/matchers/raise_error'
+require 'spec/matchers/respond_to'
+require 'spec/matchers/satisfy'
+require 'spec/matchers/throw_symbol'
+require 'spec/matchers/operator_matcher'
+
+module Spec
+
+  # RSpec ships with a number of useful Expression Matchers. An Expression Matcher
+  # is any object that responds to the following methods:
+  #
+  #   matches?(actual)
+  #   failure_message
+  #   negative_failure_message #optional
+  #   description #optional
+  #
+  # See Spec::Expectations to learn how to use these as Expectation Matchers.
+  # See Spec::Mocks to learn how to use them as Mock Argument Constraints.
+  #
+  # == Predicates
+  #
+  # In addition to those Expression Matchers that are defined explicitly, RSpec will
+  # create custom Matchers on the fly for any arbitrary predicate, giving your specs
+  # a much more natural language feel. 
+  #
+  # A Ruby predicate is a method that ends with a "?" and returns true or false.
+  # Common examples are +empty?+, +nil?+, and +instance_of?+.
+  #
+  # All you need to do is write +should be_+ followed by the predicate without
+  # the question mark, and RSpec will figure it out from there. For example:
+  #
+  #   [].should be_empty => [].empty? #passes
+  #   [].should_not be_empty => [].empty? #fails
+  #
+  # In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
+  # and "be_an_", making your specs read much more naturally:
+  #
+  #   "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+  #
+  #   3.should be_a_kind_of(Fixnum) => 3.kind_of?(Numeric) #passes
+  #   3.should be_a_kind_of(Numeric) => 3.kind_of?(Numeric) #passes
+  #   3.should be_an_instance_of(Fixnum) => 3.instance_of?(Fixnum) #passes
+  #   3.should_not be_instance_of(Numeric) => 3.instance_of?(Numeric) #fails
+  #
+  # RSpec will also create custom matchers for predicates like +has_key?+. To
+  # use this feature, just state that the object should have_key(:key) and RSpec will
+  # call has_key?(:key) on the target. For example:
+  #
+  #   {:a => "A"}.should have_key(:a) => {:a => "A"}.has_key?(:a) #passes
+  #   {:a => "A"}.should have_key(:b) => {:a => "A"}.has_key?(:b) #fails
+  #
+  # You can use this feature to invoke any predicate that begins with "has_", whether it is
+  # part of the Ruby libraries (like +Hash#has_key?+) or a method you wrote on your own class.
+  #
+  # == Custom Expectation Matchers
+  #
+  # When you find that none of the stock Expectation Matchers provide a natural
+  # feeling expectation, you can very easily write your own.
+  #
+  # For example, imagine that you are writing a game in which players can
+  # be in various zones on a virtual board. To specify that bob should
+  # be in zone 4, you could say:
+  #
+  #   bob.current_zone.should eql(Zone.new("4"))
+  #
+  # But you might find it more expressive to say:
+  #
+  #   bob.should be_in_zone("4")
+  #
+  # and/or
+  #
+  #   bob.should_not be_in_zone("3")
+  #
+  # To do this, you would need to write a class like this:
+  #
+  #   class BeInZone
+  #     def initialize(expected)
+  #       @expected = expected
+  #     end
+  #     def matches?(target)
+  #       @target = target
+  #       @target.current_zone.eql?(Zone.new(@expected))
+  #     end
+  #     def failure_message
+  #       "expected #{@target.inspect} to be in Zone #{@expected}"
+  #     end
+  #     def negative_failure_message
+  #       "expected #{@target.inspect} not to be in Zone #{@expected}"
+  #     end
+  #   end
+  #
+  # ... and a method like this:
+  #
+  #   def be_in_zone(expected)
+  #     BeInZone.new(expected)
+  #   end
+  #
+  # And then expose the method to your specs. This is normally done
+  # by including the method and the class in a module, which is then
+  # included in your spec:
+  #
+  #   module CustomGameMatchers
+  #     class BeInZone
+  #       ...
+  #     end
+  #
+  #     def be_in_zone(expected)
+  #       ...
+  #     end
+  #   end
+  #
+  #   describe "Player behaviour" do
+  #     include CustomGameMatchers
+  #     ...
+  #   end
+  #
+  # or you can include in globally in a spec_helper.rb file <tt>require</tt>d
+  # from your spec file(s):
+  #
+  #   Spec::Runner.configure do |config|
+  #     config.include(CustomGameMatchers)
+  #   end
+  #
+  module Matchers
+    module ModuleMethods
+      attr_accessor :last_matcher, :last_should
+
+      def clear_generated_description
+        self.last_matcher = nil
+        self.last_should = nil
+      end
+      
+      def generated_description
+        last_should.nil? ? nil :
+          "#{last_should} #{last_matcher.respond_to?(:description) ? last_matcher.description : 'NO NAME'}"
+      end
+    end
+
+    extend ModuleMethods
+
+    def method_missing(sym, *args, &block) # :nodoc:
+      return Matchers::Be.new(sym, *args) if sym.starts_with?("be_")
+      return Matchers::Has.new(sym, *args) if sym.starts_with?("have_")
+      super
+    end
+
+    class MatcherError < StandardError
+    end
+    
+  end
+end

data/lib/spec/mocks/argument_constraints.rb

@@ -0,0 +1,165 @@
+module Spec
+  module Mocks
+
+    # ArgumentConstraints 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 constraints
+    # are all positional - they match against the arg in the given position.
+    module ArgumentConstraints
+
+      class AnyArgsConstraint
+        def description
+          "any args"
+        end
+      end
+
+      class AnyArgConstraint
+        def initialize(ignore)
+        end
+
+        def ==(other)
+          true
+        end
+      end
+
+      class NoArgsConstraint
+        def description
+          "no args"
+        end
+
+        def ==(args)
+          args == []
+        end
+      end
+
+      class RegexpConstraint
+        def initialize(regexp)
+          @regexp = regexp
+        end
+
+        def ==(value)
+          return value =~ @regexp unless value.is_a?(Regexp)
+          value == @regexp
+        end
+      end
+
+      class BooleanConstraint
+        def initialize(ignore)
+        end
+
+        def ==(value)
+          TrueClass === value || FalseClass === value
+        end
+      end
+
+      class HashIncludingConstraint
+        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 DuckTypeConstraint
+        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 MatcherConstraint
+        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
+
+      # :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
+        AnyArgsConstraint.new
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(anything())
+      #
+      # Passes as long as there is an argument.
+      def anything
+        AnyArgConstraint.new(nil)
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(no_args)
+      #
+      # Passes if no arguments are passed along with the message
+      def no_args
+        NoArgsConstraint.new
+      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)
+        DuckTypeConstraint.new(*args)
+      end
+
+      # :call-seq:
+      #   object.should_receive(:message).with(boolean())
+      #
+      # Passes if the argument is boolean.
+      def boolean
+        BooleanConstraint.new(nil)
+      end
+      
+      # :call-seq:
+      #   object.should_receive(:message).with(hash_including(:this => that))
+      #
+      # Passes if the argument is a hash that includes the specified key/value
+      # pairs. If the hash includes other keys, it will still pass.
+      def hash_including(expected={})
+        HashIncludingConstraint.new(expected)
+      end
+    end
+  end
+end

data/lib/spec/mocks/argument_expectation.rb

@@ -0,0 +1,49 @@
+module Spec
+  module Mocks
+    
+    class ArgumentExpectation
+      attr_reader :args
+      
+      def initialize(args, &block)
+        @args = args
+        @constraints_block = block
+        
+        if ArgumentConstraints::AnyArgsConstraint === args.first
+          @match_any_args = true
+        elsif ArgumentConstraints::NoArgsConstraint === args.first
+          @constraints = []
+        else
+          @constraints = args.collect {|arg| constraint_for(arg)}
+        end
+      end
+      
+      def constraint_for(arg)
+        return ArgumentConstraints::MatcherConstraint.new(arg)   if is_matcher?(arg)
+        return ArgumentConstraints::RegexpConstraint.new(arg) if arg.is_a?(Regexp)
+        return ArgumentConstraints::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? || constraints_block_matches?(given_args) || constraints_match?(given_args)
+      end
+      
+      def constraints_block_matches?(given_args)
+        @constraints_block ? @constraints_block.call(*given_args) : nil
+      end
+      
+      def constraints_match?(given_args)
+        @constraints == given_args
+      end
+      
+      def match_any_args?
+        @match_any_args
+      end
+      
+    end
+    
+  end
+end