rspec-expectations 3.1.2 → 3.2.0

data/lib/rspec/matchers/built_in.rb

@@ -24,7 +24,7 @@ module RSpec
       autoload :Compound,                'rspec/matchers/built_in/compound'
       autoload :ContainExactly,          'rspec/matchers/built_in/contain_exactly'
       autoload :Cover,                   'rspec/matchers/built_in/cover'
-      autoload :EndWith,                 'rspec/matchers/built_in/start_and_end_with'
+      autoload :EndWith,                 'rspec/matchers/built_in/start_or_end_with'
       autoload :Eq,                      'rspec/matchers/built_in/eq'
       autoload :Eql,                     'rspec/matchers/built_in/eql'
       autoload :Equal,                   'rspec/matchers/built_in/equal'
@@ -41,7 +41,7 @@ module RSpec
       autoload :RaiseError,              'rspec/matchers/built_in/raise_error'
       autoload :RespondTo,               'rspec/matchers/built_in/respond_to'
       autoload :Satisfy,                 'rspec/matchers/built_in/satisfy'
-      autoload :StartWith,               'rspec/matchers/built_in/start_and_end_with'
+      autoload :StartWith,               'rspec/matchers/built_in/start_or_end_with'
       autoload :ThrowSymbol,             'rspec/matchers/built_in/throw_symbol'
       autoload :YieldControl,            'rspec/matchers/built_in/yield'
       autoload :YieldSuccessiveArgs,     'rspec/matchers/built_in/yield'

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

@@ -215,7 +215,7 @@ module RSpec
       private
 
         def predicate_accessible?
-          !private_predicate? && predicate_exists?
+          actual.respond_to?(predicate) || actual.respond_to?(present_tense_predicate)
         end
 
         # support 1.8.7, evaluate once at load time for performance
@@ -229,10 +229,6 @@ module RSpec
           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)
@@ -265,11 +261,11 @@ module RSpec
         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
+          return nil if predicate_accessible?
+
+          msg = "expected #{@actual} to respond to `#{predicate}`"
+          msg << " but `#{predicate}` is a private method" if private_predicate?
+          msg
         end
       end
     end

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

@@ -3,9 +3,10 @@ module RSpec
     module BuiltIn
       # @api private
       # Base class for `and` and `or` compound matchers.
+      # rubocop:disable ClassLength
       class Compound < BaseMatcher
         # @private
-        attr_reader :matcher_1, :matcher_2
+        attr_reader :matcher_1, :matcher_2, :evaluator
 
         def initialize(matcher_1, matcher_2)
           @matcher_1 = matcher_1
@@ -36,6 +37,28 @@ module RSpec
           NestedEvaluator.matcher_expects_call_stack_jump?(matcher_2)
         end
 
+        # @api private
+        # @return [Boolean]
+        def diffable?
+          matcher_is_diffable?(matcher_1) || matcher_is_diffable?(matcher_2)
+        end
+
+        # @api private
+        # @return [RSpec::Matchers::ExpectedsForMultipleDiffs]
+        def expected
+          return nil unless evaluator
+          ::RSpec::Matchers::ExpectedsForMultipleDiffs.for_many_matchers(diffable_matcher_list)
+        end
+
+      protected
+
+        def diffable_matcher_list
+          list = []
+          list.concat(diffable_matcher_list_for(matcher_1)) unless matcher_1_matches?
+          list.concat(diffable_matcher_list_for(matcher_2)) unless matcher_2_matches?
+          list
+        end
+
       private
 
         def initialize_copy(other)
@@ -88,11 +111,11 @@ module RSpec
         end
 
         def matcher_1_matches?
-          @evaluator.matcher_matches?(matcher_1)
+          evaluator.matcher_matches?(matcher_1)
         end
 
         def matcher_2_matches?
-          @evaluator.matcher_matches?(matcher_2)
+          evaluator.matcher_matches?(matcher_2)
         end
 
         def matcher_supports_block_expectations?(matcher)
@@ -101,6 +124,18 @@ module RSpec
           false
         end
 
+        def matcher_is_diffable?(matcher)
+          matcher.diffable?
+        rescue NoMethodError
+          false
+        end
+
+        def diffable_matcher_list_for(matcher)
+          return [] unless matcher_is_diffable?(matcher)
+          return matcher.diffable_matcher_list if Compound === matcher
+          [matcher]
+        end
+
         # For value expectations, we can evaluate the matchers sequentially.
         class SequentialEvaluator
           def initialize(actual, *)

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

@@ -10,13 +10,21 @@ module RSpec
 
         def initialize(expected)
           @expected = expected
+          @values = {}
           @respond_to_failed = false
+          @negated = false
+        end
+
+        # @private
+        def actual
+          @values
         end
 
         # @api private
         # @return [Boolean]
         def matches?(actual)
           @actual = actual
+          @negated = false
           return false unless respond_to_attributes?
           perform_match(:all?)
         end
@@ -25,6 +33,7 @@ module RSpec
         # @return [Boolean]
         def does_not_match?(actual)
           @actual = actual
+          @negated = true
           return false unless respond_to_attributes?
           perform_match(:none?)
         end
@@ -36,33 +45,49 @@ module RSpec
           improve_hash_formatting "have attributes #{described_items.inspect}"
         end
 
+        # @api private
+        # @return [Boolean]
+        def diffable?
+          !@respond_to_failed && !@negated
+        end
+
         # @api private
         # @return [String]
         def failure_message
-          respond_to_failure_message_or { super }
+          respond_to_failure_message_or do
+            "expected #{@actual.inspect} to #{description} but had attributes #{ formatted_values }"
+          end
         end
 
         # @api private
         # @return [String]
         def failure_message_when_negated
-          respond_to_failure_message_or { super }
+          respond_to_failure_message_or { "expected #{@actual.inspect} not to #{description}" }
         end
 
       private
 
+        def cache_all_values
+          @values = {}
+          expected.each do |attribute_key, _attribute_value|
+            actual_value = @actual.__send__(attribute_key)
+            @values[attribute_key] = actual_value
+          end
+        end
+
         def perform_match(predicate)
+          cache_all_values
           expected.__send__(predicate) do |attribute_key, attribute_value|
             actual_has_attribute?(attribute_key, attribute_value)
           end
         end
 
         def actual_has_attribute?(attribute_key, attribute_value)
-          actual_value = actual.__send__(attribute_key)
-          values_match?(attribute_value, actual_value)
+          values_match?(attribute_value, @values.fetch(attribute_key))
         end
 
         def respond_to_attributes?
-          matches = respond_to_matcher.matches?(actual)
+          matches = respond_to_matcher.matches?(@actual)
           @respond_to_failed = !matches
           matches
         end
@@ -78,6 +103,10 @@ module RSpec
             improve_hash_formatting(yield)
           end
         end
+
+        def formatted_values
+          improve_hash_formatting(@values.inspect)
+        end
       end
     end
   end

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

@@ -33,13 +33,13 @@ module RSpec
         # @api private
         # @return [String]
         def failure_message
-          improve_hash_formatting(super) + invalid_type_message
+          improve_hash_formatting(super) + invalid_object_message
         end
 
         # @api private
         # @return [String]
         def failure_message_when_negated
-          improve_hash_formatting(super) + invalid_type_message
+          improve_hash_formatting(super) + invalid_object_message
         end
 
         # @api private
@@ -50,7 +50,7 @@ module RSpec
 
       private
 
-        def invalid_type_message
+        def invalid_object_message
           return '' if actual.respond_to?(:include?)
           ", but it does not respond to `include?`"
         end

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

@@ -1,4 +1,5 @@
 require 'stringio'
+require 'tempfile'
 
 module RSpec
   module Matchers
@@ -27,6 +28,7 @@ module RSpec
 
         # @api public
         # Tells the matcher to match against stdout.
+        # Works only when the main Ruby process prints to stdout
         def to_stdout
           @stream_capturer = CaptureStdout
           self
@@ -34,11 +36,30 @@ module RSpec
 
         # @api public
         # Tells the matcher to match against stderr.
+        # Works only when the main Ruby process prints to stderr
         def to_stderr
           @stream_capturer = CaptureStderr
           self
         end
 
+        # @api public
+        # Tells the matcher to match against stdout.
+        # Works when subprocesses print to stdout as well.
+        # This is significantly (~30x) slower than `to_stdout`
+        def to_stdout_from_any_process
+          @stream_capturer = CaptureStreamToTempfile.new("stdout", $stdout)
+          self
+        end
+
+        # @api public
+        # Tells the matcher to match against stderr.
+        # Works when subprocesses print to stderr as well.
+        # This is significantly (~30x) slower than `to_stderr`
+        def to_stderr_from_any_process
+          @stream_capturer = CaptureStreamToTempfile.new("stderr", $stderr)
+          self
+        end
+
         # @api private
         # @return [String]
         def failure_message
@@ -147,6 +168,26 @@ module RSpec
           $stderr = original_stream
         end
       end
+
+      # @private
+      class CaptureStreamToTempfile < Struct.new(:name, :stream)
+        def capture(block)
+          original_stream = stream.clone
+          captured_stream = Tempfile.new(name)
+
+          begin
+            captured_stream.sync = true
+            stream.reopen(captured_stream)
+            block.call
+            captured_stream.rewind
+            captured_stream.read
+          ensure
+            stream.reopen(original_stream)
+            captured_stream.close
+            captured_stream.unlink
+          end
+        end
+      end
     end
   end
 end

data/lib/rspec/matchers/built_in/{start_and_end_with.rb → start_or_end_with.rb}

@@ -4,7 +4,7 @@ module RSpec
       # @api private
       # Base class for the `end_with` and `start_with` matchers.
       # Not intended to be instantiated directly.
-      class StartAndEndWith < BaseMatcher
+      class StartOrEndWith < BaseMatcher
         def initialize(*expected)
           @actual_does_not_have_ordered_elements = false
           @expected = expected.length == 1 ? expected.first : expected
@@ -31,11 +31,11 @@ module RSpec
 
       private
 
-        def match(expected, actual)
+        def match(_expected, actual)
           return false unless actual.respond_to?(:[])
 
           begin
-            return subset_matches? if !(Struct === expected) && expected.respond_to?(:length)
+            return true if subsets_comparable? && subset_matches?
             element_matches?
           rescue ArgumentError
             @actual_does_not_have_ordered_elements = true
@@ -43,15 +43,25 @@ module RSpec
           end
         end
 
-        def actual_is_unordered
-          ArgumentError.new("#{actual.inspect} does not have ordered elements")
+        def subsets_comparable?
+          # Structs support the Enumerable interface but don't really have
+          # the semantics of a subset of a larger set...
+          return false if Struct === expected
+
+          expected.respond_to?(:length)
         end
       end
 
+      # For RSpec 3.1, the base class was named `StartAndEndWith`. For SemVer reasons,
+      # we still provide this constant until 4.0.
+      # @deprecated Use StartOrEndWith instead.
+      # @private
+      StartAndEndWith = StartOrEndWith
+
       # @api private
       # Provides the implementation for `start_with`.
       # Not intended to be instantiated directly.
-      class StartWith < StartAndEndWith
+      class StartWith < StartOrEndWith
       private
 
         def subset_matches?
@@ -66,7 +76,7 @@ module RSpec
       # @api private
       # Provides the implementation for `end_with`.
       # Not intended to be instantiated directly.
-      class EndWith < StartAndEndWith
+      class EndWith < StartOrEndWith
       private
 
         def subset_matches?

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

@@ -94,8 +94,7 @@ module RSpec
       # Not intended to be instantiated directly.
       class YieldControl < BaseMatcher
         def initialize
-          @expectation_type = nil
-          @expected_yields_count = nil
+          at_least(:once)
         end
 
         # @api public
@@ -151,11 +150,7 @@ module RSpec
           @probe = YieldProbe.probe(block)
           return false unless @probe.has_block?
 
-          if @expectation_type
-            @probe.num_yields.__send__(@expectation_type, @expected_yields_count)
-          else
-            @probe.yielded_once?(:yield_control)
-          end
+          @probe.num_yields.__send__(@expectation_type, @expected_yields_count)
         end
 
         # @private
@@ -195,10 +190,11 @@ module RSpec
         def failure_reason
           return " but was not a block" unless @probe.has_block?
           return '' unless @expected_yields_count
-          " #{human_readable_expecation_type}#{human_readable_count}"
+          " #{human_readable_expectation_type}#{human_readable_count(@expected_yields_count)}" \
+          " but yielded #{human_readable_count(@probe.num_yields)}"
         end
 
-        def human_readable_expecation_type
+        def human_readable_expectation_type
           case @expectation_type
           when :<= then 'at most '
           when :>= then 'at least '
@@ -206,11 +202,11 @@ module RSpec
           end
         end
 
-        def human_readable_count
-          case @expected_yields_count
+        def human_readable_count(count)
+          case count
           when 1 then "once"
           when 2 then "twice"
-          else "#{@expected_yields_count} times"
+          else "#{count} times"
           end
         end
       end

data/lib/rspec/matchers/dsl.rb

@@ -5,12 +5,30 @@ module RSpec
       # Defines a custom matcher.
       # @see RSpec::Matchers
       def define(name, &declarations)
-        define_method name do |*expected|
-          RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected)
+        warn_about_block_args(name, declarations)
+        define_method name do |*expected, &block_arg|
+          RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected, &block_arg)
         end
       end
       alias_method :matcher, :define
 
+    private
+
+      if Proc.method_defined?(:parameters)
+        def warn_about_block_args(name, declarations)
+          declarations.parameters.each do |type, arg_name|
+            next unless type == :block
+            RSpec.warning("Your `#{name}` custom matcher receives a block argument (`#{arg_name}`), " \
+                          "but due to limitations in ruby, RSpec cannot provide the block. Instead, " \
+                          "use the `block_arg` method to access the block")
+          end
+        end
+      else
+        def warn_about_block_args(*)
+          # There's no way to detect block params on 1.8 since the method reflection APIs don't expose it
+        end
+      end
+
       RSpec.configure { |c| c.extend self } if RSpec.respond_to?(:configure)
 
       # Contains the methods that are available from within the
@@ -165,6 +183,12 @@ module RSpec
         # hash been enabled, the chained method name and args will be added to the
         # default description and failure message.
         #
+        # In the common case where you just want the chained method to store some
+        # value(s) for later use (e.g. in `match`), you can provide one or more
+        # attribute names instead of a block; the chained method will store its
+        # arguments in instance variables with those names, and the values will
+        # be exposed via getters.
+        #
         # @example
         #
         #     RSpec::Matchers.define :have_errors_on do |key|
@@ -178,19 +202,40 @@ module RSpec
         #     end
         #
         #     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|
+        def chain(method_name, *attr_names, &definition)
+          unless block_given? ^ attr_names.any?
+            raise ArgumentError, "You must pass either a block or some attribute names (but not both) to `chain`."
+          end
+
+          definition = assign_attributes(attr_names) if attr_names.any?
+
+          define_user_override(method_name, definition) do |*args, &block|
             super(*args, &block)
-            @chained_method_clauses.push([name, args])
+            @chained_method_clauses.push([method_name, args])
             self
           end
         end
 
+        def assign_attributes(attr_names)
+          attr_reader(*attr_names)
+          private(*attr_names)
+
+          lambda do |*attr_values|
+            attr_names.zip(attr_values) do |attr_name, attr_value|
+              instance_variable_set(:"@#{attr_name}", attr_value)
+            end
+          end
+        end
+
+        # assign_attributes isn't defined in the private section below because
+        # that makes MRI 1.9.2 emit a warning about private attributes.
+        private :assign_attributes
+
       private
 
         # Does the following:
         #
-        # - Defines the named method usign a user-provided block
+        # - Defines the named method using 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
@@ -309,13 +354,17 @@ module RSpec
         # Could be useful to extract details for a failure message.
         attr_reader :rescued_exception
 
+        # The block parameter used in the expectation
+        attr_reader :block_arg
+
         # @api private
-        def initialize(name, declarations, matcher_execution_context, *expected)
+        def initialize(name, declarations, matcher_execution_context, *expected, &block_arg)
           @name     = name
           @actual   = nil
           @expected_as_array = expected
           @matcher_execution_context = matcher_execution_context
           @chained_method_clauses = []
+          @block_arg = block_arg
 
           class << self
             # See `Macros#define_user_override` above, for an explanation.