rspec-expectations 3.5.0 → 3.9.0

data/lib/rspec/expectations/configuration.rb

@@ -56,6 +56,20 @@ module RSpec
         end
       end
 
+      # Configures the maximum character length that RSpec will print while
+      # formatting an object. You can set length to nil to prevent RSpec from
+      # doing truncation.
+      # @param [Fixnum] length the number of characters to limit the formatted output to.
+      # @example
+      #   RSpec.configure do |rspec|
+      #     rspec.expect_with :rspec do |c|
+      #       c.max_formatted_output_length = 200
+      #     end
+      #   end
+      def max_formatted_output_length=(length)
+        RSpec::Support::ObjectFormatter.default_instance.max_formatted_output_length = length
+      end
+
       # The list of configured syntaxes.
       # @return [Array<Symbol>] the list of configured syntaxes.
       # @example

data/lib/rspec/expectations/expectation_target.rb

@@ -48,7 +48,7 @@ module RSpec
 
       # Defines instance {ExpectationTarget} instance methods. These are defined
       # in a module so we can include it in `Minitest::Expectation` when
-      # `rspec/expectations/minitest_integration` is laoded in order to
+      # `rspec/expectations/minitest_integration` is loaded in order to
       # support usage with Minitest.
       module InstanceMethods
         # Runs the given expectation, passing if `matcher` returns true.
@@ -112,7 +112,7 @@ 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 " \
+        raise ExpectationNotMetError, "You must pass an argument rather than a block to `expect` to use the provided " \
           "matcher (#{RSpec::Support::ObjectFormatter.format(matcher)}), or the matcher must implement " \
           "`supports_block_expectations?`."
       end

data/lib/rspec/expectations/fail_with.rb

@@ -1,10 +1,18 @@
 module RSpec
   module Expectations
     class << self
+      # @private
+      class Differ
+        # @private
+        OBJECT_PREPARER = lambda do |object|
+          RSpec::Matchers::Composable.surface_descriptions_in(object)
+        end
+      end
+
       # @private
       def differ
         RSpec::Support::Differ.new(
-          :object_preparer => lambda { |object| RSpec::Matchers::Composable.surface_descriptions_in(object) },
+          :object_preparer => Differ::OBJECT_PREPARER,
           :color => RSpec::Matchers.configuration.color?
         )
       end

data/lib/rspec/expectations/handler.rb

@@ -52,7 +52,7 @@ module RSpec
       end
 
       def self.verb
-        "should"
+        'is expected to'
       end
 
       def self.should_method
@@ -82,7 +82,7 @@ module RSpec
       end
 
       def self.verb
-        "should not"
+        'is expected not to'
       end
 
       def self.should_method

data/lib/rspec/expectations/minitest_integration.rb

@@ -53,6 +53,6 @@ module RSpec
   module Expectations
     remove_const :ExpectationNotMetError
     # Exception raised when an expectation fails.
-    ExpectationNotMetError = ::Minitest::Assertion
+    const_set :ExpectationNotMetError, ::Minitest::Assertion
   end
 end

data/lib/rspec/expectations/syntax.rb

@@ -106,7 +106,7 @@ if defined?(BasicObject)
   # 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
+    # @method should(matcher, message)
     # Passes if `matcher` returns true.  Available on every `Object`.
     # @example
     #   actual.should eq expected
@@ -118,7 +118,7 @@ if defined?(BasicObject)
     # @note This is only available when you have enabled the `:should` syntax.
     # @see RSpec::Matchers
 
-    # @method should_not
+    # @method should_not(matcher, message)
     # Passes if `matcher` returns false.  Available on every `Object`.
     # @example
     #   actual.should_not eq expected

data/lib/rspec/expectations/version.rb

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

data/lib/rspec/matchers.rb

@@ -41,9 +41,9 @@ module RSpec
   #
   #     expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
   #
-  #     expect(3).to be_a_kind_of(Fixnum)        # => 3.kind_of?(Numeric)     | passes
-  #     expect(3).to be_a_kind_of(Numeric)       # => 3.kind_of?(Numeric)     | passes
-  #     expect(3).to be_an_instance_of(Fixnum)   # => 3.instance_of?(Fixnum)  | passes
+  #     expect(3).to be_a_kind_of(Integer)          # => 3.kind_of?(Numeric)     | passes
+  #     expect(3).to be_a_kind_of(Numeric)          # => 3.kind_of?(Numeric)     | passes
+  #     expect(3).to be_an_instance_of(Integer)     # => 3.instance_of?(Integer) | passes
   #     expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
   #
   # RSpec will also create custom matchers for predicates like `has_key?`. To
@@ -62,6 +62,26 @@ module RSpec
   #     RSpec::Matchers.alias_matcher :a_user_who_is_an_admin, :be_an_admin
   #     expect(user_list).to include(a_user_who_is_an_admin)
   #
+  # ## Alias Matchers
+  #
+  # With {RSpec::Matchers.alias_matcher}, you can easily create an
+  # alternate name for a given matcher.
+  #
+  # The description will also change according to the new name:
+  #
+  #     RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
+  #     sum_to(3).description # => "sum to 3"
+  #     a_list_that_sums_to(3).description # => "a list that sums to 3"
+  #
+  # or you can specify a custom description like this:
+  #
+  #     RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
+  #       description.sub("be sorted by", "a list sorted by")
+  #     end
+  #
+  #     be_sorted_by(:age).description # => "be sorted by age"
+  #     a_list_sorted_by(:age).description # => "a list sorted by age"
+  #
   # ## Custom Matchers
   #
   # When you find that none of the stock matchers provide a natural feeling
@@ -202,80 +222,53 @@ module RSpec
   # expressions, and also uses the noun-phrase wording in the matcher's `description`,
   # for readable failure messages. You can alias your custom matchers in similar fashion
   # using {RSpec::Matchers.alias_matcher}.
+  #
+  # ## Negated Matchers
+  #
+  # Sometimes if you want to test for the opposite using a more descriptive name
+  # instead of using `not_to`, you can use {RSpec::Matchers.define_negated_matcher}:
+  #
+  #     RSpec::Matchers.define_negated_matcher :exclude, :include
+  #     include(1, 2).description # => "include 1 and 2"
+  #     exclude(1, 2).description # => "exclude 1 and 2"
+  #
+  # While the most obvious negated form may be to add a `not_` prefix,
+  # the failure messages you get with that form can be confusing (e.g.
+  # "expected [actual] to not [verb], but did not"). We've found it works
+  # best to find a more positive name for the negated form, such as
+  # `avoid_changing` rather than `not_change`.
+  #
   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
+    extend ::RSpec::Matchers::DSL
 
-    # 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.
-    #
-    # @param new_name [Symbol] the new name for the matcher
-    # @param old_name [Symbol] the original name for the matcher
-    # @param options  [Hash] options for the aliased matcher
-    # @option options [Class] :klass the ruby class to use as the decorator. (Not normally used).
-    # @yield [String] optional block that, when given, is used to define the overriden
-    #   logic. The yielded arg is the original description or failure message. If no
-    #   block is provided, a default override is used based on the old and new names.
-    #
-    # @example
-    #   RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
-    #   sum_to(3).description # => "sum to 3"
-    #   a_list_that_sums_to(3).description # => "a list that sums to 3"
-    #
-    # @example
-    #   RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
-    #     description.sub("be sorted by", "a list sorted by")
-    #   end
-    #
-    #   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, options={}, &description_override)
-      description_override ||= lambda do |old_desc|
-        old_desc.gsub(EnglishPhrasing.split_words(old_name), EnglishPhrasing.split_words(new_name))
-      end
-      klass = options.fetch(:klass) { AliasedMatcher }
-
-      define_method(new_name) do |*args, &block|
-        matcher = __send__(old_name, *args, &block)
-        klass.new(matcher, description_override)
-      end
+    # @!visibility private
+    # We define this override here so we can attach a YARD macro to it.
+    # It ensures that our docs list all the matcher aliases.
+    def self.alias_matcher(*args, &block)
+      super(*args, &block)
     end
 
-    # Defines a negated matcher. The returned matcher's `description` and `failure_message`
-    # will be overriden to reflect the phrasing of the new name, and the match logic will
-    # be based on the original matcher but negated.
-    #
-    # @param negated_name [Symbol] the name for the negated matcher
-    # @param base_name [Symbol] the name of the original matcher that will be negated
-    # @yield [String] optional block that, when given, is used to define the overriden
-    #   logic. The yielded arg is the original description or failure message. If no
-    #   block is provided, a default override is used based on the old and new names.
-    #
+    # @!method self.alias_matcher(new_name, old_name, options={}, &description_override)
+    #   Extended from {RSpec::Matchers::DSL#alias_matcher}.
+
+    # @!method self.define(name, &declarations)
+    #   Extended from {RSpec::Matchers::DSL#define}.
+
+    # @!method self.define_negated_matcher(negated_name, base_name, &description_override)
+    #   Extended from {RSpec::Matchers::DSL#define_negated_matcher}.
+
+    # @method expect
+    # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
+    # `ExpectationTarget`.
     # @example
-    #   RSpec::Matchers.define_negated_matcher :exclude, :include
-    #   include(1, 2).description # => "include 1 and 2"
-    #   exclude(1, 2).description # => "exclude 1 and 2"
-    #
-    # @note While the most obvious negated form may be to add a `not_` prefix,
-    #   the failure messages you get with that form can be confusing (e.g.
-    #   "expected [actual] to not [verb], but did not"). We've found it works
-    #   best to find a more positive name for the negated form, such as
-    #   `avoid_changing` rather than `not_change`.
-    def self.define_negated_matcher(negated_name, base_name, &description_override)
-      alias_matcher(negated_name, base_name, :klass => AliasedNegatedMatcher, &description_override)
-    end
+    #   expect(actual).to eq(expected)
+    #   expect(actual).not_to eq(expected)
+    # @return [Expectations::ExpectationTarget]
+    # @see Expectations::ExpectationTarget#to
+    # @see Expectations::ExpectationTarget#not_to
 
     # Allows multiple expectations in the provided block to fail, and then
     # aggregates them into a single exception, rather than aborting on the
@@ -367,7 +360,7 @@ module RSpec
     # Passes if actual.instance_of?(expected)
     #
     # @example
-    #   expect(5).to     be_an_instance_of(Fixnum)
+    #   expect(5).to     be_an_instance_of(Integer)
     #   expect(5).not_to be_an_instance_of(Numeric)
     #   expect(5).not_to be_an_instance_of(Float)
     def be_an_instance_of(expected)
@@ -379,7 +372,7 @@ module RSpec
     # Passes if actual.kind_of?(expected)
     #
     # @example
-    #   expect(5).to     be_a_kind_of(Fixnum)
+    #   expect(5).to     be_a_kind_of(Integer)
     #   expect(5).to     be_a_kind_of(Numeric)
     #   expect(5).not_to be_a_kind_of(Float)
     def be_a_kind_of(expected)
@@ -487,7 +480,10 @@ module RSpec
     # == Notes
     #
     # Evaluates `receiver.message` or `block` before and after it
-    # evaluates the block passed to `expect`.
+    # evaluates the block passed to `expect`. If the value is the same
+    # object, its before/after `hash` value is used to see if it has changed.
+    # Therefore, your object needs to properly implement `hash` to work correctly
+    # with this matcher.
     #
     # `expect( ... ).not_to change` supports the form that specifies `from`
     # (which specifies what you expect the starting, unchanged value to be)
@@ -585,7 +581,7 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #   expect(5).to       equal(5)   # Fixnums are equal
+    #   expect(5).to       equal(5)   # Integers are equal
     #   expect("5").not_to equal("5") # Strings that look the same are not the same object
     def equal(expected)
       BuiltIn::Equal.new(expected)
@@ -688,7 +684,7 @@ module RSpec
     #     :a => {
     #       :b => a_collection_containing_exactly(
     #         a_string_starting_with("f"),
-    #         an_instance_of(Fixnum)
+    #         an_instance_of(Integer)
     #       ),
     #       :c => { :d => (a_value < 3) }
     #     }
@@ -809,7 +805,7 @@ module RSpec
     # @example
     #   expect(5).to satisfy { |n| n > 3 }
     #   expect(5).to satisfy("be greater than 3") { |n| n > 3 }
-    def satisfy(description="satisfy block", &block)
+    def satisfy(description=nil, &block)
       BuiltIn::Satisfy.new(description, &block)
     end
     alias_matcher :an_object_satisfying, :satisfy
@@ -905,7 +901,7 @@ module RSpec
     # @example
     #   expect { |b| 5.tap(&b) }.to yield_with_args # because #tap yields an arg
     #   expect { |b| 5.tap(&b) }.to yield_with_args(5) # because 5 == 5
-    #   expect { |b| 5.tap(&b) }.to yield_with_args(Fixnum) # because Fixnum === 5
+    #   expect { |b| 5.tap(&b) }.to yield_with_args(Integer) # because Integer === 5
     #   expect { |b| File.open("f.txt", &b) }.to yield_with_args(/txt/) # because /txt/ === "f.txt"
     #
     #   expect { |b| User.transaction(&b) }.not_to yield_with_args # because it yields no args
@@ -1007,31 +1003,35 @@ module RSpec
       is_a_matcher?(obj) && obj.respond_to?(:description)
     end
 
-    if RSpec::Support::Ruby.mri? && RUBY_VERSION[0, 3] == '1.9'
-      # @api private
-      # Note that `included` doesn't work for this because it is triggered
-      # _after_ `RSpec::Matchers` is an ancestor of the inclusion host, rather
-      # than _before_, like `append_features`. It's important we check this before
-      # in order to find the cases where it was already previously included.
-      def self.append_features(mod)
-        return super if mod < self # `mod < self` indicates a re-inclusion.
+    class << self
+      private
 
-        subclasses = ObjectSpace.each_object(Class).select { |c| c < mod && c < self }
-        return super unless subclasses.any?
+      if RSpec::Support::Ruby.mri? && RUBY_VERSION[0, 3] == '1.9'
+        # Note that `included` doesn't work for this because it is triggered
+        # _after_ `RSpec::Matchers` is an ancestor of the inclusion host, rather
+        # than _before_, like `append_features`. It's important we check this before
+        # in order to find the cases where it was already previously included.
+        # @api private
+        def append_features(mod)
+          return super if mod < self # `mod < self` indicates a re-inclusion.
 
-        subclasses.reject! { |s| subclasses.any? { |s2| s < s2 } } # Filter to the root ancestor.
-        subclasses = subclasses.map { |s| "`#{s}`" }.join(", ")
+          subclasses = ObjectSpace.each_object(Class).select { |c| c < mod && c < self }
+          return super unless subclasses.any?
 
-        RSpec.warning "`#{self}` has been included in a superclass (`#{mod}`) " \
-                      "after previously being included in subclasses (#{subclasses}), " \
-                      "which can trigger infinite recursion from `super` due to an MRI 1.9 bug " \
-                      "(https://redmine.ruby-lang.org/issues/3351). To work around this, " \
-                      "either upgrade to MRI 2.0+, include a dup of the module (e.g. " \
-                      "`include #{self}.dup`), or find a way to include `#{self}` in `#{mod}` " \
-                      "before it is included in subclasses (#{subclasses}). See " \
-                      "https://github.com/rspec/rspec-expectations/issues/814 for more info"
+          subclasses.reject! { |s| subclasses.any? { |s2| s < s2 } } # Filter to the root ancestor.
+          subclasses = subclasses.map { |s| "`#{s}`" }.join(", ")
 
-        super
+          RSpec.warning "`#{self}` has been included in a superclass (`#{mod}`) " \
+                        "after previously being included in subclasses (#{subclasses}), " \
+                        "which can trigger infinite recursion from `super` due to an MRI 1.9 bug " \
+                        "(https://redmine.ruby-lang.org/issues/3351). To work around this, " \
+                        "either upgrade to MRI 2.0+, include a dup of the module (e.g. " \
+                        "`include #{self}.dup`), or find a way to include `#{self}` in `#{mod}` " \
+                        "before it is included in subclasses (#{subclasses}). See " \
+                        "https://github.com/rspec/rspec-expectations/issues/814 for more info"
+
+          super
+        end
       end
     end
   end

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

@@ -73,6 +73,7 @@ module RSpec
 
         def initialize_copy(other)
           @matcher = @matcher.clone
+          @failed_objects = @failed_objects.clone
           super
         end
 

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

@@ -22,6 +22,9 @@ module RSpec
         # @private
         attr_reader :actual, :expected, :rescued_exception
 
+        # @private
+        attr_writer :matcher_name
+
         def initialize(expected=UNDEFINED)
           @expected = expected unless UNDEFINED.equal?(expected)
         end
@@ -95,6 +98,15 @@ module RSpec
           @matcher_name ||= underscore(name.split('::').last)
         end
 
+        # @private
+        def matcher_name
+          if defined?(@matcher_name)
+            @matcher_name
+          else
+            self.class.matcher_name
+          end
+        end
+
         # @private
         # Borrowed from ActiveSupport.
         def self.underscore(camel_cased_word)
@@ -153,7 +165,7 @@ module RSpec
           # you often only need to override `description`.
           # @return [String]
           def failure_message
-            "expected #{description_of @actual} to #{description}"
+            "expected #{description_of @actual} to #{description}".dup
           end
 
           # @api private
@@ -162,7 +174,7 @@ module RSpec
           # you often only need to override `description`.
           # @return [String]
           def failure_message_when_negated
-            "expected #{description_of @actual} not to #{description}"
+            "expected #{description_of @actual} not to #{description}".dup
           end
 
           # @private

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

@@ -145,7 +145,7 @@ module RSpec
         def matches?(actual)
           @actual = actual
           @actual.__send__ @operator, @expected
-        rescue ArgumentError
+        rescue ArgumentError, NoMethodError
           false
         end
 
@@ -270,7 +270,7 @@ module RSpec
         def validity_message
           return nil if predicate_accessible?
 
-          msg = "expected #{actual_formatted} to respond to `#{predicate}`"
+          msg = "expected #{actual_formatted} to respond to `#{predicate}`".dup
 
           if private_predicate?
             msg << " but `#{predicate}` is a private method"