rspec-expectations 3.8.6

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

@@ -0,0 +1,428 @@
+module RSpec
+  module Matchers
+    module BuiltIn
+      # @api private
+      # Provides the implementation for `change`.
+      # Not intended to be instantiated directly.
+      class Change < BaseMatcher
+        # @api public
+        # Specifies the delta of the expected change.
+        def by(expected_delta)
+          ChangeRelatively.new(change_details, expected_delta, :by) do |actual_delta|
+            values_match?(expected_delta, actual_delta)
+          end
+        end
+
+        # @api public
+        # Specifies a minimum delta of the expected change.
+        def by_at_least(minimum)
+          ChangeRelatively.new(change_details, minimum, :by_at_least) do |actual_delta|
+            actual_delta >= minimum
+          end
+        end
+
+        # @api public
+        # Specifies a maximum delta of the expected change.
+        def by_at_most(maximum)
+          ChangeRelatively.new(change_details, maximum, :by_at_most) do |actual_delta|
+            actual_delta <= maximum
+          end
+        end
+
+        # @api public
+        # Specifies the new value you expect.
+        def to(value)
+          ChangeToValue.new(change_details, value)
+        end
+
+        # @api public
+        # Specifies the original value.
+        def from(value)
+          ChangeFromValue.new(change_details, value)
+        end
+
+        # @private
+        def matches?(event_proc)
+          raise_block_syntax_error if block_given?
+          perform_change(event_proc) && change_details.changed?
+        end
+
+        def does_not_match?(event_proc)
+          raise_block_syntax_error if block_given?
+          perform_change(event_proc) && !change_details.changed?
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          "expected #{change_details.value_representation} to have changed, " \
+          "but #{positive_failure_reason}"
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected #{change_details.value_representation} not to have changed, " \
+          "but #{negative_failure_reason}"
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          "change #{change_details.value_representation}"
+        end
+
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
+      private
+
+        def initialize(receiver=nil, message=nil, &block)
+          @receiver = receiver
+          @message = message
+          @block = block
+        end
+
+        def change_details
+          @change_details ||= ChangeDetails.new(matcher_name, @receiver, @message, &@block)
+        end
+
+        def perform_change(event_proc)
+          @event_proc = event_proc
+          change_details.perform_change(event_proc) do |actual_before|
+            # pre-compute values derived from the `before` value before the
+            # mutation is applied, in case the specified mutation is mutation
+            # of a single object (rather than a changing what object a method
+            # returns). We need to cache these values before the `before` value
+            # they are based on potentially gets mutated.
+            @actual_before_description = description_of(actual_before)
+          end
+        end
+
+        def raise_block_syntax_error
+          raise SyntaxError, "Block not received by the `change` matcher. " \
+          "Perhaps you want to use `{ ... }` instead of do/end?"
+        end
+
+        def positive_failure_reason
+          return "was not given a block" unless Proc === @event_proc
+          "is still #{@actual_before_description}"
+        end
+
+        def negative_failure_reason
+          return "was not given a block" unless Proc === @event_proc
+          "did change from #{@actual_before_description} " \
+          "to #{description_of change_details.actual_after}"
+        end
+      end
+
+      # Used to specify a relative change.
+      # @api private
+      class ChangeRelatively < BaseMatcher
+        def initialize(change_details, expected_delta, relativity, &comparer)
+          @change_details = change_details
+          @expected_delta = expected_delta
+          @relativity     = relativity
+          @comparer       = comparer
+        end
+
+        # @private
+        def failure_message
+          "expected #{@change_details.value_representation} to have changed " \
+          "#{@relativity.to_s.tr('_', ' ')} " \
+          "#{description_of @expected_delta}, but #{failure_reason}"
+        end
+
+        # @private
+        def matches?(event_proc)
+          @event_proc = event_proc
+          @change_details.perform_change(event_proc) && @comparer.call(@change_details.actual_delta)
+        end
+
+        # @private
+        def does_not_match?(_event_proc)
+          raise NotImplementedError, "`expect { }.not_to change " \
+            "{ }.#{@relativity}()` is not supported"
+        end
+
+        # @private
+        def description
+          "change #{@change_details.value_representation} " \
+          "#{@relativity.to_s.tr('_', ' ')} #{description_of @expected_delta}"
+        end
+
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
+      private
+
+        def failure_reason
+          return "was not given a block" unless Proc === @event_proc
+          "was changed by #{description_of @change_details.actual_delta}"
+        end
+      end
+
+      # @api private
+      # Base class for specifying a change from and/or to specific values.
+      class SpecificValuesChange < BaseMatcher
+        # @private
+        MATCH_ANYTHING = ::Object.ancestors.last
+
+        def initialize(change_details, from, to)
+          @change_details  = change_details
+          @expected_before = from
+          @expected_after  = to
+        end
+
+        # @private
+        def matches?(event_proc)
+          perform_change(event_proc) && @change_details.changed? && @matches_before && matches_after?
+        end
+
+        # @private
+        def description
+          "change #{@change_details.value_representation} #{change_description}"
+        end
+
+        # @private
+        def failure_message
+          return not_given_a_block_failure unless Proc === @event_proc
+          return before_value_failure      unless @matches_before
+          return did_not_change_failure    unless @change_details.changed?
+          after_value_failure
+        end
+
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
+      private
+
+        def perform_change(event_proc)
+          @event_proc = event_proc
+          @change_details.perform_change(event_proc) do |actual_before|
+            # pre-compute values derived from the `before` value before the
+            # mutation is applied, in case the specified mutation is mutation
+            # of a single object (rather than a changing what object a method
+            # returns). We need to cache these values before the `before` value
+            # they are based on potentially gets mutated.
+            @matches_before = values_match?(@expected_before, actual_before)
+            @actual_before_description = description_of(actual_before)
+          end
+        end
+
+        def matches_after?
+          values_match?(@expected_after, @change_details.actual_after)
+        end
+
+        def before_value_failure
+          "expected #{@change_details.value_representation} " \
+          "to have initially been #{description_of @expected_before}, " \
+          "but was #{@actual_before_description}"
+        end
+
+        def after_value_failure
+          "expected #{@change_details.value_representation} " \
+          "to have changed to #{description_of @expected_after}, " \
+          "but is now #{description_of @change_details.actual_after}"
+        end
+
+        def did_not_change_failure
+          "expected #{@change_details.value_representation} " \
+          "to have changed #{change_description}, but did not change"
+        end
+
+        def did_change_failure
+          "expected #{@change_details.value_representation} not to have changed, but " \
+          "did change from #{@actual_before_description} " \
+          "to #{description_of @change_details.actual_after}"
+        end
+
+        def not_given_a_block_failure
+          "expected #{@change_details.value_representation} to have changed " \
+          "#{change_description}, but was not given a block"
+        end
+      end
+
+      # @api private
+      # Used to specify a change from a specific value
+      # (and, optionally, to a specific value).
+      class ChangeFromValue < SpecificValuesChange
+        def initialize(change_details, expected_before)
+          @description_suffix = nil
+          super(change_details, expected_before, MATCH_ANYTHING)
+        end
+
+        # @api public
+        # Specifies the new value you expect.
+        def to(value)
+          @expected_after     = value
+          @description_suffix = " to #{description_of value}"
+          self
+        end
+
+        # @private
+        def does_not_match?(event_proc)
+          if @description_suffix
+            raise NotImplementedError, "`expect { }.not_to change { }.to()` " \
+              "is not supported"
+          end
+
+          perform_change(event_proc) && !@change_details.changed? && @matches_before
+        end
+
+        # @private
+        def failure_message_when_negated
+          return not_given_a_block_failure unless Proc === @event_proc
+          return before_value_failure unless @matches_before
+          did_change_failure
+        end
+
+      private
+
+        def change_description
+          "from #{description_of @expected_before}#{@description_suffix}"
+        end
+      end
+
+      # @api private
+      # Used to specify a change to a specific value
+      # (and, optionally, from a specific value).
+      class ChangeToValue < SpecificValuesChange
+        def initialize(change_details, expected_after)
+          @description_suffix = nil
+          super(change_details, MATCH_ANYTHING, expected_after)
+        end
+
+        # @api public
+        # Specifies the original value.
+        def from(value)
+          @expected_before    = value
+          @description_suffix = " from #{description_of value}"
+          self
+        end
+
+        # @private
+        def does_not_match?(_event_proc)
+          raise NotImplementedError, "`expect { }.not_to change { }.to()` " \
+            "is not supported"
+        end
+
+      private
+
+        def change_description
+          "to #{description_of @expected_after}#{@description_suffix}"
+        end
+      end
+
+      # @private
+      # Encapsulates the details of the before/after values.
+      #
+      # Note that this class exposes the `actual_after` value, to allow the
+      # matchers above to derive failure messages, etc from the value on demand
+      # as needed, but it intentionally does _not_ expose the `actual_before`
+      # value. Some usages of the `change` matcher mutate a specific object
+      # returned by the value proc, which means that failure message snippets,
+      # etc, which are derived from the `before` value may not be accurate if
+      # they are lazily computed as needed. We must pre-compute them before
+      # applying the change in the `expect` block. To ensure that all `change`
+      # matchers do that properly, we do not expose the `actual_before` value.
+      # Instead, matchers must pass a block to `perform_change`, which yields
+      # the `actual_before` value before applying the change.
+      class ChangeDetails
+        attr_reader :actual_after
+
+        def initialize(matcher_name, receiver=nil, message=nil, &block)
+          if receiver && !message
+            raise(
+              ArgumentError,
+              "`change` requires either an object and message " \
+              "(`change(obj, :msg)`) or a block (`change { }`). " \
+              "You passed an object but no message."
+            )
+          end
+
+          @matcher_name = matcher_name
+          @receiver = receiver
+          @message = message
+          @value_proc = block
+        end
+
+        def value_representation
+          @value_representation ||=
+            if @message
+              "`#{message_notation(@receiver, @message)}`"
+            elsif (value_block_snippet = extract_value_block_snippet)
+              "`#{value_block_snippet}`"
+            else
+              'result'
+            end
+        end
+
+        def perform_change(event_proc)
+          @actual_before = evaluate_value_proc
+          @before_hash = @actual_before.hash
+          yield @actual_before if block_given?
+
+          return false unless Proc === event_proc
+          event_proc.call
+
+          @actual_after = evaluate_value_proc
+          @actual_hash = @actual_after.hash
+          true
+        end
+
+        def changed?
+          # Consider it changed if either:
+          #
+          # - The before/after values are unequal
+          # - The before/after values have different hash values
+          #
+          # The latter case specifically handles the case when the value proc
+          # returns the exact same object, but it has been mutated.
+          #
+          # Note that it is not sufficient to only check the hashes; it is
+          # possible for two values to be unequal (and of different classes)
+          # but to return the same hash value. Also, some objects may change
+          # their hash after being compared with `==`/`!=`.
+          @actual_before != @actual_after || @before_hash != @actual_hash
+        end
+
+        def actual_delta
+          @actual_after - @actual_before
+        end
+
+      private
+
+        def evaluate_value_proc
+          @value_proc ? @value_proc.call : @receiver.__send__(@message)
+        end
+
+        def message_notation(receiver, message)
+          case receiver
+          when Module
+            "#{receiver}.#{message}"
+          else
+            "#{Support.class_of(receiver)}##{message}"
+          end
+        end
+
+        if RSpec::Support::RubyFeatures.ripper_supported?
+          def extract_value_block_snippet
+            return nil unless @value_proc
+            Expectations::BlockSnippetExtractor.try_extracting_single_line_body_of(@value_proc, @matcher_name)
+          end
+        else
+          def extract_value_block_snippet
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,271 @@
+module RSpec
+  module Matchers
+    module BuiltIn
+      # @api private
+      # Base class for `and` and `or` compound matchers.
+      class Compound < BaseMatcher
+        # @private
+        attr_reader :matcher_1, :matcher_2, :evaluator
+
+        def initialize(matcher_1, matcher_2)
+          @matcher_1 = matcher_1
+          @matcher_2 = matcher_2
+        end
+
+        # @private
+        def does_not_match?(_actual)
+          raise NotImplementedError, "`expect(...).not_to matcher.#{conjunction} matcher` " \
+            "is not supported, since it creates a bit of an ambiguity. Instead, define negated versions " \
+            "of whatever matchers you wish to negate with `RSpec::Matchers.define_negated_matcher` and " \
+            "use `expect(...).to matcher.#{conjunction} matcher`."
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          "#{matcher_1.description} #{conjunction} #{matcher_2.description}"
+        end
+
+        def supports_block_expectations?
+          matcher_supports_block_expectations?(matcher_1) &&
+          matcher_supports_block_expectations?(matcher_2)
+        end
+
+        def expects_call_stack_jump?
+          NestedEvaluator.matcher_expects_call_stack_jump?(matcher_1) ||
+          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)
+          @matcher_1 = @matcher_1.clone
+          @matcher_2 = @matcher_2.clone
+          super
+        end
+
+        def match(_expected, actual)
+          evaluator_klass = if supports_block_expectations? && Proc === actual
+                              NestedEvaluator
+                            else
+                              SequentialEvaluator
+                            end
+
+          @evaluator = evaluator_klass.new(actual, matcher_1, matcher_2)
+        end
+
+        def indent_multiline_message(message)
+          message.lines.map do |line|
+            line =~ /\S/ ? '   ' + line : line
+          end.join
+        end
+
+        def compound_failure_message
+          "#{indent_multiline_message(matcher_1.failure_message.sub(/\n+\z/, ''))}" \
+          "\n\n...#{conjunction}:" \
+          "\n\n#{indent_multiline_message(matcher_2.failure_message.sub(/\A\n+/, ''))}"
+        end
+
+        def matcher_1_matches?
+          evaluator.matcher_matches?(matcher_1)
+        end
+
+        def matcher_2_matches?
+          evaluator.matcher_matches?(matcher_2)
+        end
+
+        def matcher_supports_block_expectations?(matcher)
+          matcher.supports_block_expectations?
+        rescue NoMethodError
+          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, *)
+            @actual = actual
+          end
+
+          def matcher_matches?(matcher)
+            matcher.matches?(@actual)
+          end
+        end
+
+        # Normally, we evaluate the matching sequentially. For an expression like
+        # `expect(x).to foo.and bar`, this becomes:
+        #
+        #   expect(x).to foo
+        #   expect(x).to bar
+        #
+        # For block expectations, we need to nest them instead, so that
+        # `expect { x }.to foo.and bar` becomes:
+        #
+        #   expect {
+        #     expect { x }.to foo
+        #   }.to bar
+        #
+        # This is necessary so that the `expect` block is only executed once.
+        class NestedEvaluator
+          def initialize(actual, matcher_1, matcher_2)
+            @actual        = actual
+            @matcher_1     = matcher_1
+            @matcher_2     = matcher_2
+            @match_results = {}
+
+            inner, outer = order_block_matchers
+
+            @match_results[outer] = outer.matches?(Proc.new do |*args|
+              @match_results[inner] = inner.matches?(inner_matcher_block(args))
+            end)
+          end
+
+          def matcher_matches?(matcher)
+            @match_results.fetch(matcher)
+          end
+
+        private
+
+          # Some block matchers (such as `yield_xyz`) pass args to the `expect` block.
+          # When such a matcher is used as the outer matcher, we need to forward the
+          # the args on to the `expect` block.
+          def inner_matcher_block(outer_args)
+            return @actual if outer_args.empty?
+
+            Proc.new do |*inner_args|
+              unless inner_args.empty?
+                raise ArgumentError, "(#{@matcher_1.description}) and " \
+                  "(#{@matcher_2.description}) cannot be combined in a compound expectation " \
+                  "since both matchers pass arguments to the block."
+              end
+
+              @actual.call(*outer_args)
+            end
+          end
+
+          # For a matcher like `raise_error` or `throw_symbol`, where the block will jump
+          # up the call stack, we need to order things so that it is the inner matcher.
+          # For example, we need it to be this:
+          #
+          #   expect {
+          #     expect {
+          #       x += 1
+          #       raise "boom"
+          #     }.to raise_error("boom")
+          #   }.to change { x }.by(1)
+          #
+          # ...rather than:
+          #
+          #   expect {
+          #     expect {
+          #       x += 1
+          #       raise "boom"
+          #     }.to change { x }.by(1)
+          #   }.to raise_error("boom")
+          #
+          # In the latter case, the after-block logic in the `change` matcher would never
+          # get executed because the `raise "boom"` line would jump to the `rescue` in the
+          # `raise_error` logic, so only the former case will work properly.
+          #
+          # This method figures out which matcher should be the inner matcher and which
+          # should be the outer matcher.
+          def order_block_matchers
+            return @matcher_1, @matcher_2 unless self.class.matcher_expects_call_stack_jump?(@matcher_2)
+            return @matcher_2, @matcher_1 unless self.class.matcher_expects_call_stack_jump?(@matcher_1)
+
+            raise ArgumentError, "(#{@matcher_1.description}) and " \
+              "(#{@matcher_2.description}) cannot be combined in a compound expectation " \
+              "because they both expect a call stack jump."
+          end
+
+          def self.matcher_expects_call_stack_jump?(matcher)
+            matcher.expects_call_stack_jump?
+          rescue NoMethodError
+            false
+          end
+        end
+
+        # @api public
+        # Matcher used to represent a compound `and` expectation.
+        class And < self
+          # @api private
+          # @return [String]
+          def failure_message
+            if matcher_1_matches?
+              matcher_2.failure_message
+            elsif matcher_2_matches?
+              matcher_1.failure_message
+            else
+              compound_failure_message
+            end
+          end
+
+        private
+
+          def match(*)
+            super
+            matcher_1_matches? && matcher_2_matches?
+          end
+
+          def conjunction
+            "and"
+          end
+        end
+
+        # @api public
+        # Matcher used to represent a compound `or` expectation.
+        class Or < self
+          # @api private
+          # @return [String]
+          def failure_message
+            compound_failure_message
+          end
+
+        private
+
+          def match(*)
+            super
+            matcher_1_matches? || matcher_2_matches?
+          end
+
+          def conjunction
+            "or"
+          end
+        end
+      end
+    end
+  end
+end