rspec-expectations 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/expectations/expectation_target.rb

@@ -1,18 +1,43 @@
 module RSpec
   module Expectations
     # Wraps the target of an expectation.
+    #
     # @example
-    #   expect(something) # => ExpectationTarget wrapping something
+    #   expect(something)       # => ExpectationTarget wrapping something
+    #   expect { do_something } # => ExpectationTarget wrapping the block
     #
     #   # used with `to`
     #   expect(actual).to eq(3)
     #
     #   # with `not_to`
     #   expect(actual).not_to eq(3)
+    #
+    # @note `ExpectationTarget` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
     class ExpectationTarget
+      # @private
+      # Used as a sentinel value to be able to tell when the user
+      # did not pass an argument. We can't use `nil` for that because
+      # `nil` is a valid value to pass.
+      UndefinedValue = Module.new
+
       # @api private
-      def initialize(target)
-        @target = target
+      def initialize(value)
+        @target = value
+      end
+
+      # @private
+      def self.for(value, block)
+        if UndefinedValue.equal?(value)
+          unless block
+            raise ArgumentError, "You must pass either an argument or a block to `expect`."
+          end
+          BlockExpectationTarget.new(block)
+        elsif block
+          raise ArgumentError, "You cannot pass both an argument and a block to `expect`."
+        else
+          new(value)
+        end
       end
 
       # Runs the given expectation, passing if `matcher` returns true.
@@ -25,7 +50,7 @@ module RSpec
       # @return [Boolean] true if the expectation succeeds (else raises)
       # @see RSpec::Matchers
       def to(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:to, matcher)
+        prevent_operator_matchers(:to) unless matcher
         RSpec::Expectations::PositiveExpectationHandler.handle_matcher(@target, matcher, message, &block)
       end
 
@@ -38,20 +63,59 @@ module RSpec
       # @return [Boolean] false if the negative expectation succeeds (else raises)
       # @see RSpec::Matchers
       def not_to(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:not_to, matcher)
+        prevent_operator_matchers(:not_to) unless matcher
         RSpec::Expectations::NegativeExpectationHandler.handle_matcher(@target, matcher, message, &block)
       end
       alias to_not not_to
 
     private
 
-      def prevent_operator_matchers(verb, matcher)
-        return if matcher
-
+      def prevent_operator_matchers(verb)
         raise ArgumentError, "The expect syntax does not support operator matchers, " +
                              "so you must pass a matcher to `##{verb}`."
       end
     end
+
+    # @private
+    # Validates the provided matcher to ensure it supports block
+    # expectations, in order to avoid user confusion when they
+    # use a block thinking the expectation will be on the return
+    # value of the block rather than the block itself.
+    class BlockExpectationTarget < ExpectationTarget
+      def to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
+
+      def not_to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
+      alias to_not not_to
+
+    private
+
+      def enforce_block_expectation(matcher)
+        return if supports_block_expectations?(matcher)
+
+        raise ExpectationNotMetError,
+          "You must pass an argument rather than a block to use the provided " +
+          "matcher (#{description_of matcher}), or the matcher must implement " +
+          "`supports_block_expectations?`."
+      end
+
+      def supports_block_expectations?(matcher)
+        matcher.supports_block_expectations?
+      rescue NoMethodError
+        false
+      end
+
+      def description_of(matcher)
+        matcher.description
+      rescue NoMethodError
+        matcher.inspect
+      end
+    end
   end
 end
 

data/lib/rspec/expectations/fail_with.rb

@@ -1,9 +1,14 @@
+RSpec::Support.require_rspec_support 'differ'
+
 module RSpec
   module Expectations
     class << self
       # @private
       def differ
-        DiffPresenter.new
+        RSpec::Support::Differ.new(
+          :object_preparer => lambda {|object| RSpec::Matchers::Composable.surface_descriptions_in(object) },
+          :color => RSpec::Matchers.configuration.color?
+        )
       end
 
       # Raises an RSpec::Expectations::ExpectationNotMetError with message.
@@ -19,60 +24,13 @@ module RSpec
                                "appropriate failure_message[_when_negated] method to return a string?"
         end
 
-        if actual && expected
-          if all_strings?(actual, expected)
-            if any_multiline_strings?(actual, expected)
-              message << "\nDiff:" << differ.diff_as_string(coerce_to_string(actual), coerce_to_string(expected))
-            end
-          elsif no_procs?(actual, expected) && no_numbers?(actual, expected)
-            message << "\nDiff:" << differ.diff_as_object(actual, expected)
-          end
-        end
-
-        raise(RSpec::Expectations::ExpectationNotMetError.new(message))
-      end
-
-    private
-
-      def no_procs?(*args)
-        args.flatten.none? {|a| Proc === a}
-      end
-
-      def all_strings?(*args)
-        args.flatten.all? {|a| String === a}
-      end
-
-      def any_multiline_strings?(*args)
-        all_strings?(*args) && args.flatten.any? { |a| multiline?(a) }
-      end
+        diff = differ.diff(actual, expected)
 
-      def no_numbers?(*args)
-        args.flatten.none? {|a| Numeric === a}
-      end
-
-      def coerce_to_string(string_or_array)
-        return string_or_array unless Array === string_or_array
-        diffably_stringify(string_or_array).join("\n")
-      end
-
-      def diffably_stringify(array)
-        array.map do |entry|
-          if Array === entry
-            entry.inspect
-          else
-            entry.to_s.gsub("\n", "\\n")
-          end
+        unless diff.empty?
+          message = "#{message}\nDiff:#{diff}"
         end
-      end
 
-      if String.method_defined?(:encoding)
-        def multiline?(string)
-          string.include?("\n".encode(string.encoding))
-        end
-      else
-        def multiline?(string)
-          string.include?("\n")
-        end
+        raise RSpec::Expectations::ExpectationNotMetError.new(message)
       end
     end
   end

data/lib/rspec/expectations/handler.rb

@@ -1,8 +1,8 @@
 module RSpec
   module Expectations
 
-    # @api private
-    class ExpectationHelper
+    # @private
+    module ExpectationHelper
       def self.check_message(msg)
         unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
           ::Kernel.warn [
@@ -16,7 +16,7 @@ module RSpec
       # Returns an RSpec-3+ compatible matcher, wrapping a legacy one
       # in an adapter if necessary.
       #
-      # @api private
+      # @private
       def self.modern_matcher_from(matcher)
         LegacyMacherAdapter::RSpec2.wrap(matcher) ||
         LegacyMacherAdapter::RSpec1.wrap(matcher) || matcher
@@ -40,7 +40,7 @@ module RSpec
       end
     end
 
-    # @api private
+    # @private
     class PositiveExpectationHandler
       def self.handle_matcher(actual, initial_matcher, message=nil, &block)
         matcher = ExpectationHelper.setup(self, initial_matcher, message)
@@ -62,7 +62,7 @@ module RSpec
       end
     end
 
-    # @api private
+    # @private
     class NegativeExpectationHandler
       def self.handle_matcher(actual, initial_matcher, message=nil, &block)
         matcher = ExpectationHelper.setup(self, initial_matcher, message)
@@ -95,17 +95,15 @@ module RSpec
     # Wraps a matcher written against one of the legacy protocols in
     # order to present the current protocol.
     #
-    # @api private
+    # @private
     class LegacyMacherAdapter < Matchers::MatcherDelegator
       def initialize(matcher)
         super
-        ::RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
-          |--------------------------------------------------------------------------
+        ::RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''), :type => "legacy_matcher")
           |#{matcher.class.name || matcher.inspect} implements a legacy RSpec matcher
           |protocol. For the current protocol you should expose the failure messages
           |via the `failure_message` and `failure_message_when_negated` methods.
           |(Used from #{CallerFilter.first_non_rspec_line})
-          |--------------------------------------------------------------------------
         EOS
       end
 
@@ -117,7 +115,7 @@ module RSpec
       # the failure message protocol was:
       #   * `failure_message_for_should`
       #   * `failure_message_for_should_not`
-      # @api private
+      # @private
       class RSpec2 < self
         def failure_message
           base_matcher.failure_message_for_should
@@ -141,7 +139,7 @@ module RSpec
       # Before RSpec 1.2, the failure message protocol was:
       #   * `failure_message`
       #   * `negative_failure_message`
-      # @api private
+      # @private
       class RSpec1 < self
         def failure_message
           base_matcher.failure_message

data/lib/rspec/expectations/syntax.rb

@@ -6,47 +6,22 @@ module RSpec
     module Syntax
       module_function
 
-      # @method should
-      # Passes if `matcher` returns true.  Available on every `Object`.
-      # @example
-      #   actual.should eq expected
-      #   actual.should match /expression/
-      # @param [Matcher]
-      #   matcher
-      # @param [String] message optional message to display when the expectation fails
-      # @return [Boolean] true if the expectation succeeds (else raises)
-      # @see RSpec::Matchers
-
-      # @method should_not
-      # Passes if `matcher` returns false.  Available on every `Object`.
-      # @example
-      #   actual.should_not eq expected
-      # @param [Matcher]
-      #   matcher
-      # @param [String] message optional message to display when the expectation fails
-      # @return [Boolean] false if the negative expectation succeeds (else raises)
-      # @see RSpec::Matchers
-
-      # @method expect
-      # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
-      # `ExpectationTarget`.
-      # @example
-      #   expect(actual).to eq(expected)
-      #   expect(actual).not_to eq(expected)
-      # @return [ExpectationTarget]
-      # @see ExpectationTarget#to
-      # @see ExpectationTarget#not_to
-
       # @api private
       # Determines where we add `should` and `should_not`.
       def default_should_host
         @default_should_host ||= ::Object.ancestors.last
       end
 
+      # @api private
+      # Instructs rspec-expectations to warn on first usage of `should` or `should_not`.
+      # Enabled by default. This is largely here to facilitate testing.
       def warn_about_should!
         @warn_about_should = true
       end
 
+      # @api private
+      # Generates a deprecation warning for the given method if no warning
+      # has already been issued.
       def warn_about_should_unless_configured(method_name)
         if @warn_about_should
           RSpec.deprecate(
@@ -94,10 +69,8 @@ module RSpec
         return if expect_enabled?(syntax_host)
 
         syntax_host.module_exec do
-          def expect(*target, &target_block)
-            target << target_block if block_given?
-            raise ArgumentError.new("You must pass an argument or a block to #expect but not both.") unless target.size == 1
-            ::RSpec::Expectations::ExpectationTarget.new(target.first)
+          def expect(value=::RSpec::Expectations::ExpectationTarget::UndefinedValue, &block)
+            ::RSpec::Expectations::ExpectationTarget.for(value, block)
           end
         end
       end
@@ -126,3 +99,32 @@ module RSpec
     end
   end
 end
+
+# The legacy `:should` syntax adds the following methods directly to
+# `BasicObject` so that they are available off of any object. Note, however,
+# that this syntax does not always play nice with delegate/proxy objects.
+# We recommend you use the non-monkeypatching `:expect` syntax instead.
+class BasicObject
+  # @method should
+  # Passes if `matcher` returns true.  Available on every `Object`.
+  # @example
+  #   actual.should eq expected
+  #   actual.should match /expression/
+  # @param [Matcher]
+  #   matcher
+  # @param [String] message optional message to display when the expectation fails
+  # @return [Boolean] true if the expectation succeeds (else raises)
+  # @note This is only available when you have enabled the `:should` syntax.
+  # @see RSpec::Matchers
+
+  # @method should_not
+  # Passes if `matcher` returns false.  Available on every `Object`.
+  # @example
+  #   actual.should_not eq expected
+  # @param [Matcher]
+  #   matcher
+  # @param [String] message optional message to display when the expectation fails
+  # @return [Boolean] false if the negative expectation succeeds (else raises)
+  # @note This is only available when you have enabled the `:should` syntax.
+  # @see RSpec::Matchers
+end

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '3.0.0.beta2'
+      STRING = '3.0.0.rc1'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -1,11 +1,18 @@
-require 'rspec/matchers/pretty'
-require 'rspec/matchers/composable'
-require 'rspec/matchers/built_in'
-require 'rspec/matchers/generated_descriptions'
-require 'rspec/matchers/dsl'
-require 'rspec/matchers/matcher_delegator'
-require 'rspec/matchers/aliased_matcher'
-
+require 'rspec/support'
+RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relative(f) }
+
+%w[
+  pretty
+  composable
+  built_in
+  generated_descriptions
+  dsl
+  matcher_delegator
+  aliased_matcher
+].each { |file| RSpec::Support.require_rspec_matchers(file) }
+
+# RSpec's top level namespace. All of rspec-expectations is contained
+# in the `RSpec::Expectations` and `RSpec::Matchers` namespaces.
 module RSpec
   # RSpec::Matchers provides a number of useful matchers we use to define
   # expectations. A matcher is any object that responds to the following:
@@ -18,6 +25,7 @@ module RSpec
   #     does_not_match?(actual)
   #     failure_message_when_negated
   #     description
+  #     supports_block_expectations?
   #
   # ## Predicates
   #
@@ -202,6 +210,16 @@ module RSpec
   # for readable failure messages. You can alias your custom matchers in similar fashion
   # using {RSpec::Matchers.alias_matcher}.
   module Matchers
+    # @method expect
+    # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
+    # `ExpectationTarget`.
+    # @example
+    #   expect(actual).to eq(expected)
+    #   expect(actual).not_to eq(expected)
+    # @return [ExpectationTarget]
+    # @see ExpectationTarget#to
+    # @see ExpectationTarget#not_to
+
     # Defines a matcher alias. The returned matcher's `description` will be overriden
     # to reflect the phrasing of the new name, which will be used in failure messages
     # when passed as an argument to another matcher in a composed matcher expression.
@@ -227,6 +245,10 @@ module RSpec
     #
     #   be_sorted_by(:age).description # => "be sorted by age"
     #   a_list_sorted_by(:age).description # => "a list sorted by age"
+    #
+    # @!macro [attach] alias_matcher
+    #   @!parse
+    #     alias $1 $2
     def self.alias_matcher(new_name, old_name, &description_override)
       description_override ||= lambda do |old_desc|
         old_desc.gsub(Pretty.split_words(old_name), Pretty.split_words(new_name))
@@ -559,6 +581,26 @@ module RSpec
     alias_matcher :a_hash_including,       :include
     alias_matcher :including,              :include
 
+    # Passes if actual all expected objects pass. This works for
+    # any enumerable object.
+    #
+    # @example
+    #
+    #   expect([1, 3, 5]).to all be_odd
+    #   expect([1, 3, 6]).to all be_odd # fails
+    #
+    # @note The negative form `not_to all` is not supported. Instead
+    #   use `not_to include` or pass a negative form of a matcher
+    #   as the argument (e.g. `all exclude(:foo)`).
+    #
+    # @note You can also use this with compound matchers as well.
+    #
+    # @example
+    #   expect([1, 3, 5]).to all( be_odd.and be_an(Integer) )
+    def all(expected)
+      BuiltIn::All.new(expected)
+    end
+
     # Given a `Regexp` or `String`, passes if `actual.match(pattern)`
     # Given an arbitrary nested data structure (e.g. arrays and hashes),
     # matches if `expected === actual` || `actual == expected` for each
@@ -675,7 +717,7 @@ module RSpec
     #
     # @example
     #
-    # expect("string").to respond_to(:length)
+    #   expect("string").to respond_to(:length)
     #
     def respond_to(*names)
       BuiltIn::RespondTo.new(*names)
@@ -837,6 +879,15 @@ module RSpec
     alias_matcher :a_block_yielding_successive_args,  :yield_successive_args
     alias_matcher :yielding_successive_args,          :yield_successive_args
 
+    # Delegates to {RSpec::Expectations.configuration}.
+    # This is here because rspec-core's `expect_with` option
+    # looks for a `configuration` method on the mixin
+    # (`RSpec::Matchers`) to yield to a block.
+    # @return [RSpec::Expectations::Configuration] the configuration object
+    def self.configuration
+      Expectations.configuration
+    end
+
   private
 
     BE_PREDICATE_REGEX = /^(be_(?:an?_)?)(.*)/