rspec-expectations 3.6.0.beta2 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4334ca25737c438a7a9266a95fb2cd4182853299
-  data.tar.gz: 810d8162263ea539f45652f84c0bf9deec512e6b
+  metadata.gz: aa835825e71953a32260e80c58d892f5517ed692
+  data.tar.gz: 3e66073a9dbefb71be893d00692df5162826105f
 SHA512:
-  metadata.gz: b9d714c6f1f8ee892a133df714e7ffcc5afca4aa0f73735eda1478591a4aeebe3601c61d96d1ceab68c60e9f023b1f629107619ecd7150a74efa7c5ce276992d
-  data.tar.gz: 45c51f595123a44b52c02058939248bf53eb3d73e7e6305a79936250d31208e191817ff60862856accc5f34e0bc5090204617d122e9cb0dd1841143976a21237
+  metadata.gz: e967e93899006e4a6c9b419b217f6cac32aee74d60d006724db428e4d574fea2be76499759348808e50f9ba69a7e34d9472aa02eb7b23cca04e56ef9beab6743
+  data.tar.gz: 96f5ea4360e26175df7dfaae04a9f76c0d1d273ccca0e8939722947e59c7d09fd3a0c3e29eb27035101060cd80d540b90cfb6abcb4b7a40d60d5f8ae5a307a16

data/Changelog.md

@@ -1,3 +1,23 @@
+### 3.6.0 / 2017-05-04
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.6.0.beta2...v3.6.0)
+
+Enhancements:
+
+* Treat NoMethodError as a failure for comparison matchers. (Jon Rowe, #972)
+* Allow for scoped aliased and negated matchers--just call
+  `alias_matcher` or `define_negated_matcher` from within an example
+  group. (Markus Reiter, #974)
+* Improve failure message of `change` matcher with block and `satisfy` matcher
+  by including the block snippet instead of just describing it as `result` or
+  `block` when Ripper is available. (Yuji Nakayama, #987)
+
+Bug Fixes:
+
+* Fix `yield_with_args` and `yield_successive_args` matchers so that
+  they compare expected to actual args at the time the args are yielded
+  instead of at the end, in case the method that is yielding mutates the
+  arguments after yielding. (Alyssa Ross, #965)
+
 ### 3.6.0.beta2 / 2016-12-12
 [Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.6.0.beta1...v3.6.0.beta2)
 
@@ -92,7 +112,7 @@ Bug Fixes:
 
 * Fix failure message from dynamic predicate matchers when the object
   does not respond to the predicate so that it is inspected rather
-  than relying upon it's `to_s` -- that way for `nil`, `"nil"` is
+  than relying upon its `to_s` -- that way for `nil`, `"nil"` is
   printed rather than an empty string. (Myron Marston, #841)
 * Fix SystemStackError raised when diffing an Enumerable object
   whose `#each` includes the object itself. (Yuji Nakayama, #857)

data/README.md

@@ -3,7 +3,9 @@
 RSpec::Expectations lets you express expected outcomes on an object in an
 example.
 
-    expect(account.balance).to eq(Money.new(37.42, :USD))
+```ruby
+expect(account.balance).to eq(Money.new(37.42, :USD))
+```
 
 ## Install
 
@@ -150,7 +152,7 @@ expect { |b| 5.tap(&b) }.to yield_control # passes regardless of yielded args
 expect { |b| yield_if_true(true, &b) }.to yield_with_no_args # passes only if no args are yielded
 
 expect { |b| 5.tap(&b) }.to yield_with_args(5)
-expect { |b| 5.tap(&b) }.to yield_with_args(Fixnum)
+expect { |b| 5.tap(&b) }.to yield_with_args(Integer)
 expect { |b| "a string".tap(&b) }.to yield_with_args(/str/)
 
 expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
@@ -263,7 +265,7 @@ expect(hash).to match(
   :a => {
     :b => a_collection_containing_exactly(
       a_string_starting_with("f"),
-      an_instance_of(Fixnum)
+      an_instance_of(Integer)
     ),
     :c => { :d => (a_value < 3) }
   }

data/lib/rspec/expectations.rb

@@ -76,6 +76,7 @@ module RSpec
     class MultipleExpectationsNotMetError < ExpectationNotMetError
     end
 
-    autoload :FailureAggregator, "rspec/expectations/failure_aggregator"
+    autoload :BlockSnippetExtractor, "rspec/expectations/block_snippet_extractor"
+    autoload :FailureAggregator,     "rspec/expectations/failure_aggregator"
   end
 end

data/lib/rspec/expectations/block_snippet_extractor.rb

@@ -0,0 +1,253 @@
+module RSpec
+  module Expectations
+    # @private
+    class BlockSnippetExtractor # rubocop:disable Style/ClassLength
+      # rubocop should properly handle `Struct.new {}` as an inner class definition.
+
+      attr_reader :proc, :method_name
+
+      def self.try_extracting_single_line_body_of(proc, method_name)
+        lines = new(proc, method_name).body_content_lines
+        return nil unless lines.count == 1
+        lines.first
+      rescue Error
+        nil
+      end
+
+      def initialize(proc, method_name)
+        @proc = proc
+        @method_name = method_name.to_s.freeze
+      end
+
+      # Ideally we should properly handle indentations of multiline snippet,
+      # but it's not implemented yet since because we use result of this method only when it's a
+      # single line and implementing the logic introduces additional complexity.
+      def body_content_lines
+        raw_body_lines.map(&:strip).reject(&:empty?)
+      end
+
+    private
+
+      def raw_body_lines
+        raw_body_snippet.split("\n")
+      end
+
+      def raw_body_snippet
+        block_token_extractor.body_tokens.map(&:string).join
+      end
+
+      def block_token_extractor
+        @block_token_extractor ||= BlockTokenExtractor.new(method_name, source, beginning_line_number)
+      end
+
+      if RSpec.respond_to?(:world)
+        def source
+          raise TargetNotFoundError unless File.exist?(file_path)
+          RSpec.world.source_from_file(file_path)
+        end
+      else
+        RSpec::Support.require_rspec_support 'source'
+        def source
+          raise TargetNotFoundError unless File.exist?(file_path)
+          @source ||= RSpec::Support::Source.from_file(file_path)
+        end
+      end
+
+      def file_path
+        source_location.first
+      end
+
+      def beginning_line_number
+        source_location.last
+      end
+
+      def source_location
+        proc.source_location || raise(TargetNotFoundError)
+      end
+
+      Error = Class.new(StandardError)
+      TargetNotFoundError = Class.new(Error)
+      AmbiguousTargetError = Class.new(Error)
+
+      # @private
+      # Performs extraction of block body snippet using tokens,
+      # which cannot be done with node information.
+      BlockTokenExtractor = Struct.new(:method_name, :source, :beginning_line_number) do
+        attr_reader :state, :body_tokens
+
+        def initialize(*)
+          super
+          parse!
+        end
+
+        private
+
+        def parse!
+          @state = :initial
+
+          catch(:finish) do
+            source.tokens.each do |token|
+              invoke_state_handler(token)
+            end
+          end
+        end
+
+        def finish!
+          throw :finish
+        end
+
+        def invoke_state_handler(token)
+          __send__("#{state}_state", token)
+        end
+
+        def initial_state(token)
+          @state = :after_method_call if token.location == block_locator.method_call_location
+        end
+
+        def after_method_call_state(token)
+          @state = :after_opener if handle_opener_token(token)
+        end
+
+        def after_opener_state(token)
+          if handle_closer_token(token)
+            finish_or_find_next_block_if_incorrect!
+          elsif pipe_token?(token)
+            finalize_pending_tokens!
+            @state = :after_beginning_of_args
+          else
+            pending_tokens << token
+            handle_opener_token(token)
+            @state = :after_beginning_of_body unless token.type == :on_sp
+          end
+        end
+
+        def after_beginning_of_args_state(token)
+          @state = :after_beginning_of_body if pipe_token?(token)
+        end
+
+        def after_beginning_of_body_state(token)
+          if handle_closer_token(token)
+            finish_or_find_next_block_if_incorrect!
+          else
+            pending_tokens << token
+            handle_opener_token(token)
+          end
+        end
+
+        def pending_tokens
+          @pending_tokens ||= []
+        end
+
+        def finalize_pending_tokens!
+          pending_tokens.freeze.tap do
+            @pending_tokens = nil
+          end
+        end
+
+        def finish_or_find_next_block_if_incorrect!
+          body_tokens = finalize_pending_tokens!
+
+          if correct_block?(body_tokens)
+            @body_tokens = body_tokens
+            finish!
+          else
+            @state = :after_method_call
+          end
+        end
+
+        def handle_opener_token(token)
+          opener_token?(token).tap do |boolean|
+            opener_token_stack.push(token) if boolean
+          end
+        end
+
+        def opener_token?(token)
+          token.type == :on_lbrace || (token.type == :on_kw && token.string == 'do')
+        end
+
+        def handle_closer_token(token)
+          if opener_token_stack.last.closed_by?(token)
+            opener_token_stack.pop
+            opener_token_stack.empty?
+          else
+            false
+          end
+        end
+
+        def opener_token_stack
+          @opener_token_stack ||= []
+        end
+
+        def pipe_token?(token)
+          token.type == :on_op && token.string == '|'
+        end
+
+        def correct_block?(body_tokens)
+          return true if block_locator.body_content_locations.empty?
+          content_location = block_locator.body_content_locations.first
+          content_location.between?(body_tokens.first.location, body_tokens.last.location)
+        end
+
+        def block_locator
+          @block_locator ||= BlockLocator.new(method_name, source, beginning_line_number)
+        end
+      end
+
+      # @private
+      # Locates target block with node information (semantics), which tokens don't have.
+      BlockLocator = Struct.new(:method_name, :source, :beginning_line_number) do
+        def method_call_location
+          @method_call_location ||= method_ident_node.location
+        end
+
+        def body_content_locations
+          @body_content_locations ||= block_body_node.map(&:location).compact
+        end
+
+        private
+
+        def method_ident_node
+          method_call_node = block_wrapper_node.children.first
+          method_call_node.find do |node|
+            method_ident_node?(node)
+          end
+        end
+
+        def block_body_node
+          block_node = block_wrapper_node.children[1]
+          block_node.children.last
+        end
+
+        def block_wrapper_node
+          case candidate_block_wrapper_nodes.size
+          when 1
+            candidate_block_wrapper_nodes.first
+          when 0
+            raise TargetNotFoundError
+          else
+            raise AmbiguousTargetError
+          end
+        end
+
+        def candidate_block_wrapper_nodes
+          @candidate_block_wrapper_nodes ||= candidate_method_ident_nodes.map do |method_ident_node|
+            block_wrapper_node = method_ident_node.each_ancestor.find { |node| node.type == :method_add_block }
+            next nil unless block_wrapper_node
+            method_call_node = block_wrapper_node.children.first
+            method_call_node.include?(method_ident_node) ? block_wrapper_node : nil
+          end.compact
+        end
+
+        def candidate_method_ident_nodes
+          source.nodes_by_line_number[beginning_line_number].select do |node|
+            method_ident_node?(node)
+          end
+        end
+
+        def method_ident_node?(node)
+          node.type == :@ident && node.args.first == method_name
+        end
+      end
+    end
+  end
+end

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '3.6.0.beta2'
+      STRING = '3.6.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,7 +222,34 @@ 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
+    extend ::RSpec::Matchers::DSL
+
+    # @!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`.
@@ -213,70 +260,6 @@ module RSpec
     # @see ExpectationTarget#to
     # @see ExpectationTarget#not_to
 
-    # 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
-    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.
-    #
-    # @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
-
     # 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
@@ -313,6 +296,10 @@ module RSpec
       Expectations::FailureAggregator.new(label, metadata).aggregate(&block)
     end
 
+    # @!macro [attach] alias_matcher
+    #   @!parse
+    #     alias $1 $2
+
     # Passes if actual is truthy (anything but false or nil)
     def be_truthy
       BuiltIn::BeTruthy.new
@@ -367,7 +354,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 +366,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)
@@ -585,7 +572,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 +675,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 +796,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 +892,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

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)

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
 

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

@@ -8,7 +8,7 @@ module RSpec
         # @api public
         # Specifies the delta of the expected change.
         def by(expected_delta)
-          ChangeRelatively.new(@change_details, expected_delta, :by) do |actual_delta|
+          ChangeRelatively.new(change_details, expected_delta, :by) do |actual_delta|
             values_match?(expected_delta, actual_delta)
           end
         end
@@ -16,7 +16,7 @@ module RSpec
         # @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|
+          ChangeRelatively.new(change_details, minimum, :by_at_least) do |actual_delta|
             actual_delta >= minimum
           end
         end
@@ -24,7 +24,7 @@ module RSpec
         # @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|
+          ChangeRelatively.new(change_details, maximum, :by_at_most) do |actual_delta|
             actual_delta <= maximum
           end
         end
@@ -32,13 +32,13 @@ module RSpec
         # @api public
         # Specifies the new value you expect.
         def to(value)
-          ChangeToValue.new(@change_details, value)
+          ChangeToValue.new(change_details, value)
         end
 
         # @api public
         # Specifies the original value.
         def from(value)
-          ChangeFromValue.new(@change_details, value)
+          ChangeFromValue.new(change_details, value)
         end
 
         # @private
@@ -46,8 +46,8 @@ module RSpec
           @event_proc = event_proc
           return false unless Proc === event_proc
           raise_block_syntax_error if block_given?
-          @change_details.perform_change(event_proc)
-          @change_details.changed?
+          change_details.perform_change(event_proc)
+          change_details.changed?
         end
 
         def does_not_match?(event_proc)
@@ -58,21 +58,21 @@ module RSpec
         # @api private
         # @return [String]
         def failure_message
-          "expected #{@change_details.message} to have changed, " \
+          "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.message} not to have changed, " \
+          "expected #{change_details.value_representation} not to have changed, " \
           "but #{negative_failure_reason}"
         end
 
         # @api private
         # @return [String]
         def description
-          "change #{@change_details.message}"
+          "change #{change_details.value_representation}"
         end
 
         # @private
@@ -83,7 +83,13 @@ module RSpec
       private
 
         def initialize(receiver=nil, message=nil, &block)
-          @change_details = ChangeDetails.new(receiver, message, &block)
+          @receiver = receiver
+          @message = message
+          @block = block
+        end
+
+        def change_details
+          @change_details ||= ChangeDetails.new(matcher_name, @receiver, @message, &@block)
         end
 
         def raise_block_syntax_error
@@ -93,13 +99,13 @@ module RSpec
 
         def positive_failure_reason
           return "was not given a block" unless Proc === @event_proc
-          "is still #{description_of @change_details.actual_before}"
+          "is still #{description_of change_details.actual_before}"
         end
 
         def negative_failure_reason
           return "was not given a block" unless Proc === @event_proc
-          "did change from #{description_of @change_details.actual_before} " \
-          "to #{description_of @change_details.actual_after}"
+          "did change from #{description_of change_details.actual_before} " \
+          "to #{description_of change_details.actual_after}"
         end
       end
 
@@ -115,7 +121,7 @@ module RSpec
 
         # @private
         def failure_message
-          "expected #{@change_details.message} to have changed " \
+          "expected #{@change_details.value_representation} to have changed " \
           "#{@relativity.to_s.tr('_', ' ')} " \
           "#{description_of @expected_delta}, but #{failure_reason}"
         end
@@ -136,7 +142,7 @@ module RSpec
 
         # @private
         def description
-          "change #{@change_details.message} " \
+          "change #{@change_details.value_representation} " \
           "#{@relativity.to_s.tr('_', ' ')} #{description_of @expected_delta}"
         end
 
@@ -175,7 +181,7 @@ module RSpec
 
         # @private
         def description
-          "change #{@change_details.message} #{change_description}"
+          "change #{@change_details.value_representation} #{change_description}"
         end
 
         # @private
@@ -202,30 +208,30 @@ module RSpec
         end
 
         def before_value_failure
-          "expected #{@change_details.message} " \
+          "expected #{@change_details.value_representation} " \
           "to have initially been #{description_of @expected_before}, " \
           "but was #{description_of @change_details.actual_before}"
         end
 
         def after_value_failure
-          "expected #{@change_details.message} " \
+          "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.message} " \
+          "expected #{@change_details.value_representation} " \
           "to have changed #{change_description}, but did not change"
         end
 
         def did_change_failure
-          "expected #{@change_details.message} not to have changed, but " \
+          "expected #{@change_details.value_representation} not to have changed, but " \
           "did change from #{description_of @change_details.actual_before} " \
           "to #{description_of @change_details.actual_after}"
         end
 
         def not_given_a_block_failure
-          "expected #{@change_details.message} to have changed " \
+          "expected #{@change_details.value_representation} to have changed " \
           "#{change_description}, but was not given a block"
         end
       end
@@ -307,9 +313,9 @@ module RSpec
       # @private
       # Encapsulates the details of the before/after values.
       class ChangeDetails
-        attr_reader :message, :actual_before, :actual_after
+        attr_reader :actual_before, :actual_after
 
-        def initialize(receiver=nil, message=nil, &block)
+        def initialize(matcher_name, receiver=nil, message=nil, &block)
           if receiver && !message
             raise(
               ArgumentError,
@@ -318,8 +324,22 @@ module RSpec
               "You passed an object but no message."
             )
           end
-          @message    = message ? "##{message}" : "result"
-          @value_proc = block || lambda { receiver.__send__(message) }
+
+          @matcher_name = matcher_name
+          @receiver = receiver
+          @message = message
+          @value_proc = block
+        end
+
+        def value_representation
+          @value_representation ||=
+            if @message
+              "##{@message}"
+            elsif (value_block_snippet = extract_value_block_snippet)
+              "`#{value_block_snippet}`"
+            else
+              'result'
+            end
         end
 
         def perform_change(event_proc)
@@ -339,7 +359,9 @@ module RSpec
       private
 
         def evaluate_value_proc
-          case val = @value_proc.call
+          value_proc = @value_proc || lambda { @receiver.__send__(@message) }
+
+          case val = value_proc.call
           when IO # enumerable, but we don't want to dup it.
             val
           when Enumerable, String
@@ -348,6 +370,17 @@ module RSpec
             val
           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

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

@@ -172,7 +172,7 @@ module RSpec
                          "including those raised by Ruby (e.g. NoMethodError, NameError " \
                          "and ArgumentError), meaning the code you are intending to test " \
                          "may not even get reached. Instead consider using " \
-                         "`expect {}.not_to raise_error` or `expect { }.to raise_error" \
+                         "`expect { }.not_to raise_error` or `expect { }.to raise_error" \
                          "(DifferentSpecificErrorClass)`. This message can be suppressed by " \
                          "setting: `RSpec::Expectations.configuration.on_potential_false" \
                          "_positives = :nothing`")

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

@@ -5,10 +5,7 @@ module RSpec
       # Provides the implementation for `satisfy`.
       # Not intended to be instantiated directly.
       class Satisfy < BaseMatcher
-        # @private
-        attr_reader :description
-
-        def initialize(description="satisfy block", &block)
+        def initialize(description=nil, &block)
           @description = description
           @block = block
         end
@@ -20,6 +17,11 @@ module RSpec
           @block.call(actual)
         end
 
+        # @private
+        def description
+          @description ||= "satisfy #{block_representation}"
+        end
+
         # @api private
         # @return [String]
         def failure_message
@@ -31,6 +33,27 @@ module RSpec
         def failure_message_when_negated
           "expected #{actual_formatted} not to #{description}"
         end
+
+      private # rubocop:disable Lint/UselessAccessModifier
+
+        if RSpec::Support::RubyFeatures.ripper_supported?
+          def block_representation
+            if (block_snippet = extract_block_snippet)
+              "expression `#{block_snippet}`"
+            else
+              'block'
+            end
+          end
+
+          def extract_block_snippet
+            return nil unless @block
+            Expectations::BlockSnippetExtractor.try_extracting_single_line_body_of(@block, matcher_name)
+          end
+        else
+          def block_representation
+            'block'
+          end
+        end
       end
     end
   end

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

@@ -8,19 +8,17 @@ module RSpec
       # yield matchers is used. Provides information about
       # the yield behavior of the object-under-test.
       class YieldProbe
-        def self.probe(block)
-          probe = new(block)
+        def self.probe(block, &callback)
+          probe = new(block, &callback)
           return probe unless probe.has_block?
-          probe.assert_valid_expect_block!
-          block.call(probe)
-          probe.assert_used!
-          probe
+          probe.probe
         end
 
         attr_accessor :num_yields, :yielded_args
 
-        def initialize(block)
+        def initialize(block, &callback)
           @block = block
+          @callback = callback || Proc.new {}
           @used = false
           self.num_yields = 0
           self.yielded_args = []
@@ -30,13 +28,22 @@ module RSpec
           Proc === @block
         end
 
+        def probe
+          assert_valid_expect_block!
+          @block.call(self)
+          assert_used!
+          self
+        end
+
         def to_proc
           @used = true
 
           probe = self
+          callback = @callback
           Proc.new do |*args|
             probe.num_yields += 1
             probe.yielded_args << args
+            callback.call(*args)
             nil # to indicate the block does not return a meaningful value
           end
         end
@@ -56,12 +63,6 @@ module RSpec
           end
         end
 
-        def successive_yield_args
-          yielded_args.map do |arg_array|
-            arg_array.size == 1 ? arg_array.first : arg_array
-          end
-        end
-
         def assert_used!
           return if @used
           raise 'You must pass the argument yielded to your expect block on ' \
@@ -269,10 +270,15 @@ module RSpec
 
         # @private
         def matches?(block)
-          @probe = YieldProbe.probe(block)
+          @args_matched_when_yielded = true
+          @probe = YieldProbe.new(block) do
+            @actual = @probe.single_yield_args
+            @actual_formatted = actual_formatted
+            @args_matched_when_yielded &&= args_currently_match?
+          end
           return false unless @probe.has_block?
-          @actual = @probe.single_yield_args
-          @probe.yielded_once?(:yield_with_args) && args_match?
+          @probe.probe
+          @probe.yielded_once?(:yield_with_args) && @args_matched_when_yielded
         end
 
         # @private
@@ -317,16 +323,16 @@ module RSpec
         def negative_failure_reason
           if !@probe.has_block?
             'was not a block'
-          elsif all_args_match?
+          elsif @args_matched_when_yielded && !@expected.empty?
             'yielded with expected arguments' \
               "\nexpected not: #{surface_descriptions_in(@expected).inspect}" \
-              "\n         got: #{actual_formatted}"
+              "\n         got: #{@actual_formatted}"
           else
             'did'
           end
         end
 
-        def args_match?
+        def args_currently_match?
           if @expected.empty? # expect {...}.to yield_with_args
             @positive_args_failure = 'yielded with no arguments' if @actual.empty?
             return !@actual.empty?
@@ -335,7 +341,7 @@ module RSpec
           unless (match = all_args_match?)
             @positive_args_failure = 'yielded with unexpected arguments' \
               "\nexpected: #{surface_descriptions_in(@expected).inspect}" \
-              "\n     got: #{actual_formatted}"
+              "\n     got: #{@actual_formatted}"
           end
 
           match
@@ -356,10 +362,21 @@ module RSpec
 
         # @private
         def matches?(block)
-          @probe = YieldProbe.probe(block)
+          @actual_formatted = []
+          @actual = []
+          args_matched_when_yielded = true
+          yield_count = 0
+
+          @probe = YieldProbe.probe(block) do |*arg_array|
+            arg_or_args = arg_array.size == 1 ? arg_array.first : arg_array
+            @actual_formatted << RSpec::Support::ObjectFormatter.format(arg_or_args)
+            @actual << arg_or_args
+            args_matched_when_yielded &&= values_match?(@expected[yield_count], arg_or_args)
+            yield_count += 1
+          end
+
           return false unless @probe.has_block?
-          @actual = @probe.successive_yield_args
-          args_match?
+          args_matched_when_yielded && yield_count == @expected.length
         end
 
         def does_not_match?(block)
@@ -390,10 +407,6 @@ module RSpec
 
       private
 
-        def args_match?
-          values_match?(@expected, @actual)
-        end
-
         def expected_arg_description
           @expected.map { |e| description_of e }.join(', ')
         end
@@ -403,7 +416,7 @@ module RSpec
 
           'yielded with unexpected arguments' \
           "\nexpected: #{surface_descriptions_in(@expected).inspect}" \
-          "\n     got: #{actual_formatted}"
+          "\n     got: [#{@actual_formatted.join(", ")}]"
         end
 
         def negative_failure_reason
@@ -411,7 +424,7 @@ module RSpec
 
           'yielded with expected arguments' \
           "\nexpected not: #{surface_descriptions_in(@expected).inspect}" \
-          "\n         got: #{actual_formatted}"
+          "\n         got: [#{@actual_formatted.join(", ")}]"
         end
       end
     end

data/lib/rspec/matchers/dsl.rb

@@ -2,7 +2,70 @@ module RSpec
   module Matchers
     # Defines the custom matcher DSL.
     module 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.
+      #
+      # @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"
+      #
+      # @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.
+      # @see RSpec::Matchers
+      def 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)
+          matcher.matcher_name = new_name if matcher.respond_to?(:matcher_name=)
+          klass.new(matcher, description_override)
+        end
+      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.
+      #
+      # @example
+      #   RSpec::Matchers.define_negated_matcher :exclude, :include
+      #   include(1, 2).description # => "include 1 and 2"
+      #   exclude(1, 2).description # => "exclude 1 and 2"
+      #
+      # @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.
+      # @see RSpec::Matchers
+      def define_negated_matcher(negated_name, base_name, &description_override)
+        alias_matcher(negated_name, base_name, :klass => AliasedNegatedMatcher, &description_override)
+      end
+
       # Defines a custom matcher.
+      #
+      # @param name [Symbol] the name for the matcher
+      # @yield [Object] block that is used to define the matcher.
+      #   The block is evaluated in the context of your custom matcher class.
+      #   When args are passed to your matcher, they will be yielded here,
+      #   usually representing the expected value(s).
       # @see RSpec::Matchers
       def define(name, &declarations)
         warn_about_block_args(name, declarations)
@@ -266,7 +329,7 @@ module RSpec
         #
         # This compiles the user block into an actual method, allowing
         # them to use normal method constructs like `return`
-        # (e.g. for a early guard statement), while allowing us to define
+        # (e.g. for an early guard statement), while allowing us to define
         # an override that can provide the wrapped handling
         # (e.g. assigning `@actual`, rescueing errors, etc) and
         # can `super` to the user's definition.
@@ -462,5 +525,3 @@ module RSpec
     end
   end
 end
-
-RSpec::Matchers.extend RSpec::Matchers::DSL

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-expectations
 version: !ruby/object:Gem::Version
-  version: 3.6.0.beta2
+  version: 3.6.0
 platform: ruby
 authors:
 - Steven Baker
@@ -45,22 +45,22 @@ cert_chain:
   ZsVDj6a7lH3cNqtWXZxrb2wO38qV5AkYj8SQK7Hj3/Yui9myUX3crr+PdetazSqQ
   F3MdtaDehhjC
   -----END CERTIFICATE-----
-date: 2016-12-12 00:00:00.000000000 Z
+date: 2017-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-support
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.0.beta2
+        version: 3.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.6.0.beta2
+        version: 3.6.0
 - !ruby/object:Gem::Dependency
   name: diff-lcs
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +150,7 @@ files:
 - LICENSE.md
 - README.md
 - lib/rspec/expectations.rb
+- lib/rspec/expectations/block_snippet_extractor.rb
 - lib/rspec/expectations/configuration.rb
 - lib/rspec/expectations/expectation_target.rb
 - lib/rspec/expectations/fail_with.rb
@@ -212,14 +213,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.8.7
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5.2
 signing_key: 
 specification_version: 4
-summary: rspec-expectations-3.6.0.beta2
+summary: rspec-expectations-3.6.0
 test_files: []
 has_rdoc: