rspec-expectations 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/matchers/aliased_matcher.rb

@@ -27,6 +27,12 @@ module RSpec
         AliasedMatcher.new(return_val, @description_block)
       end
 
+      # Provides the description of the aliased matcher. Aliased matchers
+      # are designed to behave identically to the original matcher except
+      # for this method. The description is different to reflect the aliased
+      # name.
+      #
+      # @api private
       def description
         @description_block.call(super)
       end

data/lib/rspec/matchers/built_in.rb

@@ -1,7 +1,14 @@
-require 'rspec/matchers/built_in/base_matcher'
+RSpec::Support.require_rspec_matchers "built_in/base_matcher"
 
 module RSpec
   module Matchers
+    # Container module for all built-in matchers. The matcher classes are here
+    # (rather than directly under `RSpec::Matchers`) in order to prevent name
+    # collisions, since `RSpec::Matchers` gets included into the user's namespace.
+    #
+    # Autoloading is used to delay when the matcher classes get loaded, allowing
+    # rspec-matchers to boot faster, and avoiding loading matchers the user is
+    # not using.
     module BuiltIn
       autoload :BeAKindOf,               'rspec/matchers/built_in/be_kind_of'
       autoload :BeAnInstanceOf,          'rspec/matchers/built_in/be_instance_of'
@@ -24,6 +31,7 @@ module RSpec
       autoload :Exist,                   'rspec/matchers/built_in/exist'
       autoload :Has,                     'rspec/matchers/built_in/has'
       autoload :Include,                 'rspec/matchers/built_in/include'
+      autoload :All,                     'rspec/matchers/built_in/all'
       autoload :Match,                   'rspec/matchers/built_in/match'
       autoload :NegativeOperatorMatcher, 'rspec/matchers/built_in/operators'
       autoload :OperatorMatcher,         'rspec/matchers/built_in/operators'

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

@@ -0,0 +1,78 @@
+module RSpec
+  module Matchers
+    module BuiltIn
+      # @api private
+      # Provides the implementation for `all`.
+      # Not intended to be instantiated directly.
+      class All < BaseMatcher
+
+        # @private
+        attr_reader :matcher, :failed_objects
+
+        def initialize(matcher)
+          @matcher = matcher
+          @failed_objects = {}
+        end
+
+        # @private
+        def does_not_match?(actual)
+          raise NotImplementedError, '`expect().not_to all( matcher )` is not supported.'
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          all_messages = [improve_hash_formatting(super)]
+          failed_objects.each do |index, matcher_failure_message|
+            all_messages << failure_message_for_item(index, matcher_failure_message)
+          end
+          all_messages.join("\n\n")
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          described_items = surface_descriptions_in(matcher)
+          improve_hash_formatting "all#{to_sentence(described_items)}"
+        end
+
+      private
+
+        def match(_, actual)
+          index_failed_objects
+          failed_objects.empty?
+        end
+
+        def index_failed_objects
+          actual.each_with_index do |actual_item, index|
+            cloned_matcher = matcher.clone
+            matches = cloned_matcher.matches?(actual_item)
+            failed_objects[index] = cloned_matcher.failure_message unless matches
+          end
+        end
+
+        def failure_message_for_item(index, failure_message)
+          failure_message = indent_multiline_message( add_new_line_if_needed(failure_message) )
+          indent_multiline_message("object at index #{index} failed to match:#{failure_message}")
+        end
+
+        def add_new_line_if_needed(message)
+          message.start_with?("\n") ? message : "\n#{message}"
+        end
+
+        def indent_multiline_message(message)
+          message = message.sub(/\n+\z/, '')
+          message.lines.map do |line|
+            line =~ /\S/ ? '   ' + line : line
+          end.join
+        end
+
+        def initialize_copy(other)
+          @matcher = @matcher.clone
+          super
+        end
+
+      end
+    end
+  end
+end

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

@@ -4,7 +4,7 @@ module RSpec
       # @api private
       #
       # Used _internally_ as a base class for matchers that ship with
-      # rspec-expectations.
+      # rspec-expectations and rspec-rails.
       #
       # ### Warning:
       #
@@ -15,19 +15,33 @@ module RSpec
         include RSpec::Matchers::Pretty
         include RSpec::Matchers::Composable
 
+        # @api private
+        # Used to detect when no arg is passed to `initialize`.
+        # `nil` cannot be used because it's a valid value to pass.
         UNDEFINED = Object.new.freeze
 
+        # @private
         attr_reader :actual, :expected, :rescued_exception
 
         def initialize(expected = UNDEFINED)
           @expected = expected unless UNDEFINED.equal?(expected)
         end
 
+        # @api private
+        # Indicates if the match is successful. Delegates to `match`, which
+        # should be defined on a subclass. Takes care of consistently
+        # initializing the `actual` attribute.
         def matches?(actual)
           @actual = actual
           match(expected, actual)
         end
 
+        # @api private
+        # Used to wrap a block of code that will indicate failure by
+        # raising one of the named exceptions.
+        #
+        # This is used by rspec-rails for some of its matchers that
+        # wrap rails' assertions.
         def match_unless_raises(*exceptions)
           exceptions.unshift Exception if exceptions.empty?
           begin
@@ -38,25 +52,49 @@ module RSpec
           end
         end
 
+        # @api private
+        # Provides a good generic failure message. Based on `description`.
+        # When subclassing, if you are not satisfied with this failure message
+        # you often only need to override `description`.
+        # @return [String]
         def failure_message
           assert_ivars :@actual
           "expected #{@actual.inspect} to #{description}"
         end
 
+        # @api private
+        # Provides a good generic negative failure message. Based on `description`.
+        # When subclassing, if you are not satisfied with this failure message
+        # you often only need to override `description`.
+        # @return [String]
         def failure_message_when_negated
           assert_ivars :@actual
           "expected #{@actual.inspect} not to #{description}"
         end
 
+        # @api private
+        # Generates a "pretty" description using the logic in {Pretty}.
+        # @return [String]
         def description
           return name_to_sentence unless defined?(@expected)
           "#{name_to_sentence}#{to_sentence @expected}"
         end
 
+        # @api private
+        # Matchers are not diffable by default. Override this to make your
+        # subclass diffable.
         def diffable?
           false
         end
 
+        # @api private
+        # Most matchers are value matchers (i.e. meant to work with `expect(value)`)
+        # rather than block matchers (i.e. meant to work with `expect { }`), so
+        # this defaults to false. Block matchers must override this to return true.
+        def supports_block_expectations?
+          false
+        end
+
       private
 
         def assert_ivars(*expected_ivars)

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

@@ -1,50 +1,79 @@
-require 'rspec/matchers/dsl'
-
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_truthy`.
+      # Not intended to be instantiated directly.
       class BeTruthy < BaseMatcher
-        def match(_, actual)
-          !!actual
-        end
 
+        # @api private
+        # @return [String]
         def failure_message
           "expected: truthy value\n     got: #{actual.inspect}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           "expected: falsey value\n     got: #{actual.inspect}"
         end
-      end
 
-      class BeFalsey < BaseMatcher
+      private
+
         def match(_, actual)
-          !actual
+          !!actual
         end
+      end
 
+      # @api private
+      # Provides the implementation for `be_falsey`.
+      # Not intended to be instantiated directly.
+      class BeFalsey < BaseMatcher
+
+        # @api private
+        # @return [String]
         def failure_message
           "expected: falsey value\n     got: #{actual.inspect}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           "expected: truthy value\n     got: #{actual.inspect}"
         end
-      end
 
-      class BeNil < BaseMatcher
+      private
+
         def match(_, actual)
-          actual.nil?
+          !actual
         end
+      end
 
+      # @api private
+      # Provides the implementation for `be_nil`.
+      # Not intended to be instantiated directly.
+      class BeNil < BaseMatcher
+
+        # @api private
+        # @return [String]
         def failure_message
           "expected: nil\n     got: #{actual.inspect}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           "expected: not nil\n     got: nil"
         end
+
+      private
+
+        def match(_, actual)
+          actual.nil?
+        end
       end
 
+      # @private
       module BeHelpers
         private
 
@@ -69,6 +98,9 @@ module RSpec
         end
       end
 
+      # @api private
+      # Provides the implementation for `be`.
+      # Not intended to be instantiated directly.
       class Be < BaseMatcher
         include BeHelpers
 
@@ -76,14 +108,14 @@ module RSpec
           @args = args
         end
 
-        def match(_, actual)
-          !!actual
-        end
-
+        # @api private
+        # @return [String]
         def failure_message
           "expected #{@actual.inspect} to evaluate to true"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           "expected #{@actual.inspect} to evaluate to false"
         end
@@ -93,8 +125,17 @@ module RSpec
             BeComparedTo.new(operand, operator)
           end
         end
+
+      private
+
+        def match(_, actual)
+          !!actual
+        end
       end
 
+      # @api private
+      # Provides the implementation of `be <operator> value`.
+      # Not intended to be instantiated directly.
       class BeComparedTo < BaseMatcher
         include BeHelpers
 
@@ -108,10 +149,14 @@ module RSpec
           @actual.__send__ @operator, @expected
         end
 
+        # @api private
+        # @return [String]
         def failure_message
           "expected: #{@operator} #{@expected.inspect}\n     got: #{@operator.to_s.gsub(/./, ' ')} #{@actual.inspect}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           message = "`expect(#{@actual.inspect}).not_to be #{@operator} #{@expected.inspect}`"
           if [:<, :>, :<=, :>=].include?(@operator)
@@ -121,11 +166,16 @@ module RSpec
           end
         end
 
+        # @api private
+        # @return [String]
         def description
           "be #{@operator} #{expected_to_sentence}#{args_to_sentence}"
         end
       end
 
+      # @api private
+      # Provides the implementation of `be_<predicate>`.
+      # Not intended to be instantiated directly.
       class BePredicate < BaseMatcher
         include BeHelpers
 
@@ -135,56 +185,68 @@ module RSpec
           @block = block
         end
 
-        def matches?(actual)
-          @actual = actual
-
-          if is_private_on?( @actual )
-            raise Expectations::ExpectationNotMetError.new("expectation set on private method `#{predicate}`")
-          end
-
-          begin
-            return @result = actual.__send__(predicate, *@args, &@block)
-          rescue NameError => predicate_missing_error
-          end
+        def matches?(actual, &block)
+          @actual  = actual
+          @block ||= block
+          predicate_accessible? && predicate_matches?
+        end
 
-          begin
-            return @result = actual.__send__(present_tense_predicate, *@args, &@block)
-          rescue NameError
-            raise predicate_missing_error
-          end
+        def does_not_match?(actual, &block)
+          @actual  = actual
+          @block ||= block
+          predicate_accessible? && !predicate_matches?
         end
 
+        # @api private
+        # @return [String]
         def failure_message
-          "expected #{predicate}#{args_to_s} to return true, got #{@result.inspect}"
+          failure_message_expecting(true)
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
-          "expected #{predicate}#{args_to_s} to return false, got #{@result.inspect}"
+          failure_message_expecting(false)
         end
 
+        # @api private
+        # @return [String]
         def description
           "#{prefix_to_sentence}#{expected_to_sentence}#{args_to_sentence}"
         end
 
-        private
+      private
+
+        def predicate_accessible?
+          !private_predicate? && predicate_exists?
+        end
 
-        # support 1.8.7
-        if methods.first.is_a? String
-          def is_private_on? actual
-            actual.private_methods.include? predicate.to_s
+        # support 1.8.7, evaluate once at load time for performance
+        if String === methods.first
+          def private_predicate?
+            @actual.private_methods.include? predicate.to_s
           end
         else
-          def is_private_on? actual
-            actual.private_methods.include? predicate
+          def private_predicate?
+            @actual.private_methods.include? predicate
           end
         end
 
+        def predicate_exists?
+          actual.respond_to?(predicate) || actual.respond_to?(present_tense_predicate)
+        end
+
+        def predicate_matches?
+          method_name = actual.respond_to?(predicate) ? predicate : present_tense_predicate
+          @predicate_matches = actual.__send__(method_name, *@args, &@block)
+        end
+
         def predicate
-          "#{@expected}?".to_sym
+          :"#{@expected}?"
         end
 
         def present_tense_predicate
-          "#{@expected}s?".to_sym
+          :"#{@expected}s?"
         end
 
         def parse_expected(expected)
@@ -199,6 +261,19 @@ module RSpec
         def prefix_to_sentence
           split_words(@prefix)
         end
+
+        def failure_message_expecting(value)
+          validity_message ||
+            "expected `#{@actual.inspect}.#{predicate}#{args_to_s}` to return #{value}, got #{@predicate_matches.inspect}"
+        end
+
+        def validity_message
+          if private_predicate?
+            "expected #{@actual} to respond to `#{predicate}` but `#{predicate}` is a private method"
+          elsif !predicate_exists?
+            "expected #{@actual} to respond to `#{predicate}`"
+          end
+        end
       end
     end
   end