rspec 1.0.0 → 1.3.1

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

@@ -1,75 +1,100 @@
 module Spec
   module Matchers
-    
+
     class ThrowSymbol #:nodoc:
-      def initialize(expected=nil)
-        @expected = expected
+      def initialize(expected_symbol = nil, expected_arg=nil)
+        @expected_symbol = expected_symbol
+        @expected_arg = expected_arg
+        @caught_symbol = @caught_arg = nil
       end
-      
-      def matches?(proc)
+
+      def matches?(given_proc)
         begin
-          proc.call
-        rescue NameError => e
-          @actual = extract_sym_from_name_error(e)
-        ensure
-          if @expected.nil?
-            return @actual.nil? ? false : true
+          if @expected_symbol.nil?
+            given_proc.call
           else
-            return @actual == @expected
+            @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
-        if @actual
-          "expected #{expected}, got #{@actual.inspect}"
+      def failure_message_for_should
+        if @caught_symbol
+          "expected #{expected}, got #{@caught_symbol.inspect}"
         else
           "expected #{expected} but nothing was thrown"
         end
       end
-      
-      def negative_failure_message
-        if @expected
+
+      def failure_message_for_should_not
+        if @expected_symbol
           "expected #{expected} not to be thrown"
         else
-          "expected no Symbol, got :#{@actual}"
+          "expected no Symbol, got :#{@caught_symbol}"
         end
       end
-      
+
       def description
         "throw #{expected}"
       end
-      
+
       private
-      
+
         def expected
-          @expected.nil? ? "a Symbol" : @expected.inspect
+          @expected_symbol.nil? ? "a Symbol" : "#{@expected_symbol.inspect}#{args}"
         end
-      
-        def extract_sym_from_name_error(error)
-          return "#{error.message.split("`").last.split("'").first}".to_sym
+
+        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)
-    #
-    # Given a Symbol argument, matches if a proc throws the specified Symbol.
+    #   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)
-    def throw_symbol(sym=nil)
-      Matchers::ThrowSymbol.new(sym)
+    #   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/matchers.rb

@@ -1,17 +1,31 @@
+require 'spec/extensions/instance_exec'
+require 'spec/matchers/pretty'
+require 'spec/matchers/matcher'
+require 'spec/matchers/operator_matcher'
 require 'spec/matchers/be'
 require 'spec/matchers/be_close'
+require 'spec/matchers/be_instance_of'
+require 'spec/matchers/be_kind_of'
 require 'spec/matchers/change'
 require 'spec/matchers/eql'
 require 'spec/matchers/equal'
+require 'spec/matchers/errors'
+require 'spec/matchers/exist'
+require 'spec/matchers/generated_descriptions'
 require 'spec/matchers/has'
 require 'spec/matchers/have'
 require 'spec/matchers/include'
 require 'spec/matchers/match'
-require 'spec/matchers/raise_error'
+require 'spec/matchers/match_array'
+require 'spec/matchers/method_missing'
+require 'spec/matchers/raise_exception'
 require 'spec/matchers/respond_to'
 require 'spec/matchers/satisfy'
+require 'spec/matchers/simple_matcher'
 require 'spec/matchers/throw_symbol'
-require 'spec/matchers/operator_matcher'
+require 'spec/matchers/wrap_expectation'
+require 'spec/matchers/compatibility'
+require 'spec/matchers/dsl'
 
 module Spec
 
@@ -19,12 +33,21 @@ module Spec
   # is any object that responds to the following methods:
   #
   #   matches?(actual)
-  #   failure_message
-  #   negative_failure_message #optional
+  #   failure_message_for_should
+  #
+  # These methods are also part of the matcher protocol, but are optional:
+  #
+  #   does_not_match?(actual)
+  #   failure_message_for_should_not
   #   description #optional
   #
+  # These methods are from older versions of the protocol. They are still supported,
+  # but are not recommended:
+  #
+  #   failure_message          (use failure_message_for_should instead)
+  #   negative_failure_message (use failure_message_for_should_not instead)
+  #
   # 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
   #
@@ -61,14 +84,17 @@ module Spec
   # 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 Expression Matchers
+  # == Custom Matchers
+  #
+  # When you find that none of the stock Expectation Matchers provide a natural
+  # feeling expectation, you can very easily write your own using RSpec's matcher
+  # DSL or writing one from scratch.
   #
-  # When you find that none of the stock Expression Matchers provide a natural
-  # feeling expectation, you can very easily write your own.
+  # === Matcher DSL
   #
-  # 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:
+  # 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"))
   #
@@ -80,7 +106,61 @@ module Spec
   #
   #   bob.should_not be_in_zone("3")
   #
-  # To do this, you would need to write a class like this:
+  # You can create such a matcher like so:
+  #
+  #   Spec::Matchers.define :be_in_zone do |zone|
+  #     match do |player|
+  #       player.in_zone?(zone)
+  #     end
+  #   end
+  #
+  # This will generate a <tt>be_in_zone</tt> method that returns a matcher
+  # with logical default messages for failures. You can override the failure
+  # messages and the generated description as follows:
+  #
+  #   Spec::Matchers.define :be_in_zone do |zone|
+  #     match do |player|
+  #       player.in_zone?(zone)
+  #     end
+  #     failure_message_for_should do |player|
+  #       # generate and return the appropriate string.
+  #     end
+  #     failure_message_for_should_not do |player|
+  #       # generate and return the appropriate string.
+  #     end
+  #     description do
+  #       # generate and return the appropriate string.
+  #     end
+  #   end
+  #
+  # Each of the message-generation methods has access to the block arguments
+  # passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
+  # failure message methods (<tt>failure_message_for_should</tt> and
+  # <tt>failure_message_for_should_not</tt>) are passed the actual value (the
+  # receiver of <tt>should</tt> or <tt>should_not</tt>).
+  #
+  # You can also create matchers that obey a fluent interface using the
+  # <tt>chain</tt> method:
+  #
+  #   Spec::Matchers.define :tip do |expected_tip|
+  #     chain :on do |bill|
+  #       @bill = bill
+  #     end
+  #
+  #     match do |person|
+  #       person.tip_for(bill) == expected_tip
+  #     end
+  #   end
+  #
+  # This matcher can be used as follows:
+  #
+  #   describe Customer do
+  #     it { should tip(10).on(50) }
+  #   end
+  #
+  # === Custom Matcher from scratch
+  #
+  # You could also write a custom matcher from scratch, as follows:
   #
   #   class BeInZone
   #     def initialize(expected)
@@ -90,10 +170,10 @@ module Spec
   #       @target = target
   #       @target.current_zone.eql?(Zone.new(@expected))
   #     end
-  #     def failure_message
+  #     def failure_message_for_should
   #       "expected #{@target.inspect} to be in Zone #{@expected}"
   #     end
-  #     def negative_failure_message
+  #     def failure_message_for_should_not
   #       "expected #{@target.inspect} not to be in Zone #{@expected}"
   #     end
   #   end
@@ -122,37 +202,13 @@ module Spec
   #     include CustomGameMatchers
   #     ...
   #   end
-  module Matchers
-    module ModuleMethods
-      def description_generated(callback)
-        description_generated_callbacks << callback
-      end
-
-      def unregister_description_generated(callback)
-        description_generated_callbacks.delete(callback)
-      end
-
-      def generated_description=(name)
-        description_generated_callbacks.each do |callback|
-          callback.call(name)
-        end
-      end
-
-      private
-      def description_generated_callbacks
-        @description_generated_callbacks ||= []
-      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
+  #
+  # 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; end
+end

data/lib/spec/mocks/argument_expectation.rb

@@ -1,134 +1,50 @@
 module Spec
   module Mocks
-  
-    class MatcherConstraint
-      def initialize(matcher)
-        @matcher = matcher
-      end
-      
-      def matches?(value)
-        @matcher.matches?(value)
-      end
-    end
-      
-    class LiteralArgConstraint
-      def initialize(literal)
-        @literal_value = literal
-      end
-      
-      def matches?(value)
-        @literal_value == value
-      end
-    end
     
-    class RegexpArgConstraint
-      def initialize(regexp)
-        @regexp = regexp
-      end
-      
-      def matches?(value)
-        return value =~ @regexp unless value.is_a?(Regexp)
-        value == @regexp
-      end
-    end
-    
-    class AnyArgConstraint
-      def initialize(ignore)
-      end
-      
-      def matches?(value)
-        true
-      end
-    end
-    
-    class NumericArgConstraint
-      def initialize(ignore)
-      end
-      
-      def matches?(value)
-        value.is_a?(Numeric)
-      end
-    end
-    
-    class BooleanArgConstraint
-      def initialize(ignore)
-      end
-      
-      def matches?(value)
-        return true if value.is_a?(TrueClass)
-        return true if value.is_a?(FalseClass)
-        false
-      end
-    end
-    
-    class StringArgConstraint
-      def initialize(ignore)
-      end
-      
-      def matches?(value)
-        value.is_a?(String)
-      end
-    end
-    
-    class DuckTypeArgConstraint
-      def initialize(*methods_to_respond_to)
-        @methods_to_respond_to = methods_to_respond_to
-      end
-  
-      def matches?(value)
-        @methods_to_respond_to.all? { |sym| value.respond_to?(sym) }
-      end
-      
-      def description
-        "duck_type"
-      end
-    end
-
     class ArgumentExpectation
       attr_reader :args
-      @@constraint_classes = Hash.new { |hash, key| LiteralArgConstraint}
-      @@constraint_classes[:anything] = AnyArgConstraint
-      @@constraint_classes[:numeric] = NumericArgConstraint
-      @@constraint_classes[:boolean] = BooleanArgConstraint
-      @@constraint_classes[:string] = StringArgConstraint
       
-      def initialize(args)
+      def initialize(args, &block)
         @args = args
-        if [:any_args] == args then @expected_params = nil
-        elsif [:no_args] == args then @expected_params = []
-        else @expected_params = process_arg_constraints(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 process_arg_constraints(constraints)
-        constraints.collect do |constraint| 
-          convert_constraint(constraint)
-        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 convert_constraint(constraint)
-        return @@constraint_classes[constraint].new(constraint) if constraint.is_a?(Symbol)
-        return MatcherConstraint.new(constraint) if is_matcher?(constraint)
-        return RegexpArgConstraint.new(constraint) if constraint.is_a?(Regexp)
-        return LiteralArgConstraint.new(constraint)
+      def is_matcher?(obj)
+        return obj.respond_to?(:matches?) & obj.respond_to?(:description)
       end
       
-      def is_matcher?(obj)
-        return obj.respond_to?(:matches?) && obj.respond_to?(:description)
+      def args_match?(given_args)
+        match_any_args? || matchers_block_matches?(given_args) || matchers_match?(given_args)
       end
       
-      def check_args(args)
-        return true if @expected_params.nil?
-        return true if @expected_params == args
-        return constraints_match?(args)
+      def matchers_block_matches?(given_args)
+        @matchers_block ? @matchers_block.call(*given_args) : nil
       end
       
-      def constraints_match?(args)
-        return false if args.length != @expected_params.length
-        @expected_params.each_index { |i| return false unless @expected_params[i].matches?(args[i]) }
-        return true
+      def matchers_match?(given_args)
+        @matchers == given_args
       end
-  
+      
+      def match_any_args?
+        @match_any_args
+      end
+      
     end
     
   end