rspec-expectations 2.99.2 → 3.0.0.beta1

data/lib/rspec/matchers/built_in/throw_symbol.rb

@@ -2,8 +2,6 @@ module RSpec
   module Matchers
     module BuiltIn
       class ThrowSymbol
-        include MatchAliases
-
         def initialize(expected_symbol = nil, expected_arg=nil)
           @expected_symbol = expected_symbol
           @expected_arg = expected_arg
@@ -53,6 +51,7 @@ module RSpec
             end
           end
         end
+        alias == matches?
 
         def failure_message_for_should
           "expected #{expected} to be thrown, got #{caught}"
@@ -66,14 +65,7 @@ module RSpec
           "throw #{expected}"
         end
 
-        # @api private
-        # Indicates this matcher matches against a block.
-        # @return [True]
-        def supports_block_expectations?
-          true
-        end
-
-      private
+        private
 
         def expected(symbol_desc = 'a Symbol')
           throw_description(@expected_symbol || symbol_desc, @expected_arg)

data/lib/rspec/matchers/built_in/yield.rb

@@ -24,6 +24,7 @@ module RSpec
           Proc.new do |*args|
             probe.num_yields += 1
             probe.yielded_args << args
+            nil # to indicate the block does not return a meaningful value
           end
         end
 
@@ -121,12 +122,7 @@ module RSpec
           end
         end
 
-        # @private
-        def supports_block_expectations?
-          true
-        end
-
-      private
+        private
 
         def set_expected_yields_count(relativity, n)
           @expectation_type = relativity
@@ -174,11 +170,6 @@ module RSpec
           "expected given block not to yield with no arguments, but did"
         end
 
-        # @private
-        def supports_block_expectations?
-          true
-        end
-
       private
 
         def failure_reason
@@ -191,8 +182,6 @@ module RSpec
       end
 
       class YieldWithArgs
-        include MatchAliases
-
         def initialize(*args)
           @expected = args
         end
@@ -202,6 +191,7 @@ module RSpec
           @actual = @probe.single_yield_args
           @probe.yielded_once?(:yield_with_args) && args_match?
         end
+        alias == matches?
 
         def failure_message_for_should
           "expected given block to yield with arguments, but #{positive_failure_reason}"
@@ -217,11 +207,6 @@ module RSpec
           desc
         end
 
-        # @private
-        def supports_block_expectations?
-          true
-        end
-
       private
 
         def positive_failure_reason
@@ -267,8 +252,6 @@ module RSpec
       end
 
       class YieldSuccessiveArgs
-        include MatchAliases
-
         def initialize(*args)
           @expected = args
         end
@@ -278,6 +261,7 @@ module RSpec
           @actual = @probe.successive_yield_args
           args_match?
         end
+        alias == matches?
 
         def failure_message_for_should
           "expected given block to yield successively with arguments, but yielded with unexpected arguments" +
@@ -297,11 +281,6 @@ module RSpec
           desc
         end
 
-        # @private
-        def supports_block_expectations?
-          true
-        end
-
       private
 
         def args_match?

data/lib/rspec/matchers/compatibility.rb

@@ -1,12 +1,12 @@
 RSpec::Matchers.constants.each do |c|
   if Class === (klass = RSpec::Matchers.const_get(c))
     if klass.public_instance_methods.any? {|m| ['failure_message_for_should',:failure_message_for_should].include?(m)}
-      klass.class_eval do
+      klass.class_exec do
         alias_method :failure_message, :failure_message_for_should
       end
     end
     if klass.public_instance_methods.any? {|m| ['failure_message_for_should_not',:failure_message_for_should_not].include?(m)}
-      klass.class_eval do
+      klass.class_exec do
         alias_method :negative_failure_message, :failure_message_for_should_not
       end
     end

data/lib/rspec/{expectations → matchers}/configuration.rb

@@ -1,7 +1,7 @@
 require 'rspec/expectations/syntax'
 
 module RSpec
-  module Expectations
+  module Matchers
     # Provides configuration options for rspec-expectations.
     class Configuration
       # Configures the supported syntax.
@@ -87,6 +87,11 @@ module RSpec
         end
       end
 
+      def reset_syntaxes_to_default
+        self.syntax = [:should, :expect]
+        RSpec::Expectations::Syntax.warn_about_should!
+      end
+
       # @api private
       NullBacktraceFormatter = Module.new do
         def self.format_backtrace(backtrace)
@@ -94,17 +99,15 @@ module RSpec
         end
       end
     end
-  end
 
-  module Matchers
     # The configuration object
-    # @return [RSpec::Expectations::Configuration] the configuration object
+    # @return [RSpec::Matchers::Configuration] the configuration object
     def self.configuration
-      @configuration ||= Expectations::Configuration.new
+      @configuration ||= Configuration.new
     end
 
     # set default syntax
-    configuration.syntax = [:expect, :should]
+    configuration.reset_syntaxes_to_default
   end
 end
 

data/lib/rspec/matchers/dsl.rb

@@ -4,11 +4,9 @@ module RSpec
       # Defines a custom matcher.
       # @see RSpec::Matchers
       def define(name, &declarations)
-        matcher_template = RSpec::Matchers::DSL::Matcher.new(name, &declarations)
         define_method name do |*expected|
-          matcher = matcher_template.for_expected(*expected)
-          @matcher_execution_context ||= self
-          matcher.instance_variable_set(:@matcher_execution_context, @matcher_execution_context)
+          matcher = RSpec::Matchers::DSL::Matcher.new(name, declarations, *expected)
+          matcher.matcher_execution_context = @matcher_execution_context ||= self
           matcher
         end
       end

data/lib/rspec/matchers/matcher.rb

@@ -1,115 +1,18 @@
 require 'set'
-require 'rspec/matchers/differentiate_block_method_types'
 
 module RSpec
   module Matchers
     module DSL
-      # Provides the context in which the block passed to RSpec::Matchers.define
-      # will be evaluated.
-      class Matcher
-        include RSpec::Matchers::Extensions::InstanceEvalWithArgs
-        include RSpec::Matchers::Pretty
-        include RSpec::Matchers
-
-        attr_reader :actual, :rescued_exception
-
-        # @api private
-        def initialize(name, &declarations)
-          @name         = name
-          @declarations = declarations
-          @actual       = nil
-          @diffable     = false
-          @supports_block_expectations = false
-          @expected_exception, @rescued_exception = nil, nil
-          @match_for_should_not_block = nil
-          @messages = {}
-          @define_block_executed = false
-          @block_method_differentiator = nil
-          @deprecated_methods = Set.new
-          @matcher_execution_context = nil
-        end
-
-        PERSISTENT_INSTANCE_VARIABLES = [
-          :@name, :@declarations, :@diffable,
-          :@supports_block_expectations,
-          :@match_block, :@match_for_should_not_block,
-          :@expected_exception
-        ].to_set
-
-        def expected
-          if @expected.size == 1
-            RSpec.warn_deprecation(
-              "Custom matchers in 3.x will set expected to be a single value "+
-              "(when provided as such) rather than an array. This may change "+
-              "the behaviour of your matcher.\n"+
-              "To continue to access this as an array use `expected_as_array`\n"+
-              "Called from: #{ RSpec::CallerFilter.first_non_rspec_line }\n\n"
-            )
-          end
-          @expected
-        end
-
-        def expected_as_array
-          @expected
-        end
-
-        def matcher_execution_context=(value)
-          RSpec.deprecate("`matcher_execution_context=` on custom matchers")
-          @matcher_execution_context = value
-        end
-
-        def matcher_execution_context
-          RSpec.deprecate("`matcher_execution_context` on custom matchers")
-          @matcher_execution_context
-        end
-
-        # @api private
-        def for_expected(*expected)
-          @expected = expected
-          dup.instance_eval do
-            instance_variables.map {|ivar| ivar.intern}.each do |ivar|
-              instance_variable_set(ivar, nil) unless (PERSISTENT_INSTANCE_VARIABLES + [:@expected]).include?(ivar)
-            end
-            @messages = {}
-            @deprecated_methods = Set.new
-
-            @block_method_differentiator = DifferentiateBlockMethodTypes.new(*@expected, &@declarations)
-            making_declared_methods_public do
-              instance_eval_with_args(*@expected, &@declarations)
-            end
-
-            @define_block_executed = true
-            self
-          end
-        end
-
-        # @api private
-        # Used internally by +should+ and +should_not+.
-        def matches?(actual)
-          @actual = actual
-          if @expected_exception
-            begin
-              instance_eval_with_args(actual, &@match_block)
-              true
-            rescue @expected_exception => @rescued_exception
-              false
-            end
-          else
-            begin
-              instance_eval_with_args(actual, &@match_block)
-            rescue RSpec::Expectations::ExpectationNotMetError
-              false
-            end
-          end
-        end
-
+      # Contains the methods that are available from within the
+      # `RSpec::Matchers.define` DSL for creating custom matchers.
+      module Macros
         # Stores the block that is used to determine whether this matcher passes
         # or fails. The block should return a boolean value. When the matcher is
-        # passed to `should` and the block returns `true`, then the expectation
-        # passes. Similarly, when the matcher is passed to `should_not` and the
+        # passed to `expect(...).to` and the block returns `true`, then the expectation
+        # passes. Similarly, when the matcher is passed to `expect(...).not_to` and the
         # block returns `false`, then the expectation passes.
         #
-        # Use `match_for_should` when used in conjuntion with
+        # Use `match_for_should` when used in conjunction with
         # `match_for_should_not`.
         #
         # @example
@@ -120,26 +23,35 @@ module RSpec
         #       end
         #     end
         #
-        #     4.should be_even     # passes
-        #     3.should_not be_even # passes
-        #     3.should be_even     # fails
-        #     4.should_not be_even # fails
+        #     expect(4).to be_even     # passes
+        #     expect(3).not_to be_even # passes
+        #     expect(3).to be_even     # fails
+        #     expect(4).not_to be_even # fails
         #
-        # @yield [Object] actual the actual value (or receiver of should)
-        def match(&block)
-          @match_block = block
+        # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
+        def match(&match_block)
+          define_user_override(:matches?, match_block) do |actual|
+            begin
+              @actual = actual
+              super(*actual_arg_for(match_block))
+            rescue RSpec::Expectations::ExpectationNotMetError
+              false
+            end
+          end
         end
+        alias match_for_should match
 
-        alias_method :match_for_should, :match
-
-        # Use this to define the block for a negative expectation (`should_not`)
+        # Use this to define the block for a negative expectation (`expect(...).not_to`)
         # when the positive and negative forms require different handling. This
         # is rarely necessary, but can be helpful, for example, when specifying
         # asynchronous processes that require different timeouts.
         #
-        # @yield [Object] actual the actual value (or receiver of should)
-        def match_for_should_not(&block)
-          @match_for_should_not_block = block
+        # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
+        def match_for_should_not(&match_block)
+          define_user_override(:does_not_match?, match_block) do |actual|
+            @actual = actual
+            super(*actual_arg_for(match_block))
+          end
         end
 
         # Use this instead of `match` when the block will raise an exception
@@ -153,76 +65,82 @@ module RSpec
         #       end
         #     end
         #
-        #     email_validator.should accept_as_valid("person@company.com")
-        def match_unless_raises(exception=Exception, &block)
-          @expected_exception = exception
-          match(&block)
+        #     expect(email_validator).to accept_as_valid("person@company.com")
+        #
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def match_unless_raises(expected_exception=Exception, &match_block)
+          define_user_override(:matches?, match_block) do |actual|
+            @actual = actual
+            begin
+              super(*actual_arg_for(match_block))
+            rescue expected_exception => @rescued_exception
+              false
+            else
+              true
+            end
+          end
         end
 
-        # Customize the failure messsage to use when this matcher is invoked with
-        # `should`. Only use this when the message generated by default doesn't
-        # suit your needs.
+        # Customizes the failure messsage to use when this matcher is
+        # asked to positively match. Only use this when the message
+        # generated by default doesn't suit your needs.
         #
         # @example
         #
         #     RSpec::Matchers.define :have_strength do |expected|
-        #       match { ... }
+        #       match { your_match_logic }
         #
         #       failure_message_for_should do |actual|
         #         "Expected strength of #{expected}, but had #{actual.strength}"
         #       end
         #     end
         #
-        # @yield [Object] actual the actual object
-        def failure_message_for_should(&block)
-          cache_or_call_cached(:failure_message_for_should, &block)
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def failure_message_for_should(&definition)
+          define_user_override(__method__, definition)
         end
 
-        # Customize the failure messsage to use when this matcher is invoked with
-        # `should_not`. Only use this when the message generated by default
-        # doesn't suit your needs.
+        # Customize the failure messsage to use when this matcher is asked
+        # to negatively match. Only use this when the message generated by
+        # default doesn't suit your needs.
         #
         # @example
         #
         #     RSpec::Matchers.define :have_strength do |expected|
-        #       match { ... }
+        #       match { your_match_logic }
         #
         #       failure_message_for_should_not do |actual|
         #         "Expected not to have strength of #{expected}, but did"
         #       end
         #     end
         #
-        # @yield [Object] actual the actual object
-        # @yield [Object] actual the actual object
-        def failure_message_for_should_not(&block)
-          cache_or_call_cached(:failure_message_for_should_not, &block)
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def failure_message_for_should_not(&definition)
+          define_user_override(__method__, definition)
         end
 
-
         # Customize the description to use for one-liners.  Only use this when
         # the description generated by default doesn't suit your needs.
         #
         # @example
         #
         #     RSpec::Matchers.define :qualify_for do |expected|
-        #       match { ... }
+        #       match { your_match_logic }
         #
         #       description do
         #         "qualify for #{expected}"
         #       end
         #     end
-        def description(&block)
-          cache_or_call_cached(:description, &block)
+        #
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def description(&definition)
+          define_user_override(__method__, definition)
         end
 
         # Tells the matcher to diff the actual and expected values in the failure
         # message.
         def diffable
-          @diffable = true
-        end
-
-        def supports_block_expectations
-          @supports_block_expectations = true
+          define_method(:diffable?) { true }
         end
 
         # Convenience for defining methods on this matcher to create a fluent
@@ -242,178 +160,140 @@ module RSpec
         #       end
         #     end
         #
-        #     minor.should have_errors_on(:age).with("Not old enough to participate")
-        def chain(method, &block)
-          define_method method do |*args|
-            block.call(*args)
+        #     expect(minor).to have_errors_on(:age).with("Not old enough to participate")
+        def chain(name, &definition)
+          define_user_override(name, definition) do |*args, &block|
+            super(*args, &block)
             self
           end
         end
 
-        # @api private
-        # Used internally by objects returns by +should+ and +should_not+.
-        def diffable?
-          @diffable
-        end
+      private
 
-        # @api private
-        def supports_block_expectations?
-          @supports_block_expectations
+        # Does the following:
+        #
+        # - Defines the named method usign a user-provided block
+        #   in @user_method_defs, which is included as an ancestor
+        #   in the singleton class in which we eval the `define` block.
+        # - Defines an overriden definition for the same method
+        #   usign the provided `our_def` block.
+        # - Provides a default `our_def` block for the common case
+        #   of needing to call the user's definition with `@actual`
+        #   as an arg, but only if their block's arity can handle it.
+        #
+        # This compiles the user block into an actual method, allowing
+        # them to use normal method constructs like `return`
+        # (e.g. for a early guard statement), while allowing us to define
+        # an override that can provide the wrapped handling
+        # (e.g. assigning `@actual`, rescueing errors, etc) and
+        # can `super` to the user's definition.
+        def define_user_override(method_name, user_def, &our_def)
+          @user_method_defs.__send__(:define_method, method_name, &user_def)
+          our_def ||= lambda { super(*actual_arg_for(user_def)) }
+          define_method(method_name, &our_def)
         end
+      end
 
+      # Defines default implementations of the matcher
+      # protocol methods for custom matchers. You can
+      # override any of these using the {RSpec::Matchers::DSL::Macros Macros} methods
+      # from within an `RSpec::Matchers.define` block.
+      module DefaultImplementations
         # @api private
-        # Used internally by +should_not+
-        def does_not_match?(actual)
-          @actual = actual
-          @match_for_should_not_block ?
-            instance_eval_with_args(actual, &@match_for_should_not_block) :
-            !matches?(actual)
-        end
-
-        def respond_to?(method, include_private=false)
-          super || @matcher_execution_context.respond_to?(method, include_private)
+        # Used internally by objects returns by `should` and `should_not`.
+        def diffable?
+          false
         end
 
-        private
-
-        def method_missing(method, *args, &block)
-          if @matcher_execution_context.respond_to?(method)
-            @matcher_execution_context.__send__ method, *args, &block
-          else
-            super(method, *args, &block)
-          end
+        # The default description.
+        def description
+          "#{name_to_sentence}#{expected_to_sentence}"
         end
 
-        def include(*modules)
-          return_value = singleton_class.__send__(:include, *modules)
-
-          modules.each do |mod|
-            mod.instance_methods.each do |name|
-              add_deprecation_warning_to(name,
-                "Calling a helper method (`#{name}`) from a module included in a custom matcher as a macro",
-                "`extend #{mod.name || "TheModule"}`",
-                "included in the custom matcher",
-                :unless
-              )
-            end
-          end
-
-          return_value
+        # The default failure message for positive expectations.
+        def failure_message_for_should
+          "expected #{actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
         end
 
-        def extend(*modules)
-          return_value = super
-
-          modules.each do |mod|
-            mod.instance_methods.each do |name|
-              add_deprecation_warning_to(name,
-                "Calling a helper method (`#{name}`) from a module extended onto a custom matcher",
-                "`include #{mod.name || "TheModule"}`",
-                "extended onto the custom matcher",
-                :if
-              )
-            end
-          end unless @define_block_executed
-
-          return_value
+        # The default failure message for negative expectations.
+        def failure_message_for_should_not
+          "expected #{actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
         end
+      end
 
-        def define_method(name, &block)
-          singleton_class.__send__(:define_method, name, &block)
-        end
+      # The class used for custom matchers. The block passed to
+      # `RSpec::Matchers.define` will be evaluated in the context
+      # of the singleton class of an instance, and will have the
+      # {RSpec::Matchers::DSL::Macros Macros} methods available.
+      class Matcher
+        # Provides default implementations for the matcher protocol methods.
+        include DefaultImplementations
 
-        def making_declared_methods_public
-          # Our home-grown instance_exec in ruby 1.8.6 results in any methods
-          # declared in the block eval'd by instance_exec in the block to which we
-          # are yielding here are scoped private. This is NOT the case for Ruby
-          # 1.8.7 or 1.9.
-          #
-          # Also, due some crazy scoping that I don't understand, these methods
-          # are actually available in the specs (something about the matcher being
-          # defined in the scope of RSpec::Matchers or within an example), so not
-          # doing the following will not cause specs to fail, but they *will*
-          # cause features to fail and that will make users unhappy. So don't.
-          orig_private_methods = private_methods
-          yield
-          (private_methods - orig_private_methods).each {|m| singleton_class.__send__ :public, m}
-        end
+        # Allows expectation expressions to be used in the match block.
+        include RSpec::Matchers
 
-        def cache_or_call_cached(key, &block)
-          block ? cache(key, &block) : call_cached(key)
-        end
+        # Converts matcher name and expected args to an English expresion.
+        include RSpec::Matchers::Pretty
 
-        def cache(key, &block)
-          @messages[key] = block
-        end
+        # Makes the macro methods available to an `RSpec::Matchers.define` block.
+        extend Macros
 
-        def call_cached(key)
-          if @messages.has_key?(key)
-            @messages[key].arity == 1 ? @messages[key].call(@actual) : @messages[key].call
-          else
-            __send__("default_#{key}")
-          end
-        end
+        attr_reader   :expected, :actual, :rescued_exception
+        attr_accessor :matcher_execution_context
 
-        def default_description
-          "#{name_to_sentence}#{to_sentence expected_as_array}"
-        end
+        # @api private
+        def initialize(name, declarations, *expected)
+          @name     = name
+          @actual   = nil
+          @expected = expected
 
-        def default_failure_message_for_should
-          "expected #{actual.inspect} to #{name_to_sentence}#{to_sentence expected_as_array}"
+          class << self
+            # See `Macros#define_user_override` above, for an explanation.
+            include(@user_method_defs = Module.new)
+            self
+          end.class_exec(*expected, &declarations)
         end
 
-        def default_failure_message_for_should_not
-          "expected #{actual.inspect} not to #{name_to_sentence}#{to_sentence expected_as_array}"
+        # Adds the name (rather than a cryptic hex number)
+        # so we can identify an instance of
+        # the matcher in error messages (e.g. for `NoMethodError`)
+        def inspect
+          "#<#{self.class.name} #{name}>"
         end
 
-        unless method_defined?(:singleton_class)
-          def singleton_class
-            class << self; self; end
+        if RUBY_VERSION.to_f >= 1.9
+          # Indicates that this matcher responds to messages
+          # from the `matcher_execution_context` as well.
+          # Also, supports getting a method object for such methods.
+          def respond_to_missing?(method, include_private=false)
+            super || matcher_execution_context.respond_to?(method, include_private)
           end
-        end
-
-        def singleton_method_added(name)
-          return unless @block_method_differentiator
-
-          if @block_method_differentiator.instance_methods.include?(name)
-            add_deprecation_warning_to(name,
-              "Calling a helper method (`#{name}`) defined as an instance method (using `def #{name}`) as a macro from a custom matcher `define` block",
-              "`def self.#{name}` (to define it as a singleton method)",
-              "defined in the custom matcher definition block",
-              :unless
-            )
-          elsif @block_method_differentiator.singleton_methods.include?(name)
-            add_deprecation_warning_to(name,
-              "Calling a helper method (`#{name}`) defined as a singleton method (using `def self.#{name}`) on a custom matcher",
-              "`def #{name}` (to define it as an instance method)",
-              "defined in the custom matcher definition block",
-              :if
-            )
+        else # for 1.8.7
+          # Indicates that this matcher responds to messages
+          # from the `matcher_execution_context` as well.
+          def respond_to?(method, include_private=false)
+            super || matcher_execution_context.respond_to?(method, include_private)
           end
         end
 
-        def add_deprecation_warning_to(method_name, msg, replacement, extra_call_site_msg, condition)
-          return if @deprecated_methods.include?(method_name)
-          @deprecated_methods << method_name
-
-          aliased_name = aliased_name_for(method_name)
-          singleton_class.__send__(:alias_method, aliased_name, method_name)
+      private
 
-          singleton_class.class_eval(<<-EOS, __FILE__, __LINE__ + 1)
-            def #{method_name}(*a, &b)
-              ::RSpec.deprecate(#{msg.inspect},
-                :replacement => #{replacement.inspect},
-                :call_site => CallerFilter.first_non_rspec_line + " and #{extra_call_site_msg} at #{CallerFilter.first_non_rspec_line}"
-              ) #{condition} @define_block_executed
-
-              __send__(#{aliased_name.inspect}, *a, &b)
-            end
-          EOS
+        def actual_arg_for(block)
+          block.arity.zero? ? [] : [@actual]
         end
 
-        def aliased_name_for(method_name)
-          target, punctuation = method_name.to_s.sub(/([?!=])$/, ''), $1
-          "#{target}_without_rspec_deprecation_warning#{punctuation}"
+        # Takes care of forwarding unhandled messages to the
+        # `matcher_execution_context` (typically the current
+        # running `RSpec::Core::Example`). This is needed by
+        # rspec-rails so that it can define matchers that wrap
+        # Rails' test helper methods, but it's also a useful
+        # feature in its own right.
+        def method_missing(method, *args, &block)
+          if matcher_execution_context.respond_to?(method)
+            matcher_execution_context.__send__ method, *args, &block
+          else
+            super(method, *args, &block)
+          end
         end
       end
     end