rspec-expectations 3.2.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3aa831b7183b5d522f5e67b19053832a7adeec29
-  data.tar.gz: fef8e60148530b9df3545e113341083c426baa56
+  metadata.gz: 050cebd3fe559b7cd5391cba39333fc9815e7650
+  data.tar.gz: 0034049cdc0f2fd7ab5210ba606b72a267b3abbc
 SHA512:
-  metadata.gz: e51ebb3d7564f575eee701467eda6e003fade12c2644b38b6b8eba5d2820bccfe60ab22d8ae410e76bd0e5c18dfdbd94298108699f5d4d6a12ee61fb65f03db1
-  data.tar.gz: 75f4ea4fd9cf63a31967aa3cceb6071de46dd57c3326fe8cd35d47710c741d45d36ba2b77593236d2f614a0b1e921c6a21e08b60c41cd23b7431e77835d68248
+  metadata.gz: afee08bfc1eedff07267817c53989802b649cab426c15f55aa869e71bac7db27eadb679b854d5c9da3bbdb7ac39bedcc7c448e8fd7ae8eec311b1a19a694ff07
+  data.tar.gz: 1215a16c5ec70686dba0fd02d4ae14c4238352a995850a4c437eda0d7a4279597e1866f7426c623afc31ba32db5215517102576a2442caeddfdc44da308e5123

data/Changelog.md

@@ -1,3 +1,54 @@
+### 3.3.0 / 2015-06-12
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.2.1...v3.3.0)
+
+Enhancements:
+
+* Expose `RSpec::Matchers::EnglishPhrasing` to make it easier to write
+  nice failure messages in custom matchers. (Jared Beck, #736)
+* Add `RSpec::Matchers::FailMatchers`, a mixin which provides
+  `fail`, `fail_with` and `fail_including` matchers for use in
+  specifying that an expectation fails for use by
+  extension/plugin authors. (Charlie Rudolph, #729)
+* Avoid loading `tempfile` (and its dependencies) unless
+  it is absolutely needed. (Myron Marston, #735)
+* Improve failure output when attempting to use `be_true` or `be_false`.
+  (Tim Wade, #744)
+* Define `RSpec::Matchers#respond_to_missing?` so that
+  `RSpec::Matchers#respond_to?` and `RSpec::Matchers#method` handle
+  dynamic predicate matchers. (Andrei Botalov, #751)
+* Use custom Time/DateTime/BigDecimal formatting for all matchers
+  so they are consistently represented in failure messages.
+  (Gavin Miller, #740)
+* Add configuration to turn off warnings about matcher combinations that
+  may cause false positives. (Jon Rowe, #768)
+* Warn when using a bare `raise_error` matcher that you may be subject to
+  false positives. (Jon Rowe, #768)
+* Warn rather than raise when using the`raise_error` matcher in negative
+  expectations that may be subject to false positives. (Jon Rowe, #775)
+* Improve failure message for `include(a, b, c)` so that if `a` and `b`
+  are included the failure message only mentions `c`. (Chris Arcand, #780)
+* Allow `satisfy` matcher to take an optional description argument
+  that will be used in the `description`, `failure_message` and
+  `failure_message_when_negated` in place of the undescriptive
+  "sastify block". (Chris Arcand, #783)
+* Add new `aggregate_failures` API that allows multiple independent
+  expectations to all fail and be listed in the failure output, rather
+  than the example aborting on the first failure. (Myron Marston, #776)
+* Improve `raise_error` matcher so that it can accept a matcher as a single argument
+  that matches the message. (Time Wade, #782)
+
+Bug Fixes:
+
+* Make `contain_exactly` / `match_array` work with strict test doubles
+  that have not defined `<=>`. (Myron Marston, #758)
+* Fix `include` matcher so that it omits the diff when it would
+  confusingly highlight items that are actually included but are not
+  an exact match in a line-by-line diff. (Tim Wade, #763)
+* Fix `match` matcher so that it does not blow up when matching a string
+  or regex against another matcher (rather than a string or regex).
+  (Myron Marston, #772)
+* Silence whitespace-only diffs. (Myron Marston, #801)
+
 ### 3.2.1 / 2015-04-06
 [Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.2.0...v3.2.1)
 
@@ -321,7 +372,7 @@ Breaking Changes for 3.0.0:
   (Sam Phippen)
 * Remove the deprecated `have`, `have_at_least` and `have_at_most` matchers.
   You can continue using those matchers through https://github.com/rspec/rspec-collection_matchers,
-  or you can rewrite your expectations with something like 
+  or you can rewrite your expectations with something like
   `expect(your_object.size).to eq(num)`. (Hugo Baraúna)
 * Rename `be_true` and `be_false` to `be_truthy` and `be_falsey`. (Sam Phippen)
 * Make `expect { }.to_not raise_error(SomeSpecificClass, message)`,
@@ -442,9 +493,9 @@ Deprecations:
 Deprecations
 
 * Deprecate `have`, `have_at_least` and `have_at_most`. You can continue using those
-	matchers through https://github.com/rspec/rspec-collection_matchers, or
-	you can rewrite your expectations with something like
-	`expect(your_object.size).to eq(num)`. (Hugo Baraúna)
+  matchers through https://github.com/rspec/rspec-collection_matchers, or
+  you can rewrite your expectations with something like
+  `expect(your_object.size).to eq(num)`. (Hugo Baraúna)
 * Deprecate `be_xyz` predicate matcher when `xyz?` is a private method.
   (Jon Rowe)
 * Deprecate `be_true`/`be_false` in favour of `be_truthy`/`be_falsey`

data/README.md

@@ -95,7 +95,7 @@ Note: The new `expect` syntax no longer supports the `=~` matcher.
 
 ```ruby
 expect(actual).to be_an_instance_of(expected) # passes if actual.class == expected
-expect(actual).to be_a(expected)              # passes if actual.is_a?(expected)
+expect(actual).to be_a(expected)              # passes if actual.kind_of?(expected)
 expect(actual).to be_an(expected)             # an alias for be_a
 expect(actual).to be_a_kind_of(expected)      # another alias
 ```

data/lib/rspec/expectations.rb

@@ -1,6 +1,7 @@
 require 'rspec/support'
 RSpec::Support.require_rspec_support "caller_filter"
 RSpec::Support.require_rspec_support "warnings"
+RSpec::Support.require_rspec_support "object_formatter"
 
 require 'rspec/matchers'
 
@@ -63,7 +64,18 @@ module RSpec
     # the user sets an expectation, it can't be caught in their
     # code by a bare `rescue`.
     # @api public
-    class ExpectationNotMetError < ::Exception
+    class ExpectationNotMetError < Exception
     end
+
+    # Exception raised from `aggregate_failures` when multiple expectations fail.
+    #
+    # @note The constant is defined here but the extensive logic of this class
+    #   is lazily defined when `FailureAggregator` is autoloaded, since we do
+    #   not need to waste time defining that functionality unless
+    #   `aggregate_failures` is used.
+    class MultipleExpectationsNotMetError < ExpectationNotMetError
+    end
+
+    autoload :FailureAggregator, "rspec/expectations/failure_aggregator"
   end
 end

data/lib/rspec/expectations/configuration.rb

@@ -18,6 +18,10 @@ module RSpec
     #
     #   RSpec::Expectations.configuration
     class Configuration
+      def initialize
+        @warn_about_potential_false_positives = true
+      end
+
       # Configures the supported syntax.
       # @param [Array<Symbol>, Symbol] values the syntaxes to enable
       # @example
@@ -133,6 +137,19 @@ module RSpec
           backtrace
         end
       end
+
+      # Configures whether RSpec will warn about matcher use which will
+      # potentially cause false positives in tests.
+      #
+      # @param value [Boolean]
+      attr_writer :warn_about_potential_false_positives
+
+      # Indicates whether RSpec will warn about matcher use which will
+      # potentially cause false positives in tests, generally you want to
+      # avoid such scenarios so this defaults to `true`.
+      def warn_about_potential_false_positives?
+        @warn_about_potential_false_positives
+      end
     end
 
     # The configuration object.

data/lib/rspec/expectations/expectation_target.rb

@@ -98,9 +98,9 @@ module RSpec
       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?`."
+        raise ExpectationNotMetError, "You must pass an argument rather than a block to use the provided " \
+          "matcher (#{RSpec::Support::ObjectFormatter.format(matcher)}), or the matcher must implement " \
+          "`supports_block_expectations?`."
       end
 
       def supports_block_expectations?(matcher)
@@ -108,12 +108,6 @@ module RSpec
       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,5 +1,3 @@
-RSpec::Support.require_rspec_support 'differ'
-
 module RSpec
   module Expectations
     class << self
@@ -26,7 +24,7 @@ module RSpec
 
         message = ::RSpec::Matchers::ExpectedsForMultipleDiffs.from(expected).message_with_diff(message, differ, actual)
 
-        raise RSpec::Expectations::ExpectationNotMetError, message
+        RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new message)
       end
     end
   end

data/lib/rspec/expectations/failure_aggregator.rb

@@ -0,0 +1,194 @@
+module RSpec
+  module Expectations
+    # @private
+    class FailureAggregator
+      attr_reader :block_label, :metadata
+
+      def aggregate
+        RSpec::Support.with_failure_notifier(self) do
+          begin
+            yield
+          rescue ExpectationNotMetError => e
+            # Normally, expectation failures will be notified via the `call` method, below,
+            # but since the failure notifier uses a thread local variable, failing expectations
+            # in another thread will still raise. We handle that here and categorize it as part
+            # of `failures` rather than letting it fall through and be categorized as part of
+            # `other_errors`.
+            failures << e
+          rescue Exception => e
+            # While it is normally a bad practice to rescue `Exception`, it's important we do
+            # so here. It's low risk (`notify_aggregated_failures` below will re-raise the exception,
+            # or raise a `MultipleExpectationsNotMetError` that includes the exception), and it's
+            # essential that the user is notified of expectation failures that may have already
+            # occurred in the `aggregate_failures` block. Those expectation failures may provide
+            # important diagnostics for understanding why this exception occurred, and if we simply
+            # allowed this exception to be raised as-is, it would (wrongly) suggest to the user
+            # that the expectation passed when it did not, which would be quite confusing.
+            other_errors << e
+          end
+        end
+
+        notify_aggregated_failures
+      end
+
+      def failures
+        @failures ||= []
+      end
+
+      def other_errors
+        @other_errors ||= []
+      end
+
+      # This method is defined to satisfy the callable interface
+      # expected by `RSpec::Support.with_failure_notifier`.
+      def call(failure, options)
+        source_id = options[:source_id]
+        return if source_id && @seen_source_ids.key?(source_id)
+
+        @seen_source_ids[source_id] = true
+        assign_backtrace(failure) unless failure.backtrace
+        failures << failure
+      end
+
+    private
+
+      if RSpec::Support::Ruby.jruby?
+        # On JRuby, `caller` and `raise` produce different backtraces with regards to `.java`
+        # stack frames. It's important that we use `raise` for JRuby to produce a backtrace
+        # that has a continuous common section with the raised `MultipleExpectationsNotMetError`,
+        # so that rspec-core's truncation logic can work properly on it to list the backtrace
+        # relative to the `aggregate_failures` block.
+        def assign_backtrace(failure)
+          raise failure
+        rescue failure.class => e
+          failure.set_backtrace(e.backtrace)
+        end
+      else
+        # Using `caller` performs better (and is simpler) than `raise` on most Rubies.
+        def assign_backtrace(failure)
+          failure.set_backtrace(caller)
+        end
+      end
+
+      def initialize(block_label, metadata)
+        @block_label     = block_label
+        @metadata        = metadata
+        @seen_source_ids = {} # don't want to load stdlib set
+      end
+
+      def notify_aggregated_failures
+        all_errors = failures + other_errors
+
+        case all_errors.size
+        when 0 then return nil
+        when 1 then RSpec::Support.notify_failure all_errors.first
+        else RSpec::Support.notify_failure MultipleExpectationsNotMetError.new(self)
+        end
+      end
+    end
+
+    # Exception raised from `aggregate_failures` when multiple expectations fail.
+    class MultipleExpectationsNotMetError
+      # @return [String] The fully formatted exception message.
+      def message
+        @message ||= (["#{summary}:"] + enumerated_failures + enumerated_errors).join("\n\n")
+      end
+
+      # @return [Array<RSpec::Expectations::ExpectationNotMetError>] The list of expectation failures.
+      def failures
+        @failure_aggregator.failures
+      end
+
+      # @return [Array<Exception>] The list of other exceptions.
+      def other_errors
+        @failure_aggregator.other_errors
+      end
+
+      # @return [Array<Exception>] The list of expectation failures and other exceptions, combined.
+      attr_reader :all_exceptions
+
+      # @return [String] The user-assigned label for the aggregation block.
+      def aggregation_block_label
+        @failure_aggregator.block_label
+      end
+
+      # @return [Hash] The metadata hash passed to `aggregate_failures`.
+      def aggregation_metadata
+        @failure_aggregator.metadata
+      end
+
+      # @return [String] A summary of the failure, including the block label and a count of failures.
+      def summary
+        "Got #{exception_count_description} from failure aggregation " \
+        "block#{block_description}"
+      end
+
+      # return [String] A description of the failure/error counts.
+      def exception_count_description
+        failure_count = pluralize("failure", failures.size)
+        return failure_count if other_errors.empty?
+        error_count = pluralize("other error", other_errors.size)
+        "#{failure_count} and #{error_count}"
+      end
+
+    private
+
+      def initialize(failure_aggregator)
+        @failure_aggregator = failure_aggregator
+        @all_exceptions = failures + other_errors
+      end
+
+      def block_description
+        return "" unless aggregation_block_label
+        " #{aggregation_block_label.inspect}"
+      end
+
+      def pluralize(noun, count)
+        "#{count} #{noun}#{'s' unless count == 1}"
+      end
+
+      def enumerated(exceptions, index_offset)
+        exceptions.each_with_index.map do |exception, index|
+          index += index_offset
+          formatted_message = yield exception
+          "#{index_label index}#{indented formatted_message, index}"
+        end
+      end
+
+      def enumerated_failures
+        enumerated(failures, 0, &:message)
+      end
+
+      def enumerated_errors
+        enumerated(other_errors, failures.size) do |error|
+          "#{error.class}: #{error.message}"
+        end
+      end
+
+      def indented(failure_message, index)
+        line_1, *rest = failure_message.strip.lines.to_a
+        first_line_indentation = ' ' * (longest_index_label_width - width_of_label(index))
+
+        first_line_indentation + line_1 + rest.map do |line|
+          line =~ /\S/ ? indentation + line : line
+        end.join
+      end
+
+      def indentation
+        @indentation ||= ' ' * longest_index_label_width
+      end
+
+      def longest_index_label_width
+        @longest_index_label_width ||= width_of_label(failures.size)
+      end
+
+      def width_of_label(index)
+        index_label(index).chars.count
+      end
+
+      def index_label(index)
+        "  #{index + 1}) "
+      end
+    end
+  end
+end

data/lib/rspec/expectations/minitest_integration.rb

@@ -7,6 +7,19 @@ Minitest::Test.class_eval do
     assert(true) # so each expectation gets counted in minitest's assertion stats
     super
   end
+
+  # Convert a `MultipleExpectationsNotMetError` to a `Minitest::Assertion` error so
+  # it gets counted in minitest's summary stats as a failure rather than an error.
+  # It would be nice to make `MultipleExpectationsNotMetError` subclass
+  # `Minitest::Assertion`, but Minitest's implementation does not treat subclasses
+  # the same, so this is the best we can do.
+  def aggregate_failures(*args, &block)
+    super
+  rescue RSpec::Expectations::MultipleExpectationsNotMetError => e
+    assertion_failed = Minitest::Assertion.new(e.message)
+    assertion_failed.set_backtrace e.backtrace
+    raise assertion_failed
+  end
 end
 
 module RSpec

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '3.2.1'
+      STRING = '3.3.0'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -3,7 +3,7 @@ RSpec::Support.require_rspec_support 'matcher_definition'
 RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relative(f) }
 
 %w[
-  pretty
+  english_phrasing
   composable
   built_in
   generated_descriptions
@@ -243,7 +243,7 @@ module RSpec
     #     alias $1 $2
     def self.alias_matcher(new_name, old_name, options={}, &description_override)
       description_override ||= lambda do |old_desc|
-        old_desc.gsub(Pretty.split_words(old_name), Pretty.split_words(new_name))
+        old_desc.gsub(EnglishPhrasing.split_words(old_name), EnglishPhrasing.split_words(new_name))
       end
       klass = options.fetch(:klass) { AliasedMatcher }
 
@@ -277,6 +277,42 @@ module RSpec
       alias_matcher(negated_name, base_name, :klass => AliasedNegatedMatcher, &description_override)
     end
 
+    # Allows multiple expectations in the provided block to fail, and then
+    # aggregates them into a single exception, rather than aborting on the
+    # first expectation failure like normal. This allows you to see all
+    # failures from an entire set of expectations without splitting each
+    # off into its own example (which may slow things down if the example
+    # setup is expensive).
+    #
+    # @param label [String] label for this aggregation block, which will be
+    #   included in the aggregated exception message.
+    # @param metadata [Hash] additional metadata about this failure aggregation
+    #   block. If multiple expectations fail, it will be exposed from the
+    #   {Expectations::MultipleExpectationsNotMetError} exception. Mostly
+    #   intended for internal RSpec use but you can use it as well.
+    # @yield Block containing as many expectation as you want. The block is
+    #   simply yielded to, so you can trust that anything that works outside
+    #   the block should work within it.
+    # @raise [Expectations::MultipleExpectationsNotMetError] raised when
+    #   multiple expectations fail.
+    # @raise [Expectations::ExpectationNotMetError] raised when a single
+    #   expectation fails.
+    # @raise [Exception] other sorts of exceptions will be raised as normal.
+    #
+    # @example
+    #   aggregate_failures("verifying response") do
+    #     expect(response.status).to eq(200)
+    #     expect(response.headers).to include("Content-Type" => "text/plain")
+    #     expect(response.body).to include("Success")
+    #   end
+    #
+    # @note The implementation of this feature uses a thread-local variable,
+    #   which means that if you have an expectation failure in another thread,
+    #   it'll abort like normal.
+    def aggregate_failures(label=nil, metadata={}, &block)
+      Expectations::FailureAggregator.new(label, metadata).aggregate(&block)
+    end
+
     # Passes if actual is truthy (anything but false or nil)
     def be_truthy
       BuiltIn::BeTruthy.new
@@ -732,7 +768,7 @@ module RSpec
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError, /oo ri/)
     #
     #   expect { do_something_risky }.not_to raise_error
-    def raise_error(error=Exception, message=nil, &block)
+    def raise_error(error=nil, message=nil, &block)
       BuiltIn::RaiseError.new(error, message, &block)
     end
     alias_method :raise_exception,  :raise_error
@@ -767,10 +803,13 @@ module RSpec
     # If you do find yourself in such a situation, you could always write
     # a custom matcher, which would likely make your specs more expressive.
     #
+    # @param description [String] optional description to be used for this matcher.
+    #
     # @example
     #   expect(5).to satisfy { |n| n > 3 }
-    def satisfy(&block)
-      BuiltIn::Satisfy.new(&block)
+    #   expect(5).to satisfy("be greater than 3") { |n| n > 3 }
+    def satisfy(description="satisfy block", &block)
+      BuiltIn::Satisfy.new(description, &block)
     end
     alias_matcher :an_object_satisfying, :satisfy
     alias_matcher :satisfying,           :satisfy
@@ -915,6 +954,7 @@ module RSpec
 
     BE_PREDICATE_REGEX = /^(be_(?:an?_)?)(.*)/
     HAS_REGEX = /^(?:have_)(.*)/
+    DYNAMIC_MATCHER_REGEX = Regexp.union(BE_PREDICATE_REGEX, HAS_REGEX)
 
     def method_missing(method, *args, &block)
       case method.to_s
@@ -927,6 +967,20 @@ module RSpec
       end
     end
 
+    if RUBY_VERSION.to_f >= 1.9
+      def respond_to_missing?(method, *)
+        method =~ DYNAMIC_MATCHER_REGEX || super
+      end
+    else # for 1.8.7
+      # :nocov:
+      def respond_to?(method, *)
+        method = method.to_s
+        method =~ DYNAMIC_MATCHER_REGEX || super
+      end
+      public :respond_to?
+      # :nocov:
+    end
+
     # @api private
     def self.is_a_matcher?(obj)
       return true  if ::RSpec::Matchers::BuiltIn::BaseMatcher === obj