rspec-expectations 3.0.4 → 3.12.3

data/README.md

@@ -1,9 +1,11 @@
-# RSpec Expectations [![Build Status](https://secure.travis-ci.org/rspec/rspec-expectations.png?branch=master)](http://travis-ci.org/rspec/rspec-expectations) [![Code Climate](https://codeclimate.com/github/rspec/rspec-expectations.png)](https://codeclimate.com/github/rspec/rspec-expectations)
+# RSpec Expectations [![Build Status](https://github.com/rspec/rspec-expectations/workflows/RSpec%20CI/badge.svg)](https://github.com/rspec/rspec-expectations/actions) [![Code Climate](https://codeclimate.com/github/rspec/rspec-expectations.svg)](https://codeclimate.com/github/rspec/rspec-expectations)
 
 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
 
@@ -13,11 +15,34 @@ rspec-core and rspec-mocks):
 
     gem install rspec
 
+Want to run against the `main` branch? You'll need to include the dependent
+RSpec repos as well. Add the following to your `Gemfile`:
+
+```ruby
+%w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
+  gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => 'main'
+end
+```
+
 If you want to use rspec-expectations with another tool, like Test::Unit,
 Minitest, or Cucumber, you can install it directly:
 
     gem install rspec-expectations
 
+## Contributing
+
+Once you've set up the environment, you'll need to cd into the working
+directory of whichever repo you want to work in. From there you can run the
+specs and cucumber features, and make patches.
+
+NOTE: You do not need to use rspec-dev to work on a specific RSpec repo. You
+can treat each RSpec repo as an independent project.
+
+- [Build details](BUILD_DETAIL.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Detailed contributing guide](CONTRIBUTING.md)
+- [Development setup guide](DEVELOPMENT.md)
+
 ## Basic usage
 
 Here's an example using rspec-core:
@@ -52,6 +77,7 @@ the example passes. If not, it fails with a message like:
 ```ruby
 expect(actual).to eq(expected)  # passes if actual == expected
 expect(actual).to eql(expected) # passes if actual.eql?(expected)
+expect(actual).not_to eql(not_expected) # passes if not(actual.eql?(expected))
 ```
 
 Note: The new `expect` syntax no longer supports the `==` matcher.
@@ -85,7 +111,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
 ```
@@ -93,11 +119,12 @@ expect(actual).to be_a_kind_of(expected)      # another alias
 ### Truthiness
 
 ```ruby
-expect(actual).to be_truthy # passes if actual is truthy (not nil or false)
-expect(actual).to be true   # passes if actual == true
-expect(actual).to be_falsy  # passes if actual is falsy (nil or false)
-expect(actual).to be false  # passes if actual == false
-expect(actual).to be_nil    # passes if actual is nil
+expect(actual).to be_truthy   # passes if actual is truthy (not nil or false)
+expect(actual).to be true     # passes if actual == true
+expect(actual).to be_falsy    # passes if actual is falsy (nil or false)
+expect(actual).to be false    # passes if actual == false
+expect(actual).to be_nil      # passes if actual is nil
+expect(actual).to_not be_nil  # passes if actual is not nil
 ```
 
 ### Expecting errors
@@ -125,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)
@@ -148,30 +175,45 @@ expect(1..10).to cover(3)
 ### Collection membership
 
 ```ruby
-expect(actual).to include(expected)
+# exact order, entire collection
+expect(actual).to eq(expected)
+
+# exact order, partial collection (based on an exact position)
 expect(actual).to start_with(expected)
 expect(actual).to end_with(expected)
 
-expect(actual).to contain_exactly(individual, items)
-# ...which is the same as:
-expect(actual).to match_array(expected_array)
+# any order, entire collection
+expect(actual).to match_array(expected)
+
+# You can also express this by passing the expected elements
+# as individual arguments
+expect(actual).to contain_exactly(expected_element1, expected_element2)
+
+ # any order, partial collection
+expect(actual).to include(expected)
 ```
 
 #### Examples
 
 ```ruby
-expect([1, 2, 3]).to include(1)
-expect([1, 2, 3]).to include(1, 2)
-expect([1, 2, 3]).to start_with(1)
-expect([1, 2, 3]).to start_with(1, 2)
-expect([1, 2, 3]).to end_with(3)
-expect([1, 2, 3]).to end_with(2, 3)
-expect({:a => 'b'}).to include(:a => 'b')
-expect("this string").to include("is str")
-expect("this string").to start_with("this")
-expect("this string").to end_with("ring")
-expect([1, 2, 3]).to contain_exactly(2, 3, 1)
-expect([1, 2, 3]).to match_array([3, 2, 1])
+expect([1, 2, 3]).to eq([1, 2, 3])            # Order dependent equality check
+expect([1, 2, 3]).to include(1)               # Exact ordering, partial collection matches
+expect([1, 2, 3]).to include(2, 3)            #
+expect([1, 2, 3]).to start_with(1)            # As above, but from the start of the collection
+expect([1, 2, 3]).to start_with(1, 2)         #
+expect([1, 2, 3]).to end_with(3)              # As above but from the end of the collection
+expect([1, 2, 3]).to end_with(2, 3)           #
+expect({:a => 'b'}).to include(:a => 'b')     # Matching within hashes
+expect("this string").to include("is str")    # Matching within strings
+expect("this string").to start_with("this")   #
+expect("this string").to end_with("ring")     #
+expect([1, 2, 3]).to contain_exactly(2, 3, 1) # Order independent matches
+expect([1, 2, 3]).to match_array([3, 2, 1])   #
+
+# Order dependent compound matchers
+expect(
+  [{:a => 'hash'},{:a => 'another'}]
+).to match([a_hash_including(:a => 'hash'), a_hash_including(:a => 'another')])
 ```
 
 ## `should` syntax
@@ -185,7 +227,7 @@ actual.should be > 3
 [1, 2, 3].should_not include 4
 ```
 
-See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/master/Should.md)
+See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/main/Should.md)
 
 ## Compound Matcher Expressions
 
@@ -238,7 +280,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) }
   }
@@ -272,7 +314,7 @@ end
 
 ## Also see
 
-* [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
-* [http://github.com/rspec/rspec-core](http://github.com/rspec/rspec-core)
-* [http://github.com/rspec/rspec-mocks](http://github.com/rspec/rspec-mocks)
-* [http://github.com/rspec/rspec-collection_matchers](https://github.com/rspec/rspec-collection_matchers)
+* [https://github.com/rspec/rspec](https://github.com/rspec/rspec)
+* [https://github.com/rspec/rspec-core](https://github.com/rspec/rspec-core)
+* [https://github.com/rspec/rspec-mocks](https://github.com/rspec/rspec-mocks)
+* [https://github.com/rspec/rspec-rails](https://github.com/rspec/rspec-rails)

data/lib/rspec/expectations/block_snippet_extractor.rb

@@ -0,0 +1,253 @@
+module RSpec
+  module Expectations
+    # @private
+    class BlockSnippetExtractor # rubocop:disable Metrics/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/configuration.rb

@@ -18,6 +18,19 @@ module RSpec
     #
     #   RSpec::Expectations.configuration
     class Configuration
+      # @private
+      FALSE_POSITIVE_BEHAVIOURS =
+        {
+          :warn    => lambda { |message| RSpec.warning message },
+          :raise   => lambda { |message| raise ArgumentError, message },
+          :nothing => lambda { |_| true },
+        }
+
+      def initialize
+        @on_potential_false_positives = :warn
+        @strict_predicate_matchers = false
+      end
+
       # Configures the supported syntax.
       # @param [Array<Symbol>, Symbol] values the syntaxes to enable
       # @example
@@ -44,6 +57,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
@@ -71,7 +98,7 @@ module RSpec
         # Delegates to rspec-core's color option if rspec-core
         # is loaded; otherwise you can set it here.
         def color?
-          @color
+          defined?(@color) && @color
         end
       end
 
@@ -107,6 +134,18 @@ module RSpec
                                  end
       end
 
+      # Sets if custom matcher descriptions and failure messages
+      # should include clauses from methods defined using `chain`.
+      # @param value [Boolean]
+      attr_writer :include_chain_clauses_in_custom_matcher_descriptions
+
+      # Indicates whether or not custom matcher descriptions and failure messages
+      # should include clauses from methods defined using `chain`. It is
+      # false by default for backwards compatibility.
+      def include_chain_clauses_in_custom_matcher_descriptions?
+        @include_chain_clauses_in_custom_matcher_descriptions ||= false
+      end
+
       # @private
       def reset_syntaxes_to_default
         self.syntax = [:should, :expect]
@@ -121,6 +160,62 @@ module RSpec
           backtrace
         end
       end
+
+      # Configures whether RSpec will warn about matcher use which will
+      # potentially cause false positives in tests.
+      #
+      # @param [Boolean] boolean
+      def warn_about_potential_false_positives=(boolean)
+        if boolean
+          self.on_potential_false_positives = :warn
+        elsif warn_about_potential_false_positives?
+          self.on_potential_false_positives = :nothing
+        else
+          # no-op, handler is something else
+        end
+      end
+      #
+      # Configures what RSpec will do about matcher use which will
+      # potentially cause false positives in tests.
+      #
+      # @param [Symbol] behavior can be set to :warn, :raise or :nothing
+      def on_potential_false_positives=(behavior)
+        unless FALSE_POSITIVE_BEHAVIOURS.key?(behavior)
+          raise ArgumentError, "Supported values are: #{FALSE_POSITIVE_BEHAVIOURS.keys}"
+        end
+        @on_potential_false_positives = behavior
+      end
+
+      # Configures RSpec to check predicate matchers to `be(true)` / `be(false)` (strict),
+      # or `be_truthy` / `be_falsey` (not strict).
+      # Historically, the default was `false`, but `true` is recommended.
+      def strict_predicate_matchers=(flag)
+        raise ArgumentError, "Pass `true` or `false`" unless flag == true || flag == false
+        @strict_predicate_matchers = flag
+      end
+
+      attr_reader :strict_predicate_matchers
+
+      def strict_predicate_matchers?
+        @strict_predicate_matchers
+      end
+
+      # Indicates what RSpec will do about matcher use which will
+      # potentially cause false positives in tests, generally you want to
+      # avoid such scenarios so this defaults to `true`.
+      attr_reader :on_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?
+        on_potential_false_positives == :warn
+      end
+
+      # @private
+      def false_positives_handler
+        FALSE_POSITIVE_BEHAVIOURS.fetch(@on_potential_false_positives)
+      end
     end
 
     # The configuration object.