rspec-expectations 3.8.6

data/LICENSE.md

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+* Copyright © 2012 David Chelimsky, Myron Marston
+* Copyright © 2006 David Chelimsky, The RSpec Development Team
+* Copyright © 2005 Steven Baker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,305 @@
+# RSpec Expectations [![Build Status](https://secure.travis-ci.org/rspec/rspec-expectations.svg?branch=master)](http://travis-ci.org/rspec/rspec-expectations) [![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.
+
+```ruby
+expect(account.balance).to eq(Money.new(37.42, :USD))
+```
+
+## Install
+
+If you want to use rspec-expectations with rspec, just install the rspec gem
+and RubyGems will also install rspec-expectations for you (along with
+rspec-core and rspec-mocks):
+
+    gem install rspec
+
+Want to run against the `master` 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 => 'master'
+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:
+
+```ruby
+RSpec.describe Order do
+  it "sums the prices of the items in its line items" do
+    order = Order.new
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(1.11, :USD)
+    )))
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(2.22, :USD),
+      :quantity => 2
+    )))
+    expect(order.total).to eq(Money.new(5.55, :USD))
+  end
+end
+```
+
+The `describe` and `it` methods come from rspec-core.  The `Order`, `LineItem`, `Item` and `Money` classes would be from _your_ code. The last line of the example
+expresses an expected outcome. If `order.total == Money.new(5.55, :USD)`, then
+the example passes. If not, it fails with a message like:
+
+    expected: #<Money @value=5.55 @currency=:USD>
+         got: #<Money @value=1.11 @currency=:USD>
+
+## Built-in matchers
+
+### Equivalence
+
+```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.
+
+### Identity
+
+```ruby
+expect(actual).to be(expected)    # passes if actual.equal?(expected)
+expect(actual).to equal(expected) # passes if actual.equal?(expected)
+```
+
+### Comparisons
+
+```ruby
+expect(actual).to be >  expected
+expect(actual).to be >= expected
+expect(actual).to be <= expected
+expect(actual).to be <  expected
+expect(actual).to be_within(delta).of(expected)
+```
+
+### Regular expressions
+
+```ruby
+expect(actual).to match(/expression/)
+```
+
+Note: The new `expect` syntax no longer supports the `=~` matcher.
+
+### Types/classes
+
+```ruby
+expect(actual).to be_an_instance_of(expected) # passes if actual.class == 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
+```
+
+### 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_not be_nil  # passes if actual is not nil
+```
+
+### Expecting errors
+
+```ruby
+expect { ... }.to raise_error
+expect { ... }.to raise_error(ErrorClass)
+expect { ... }.to raise_error("message")
+expect { ... }.to raise_error(ErrorClass, "message")
+```
+
+### Expecting throws
+
+```ruby
+expect { ... }.to throw_symbol
+expect { ... }.to throw_symbol(:symbol)
+expect { ... }.to throw_symbol(:symbol, 'value')
+```
+
+### Yielding
+
+```ruby
+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(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)
+expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2])
+```
+
+### Predicate matchers
+
+```ruby
+expect(actual).to be_xxx         # passes if actual.xxx?
+expect(actual).to have_xxx(:arg) # passes if actual.has_xxx?(:arg)
+```
+
+### Ranges (Ruby >= 1.9 only)
+
+```ruby
+expect(1..10).to cover(3)
+```
+
+### Collection membership
+
+```ruby
+expect(actual).to include(expected)
+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)
+```
+
+#### 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])
+```
+
+## `should` syntax
+
+In addition to the `expect` syntax, rspec-expectations continues to support the
+`should` syntax:
+
+```ruby
+actual.should eq expected
+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)
+
+## Compound Matcher Expressions
+
+You can also create compound matcher expressions using `and` or `or`:
+
+``` ruby
+expect(alphabet).to start_with("a").and end_with("z")
+expect(stoplight.color).to eq("red").or eq("green").or eq("yellow")
+```
+
+## Composing Matchers
+
+Many of the built-in matchers are designed to take matchers as
+arguments, to allow you to flexibly specify only the essential
+aspects of an object or data structure. In addition, all of the
+built-in matchers have one or more aliases that provide better
+phrasing for when they are used as arguments to another matcher.
+
+### Examples
+
+```ruby
+expect { k += 1.05 }.to change { k }.by( a_value_within(0.1).of(1.0) )
+
+expect { s = "barn" }.to change { s }
+  .from( a_string_matching(/foo/) )
+  .to( a_string_matching(/bar/) )
+
+expect(["barn", 2.45]).to contain_exactly(
+  a_value_within(0.1).of(2.5),
+  a_string_starting_with("bar")
+)
+
+expect(["barn", "food", 2.45]).to end_with(
+  a_string_matching("foo"),
+  a_value > 2
+)
+
+expect(["barn", 2.45]).to include( a_string_starting_with("bar") )
+
+expect(:a => "food", :b => "good").to include(:a => a_string_matching(/foo/))
+
+hash = {
+  :a => {
+    :b => ["foo", 5],
+    :c => { :d => 2.05 }
+  }
+}
+
+expect(hash).to match(
+  :a => {
+    :b => a_collection_containing_exactly(
+      a_string_starting_with("f"),
+      an_instance_of(Integer)
+    ),
+    :c => { :d => (a_value < 3) }
+  }
+)
+
+expect { |probe|
+  [1, 2, 3].each(&probe)
+}.to yield_successive_args( a_value < 2, 2, a_value > 2 )
+```
+
+## Usage outside rspec-core
+
+You always need to load `rspec/expectations` even if you only want to use one part of the library:
+
+```ruby
+require 'rspec/expectations'
+```
+
+Then simply include `RSpec::Matchers` in any class:
+
+```ruby
+class MyClass
+  include RSpec::Matchers
+
+  def do_something(arg)
+    expect(arg).to be > 0
+    # do other stuff
+  end
+end
+```
+
+## Also see
+
+* [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.rb

@@ -0,0 +1,82 @@
+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'
+
+RSpec::Support.define_optimized_require_for_rspec(:expectations) { |f| require_relative(f) }
+
+%w[
+  expectation_target
+  configuration
+  fail_with
+  handler
+  version
+].each { |file| RSpec::Support.require_rspec_expectations(file) }
+
+module RSpec
+  # RSpec::Expectations provides a simple, readable API to express
+  # the expected outcomes in a code example. To express an expected
+  # outcome, wrap an object or block in `expect`, call `to` or `to_not`
+  # (aliased as `not_to`) and pass it a matcher object:
+  #
+  #     expect(order.total).to eq(Money.new(5.55, :USD))
+  #     expect(list).to include(user)
+  #     expect(message).not_to match(/foo/)
+  #     expect { do_something }.to raise_error
+  #
+  # The last form (the block form) is needed to match against ruby constructs
+  # that are not objects, but can only be observed when executing a block
+  # of code. This includes raising errors, throwing symbols, yielding,
+  # and changing values.
+  #
+  # When `expect(...).to` is invoked with a matcher, it turns around
+  # and calls `matcher.matches?(<object wrapped by expect>)`.  For example,
+  # in the expression:
+  #
+  #     expect(order.total).to eq(Money.new(5.55, :USD))
+  #
+  # ...`eq(Money.new(5.55, :USD))` returns a matcher object, and it results
+  # in the equivalent of `eq.matches?(order.total)`. If `matches?` returns
+  # `true`, the expectation is met and execution continues. If `false`, then
+  # the spec fails with the message returned by `eq.failure_message`.
+  #
+  # Given the expression:
+  #
+  #     expect(order.entries).not_to include(entry)
+  #
+  # ...the `not_to` method (also available as `to_not`) invokes the equivalent of
+  # `include.matches?(order.entries)`, but it interprets `false` as success, and
+  # `true` as a failure, using the message generated by
+  # `include.failure_message_when_negated`.
+  #
+  # rspec-expectations ships with a standard set of useful matchers, and writing
+  # your own matchers is quite simple.
+  #
+  # See [RSpec::Matchers](../RSpec/Matchers) for more information about the
+  # built-in matchers that ship with rspec-expectations, and how to write your
+  # own custom matchers.
+  module Expectations
+    # Exception raised when an expectation fails.
+    #
+    # @note We subclass Exception so that in a stub implementation if
+    # the user sets an expectation, it can't be caught in their
+    # code by a bare `rescue`.
+    # @api public
+    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 :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 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