rspec-expectations 2.13.0 → 3.0.0

data/README.md

@@ -1,9 +1,9 @@
-# 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://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) [![Inline docs](http://inch-pages.github.io/github/rspec/rspec-expectations.png)](http://inch-pages.github.io/github/rspec/rspec-expectations)
 
 RSpec::Expectations lets you express expected outcomes on an object in an
 example.
 
-    account.balance.should eq(Money.new(37.42, :USD))
+    expect(account.balance).to eq(Money.new(37.42, :USD))
 
 ## Install
 
@@ -23,7 +23,7 @@ Minitest, or Cucumber, you can install it directly:
 Here's an example using rspec-core:
 
 ```ruby
-describe Order do
+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(
@@ -38,8 +38,7 @@ describe Order do
 end
 ```
 
-The `describe` and `it` methods come from rspec-core.  The `Order`, `LineItem`,
-and `Item` classes would be from _your_ code. The last line of the example
+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:
 
@@ -51,52 +50,54 @@ the example passes. If not, it fails with a message like:
 ### Equivalence
 
 ```ruby
-actual.should eq(expected)  # passes if actual == expected
-actual.should == expected   # passes if actual == expected
-actual.should eql(expected) # passes if actual.eql?(expected)
+expect(actual).to eq(expected)  # passes if actual == expected
+expect(actual).to eql(expected) # passes if actual.eql?(expected)
 ```
 
-Note: we recommend the `eq` matcher over `==` to avoid Ruby's "== in a
-useless context" warning when the `==` matcher is used anywhere but the
-last statement of an example.
+Note: The new `expect` syntax no longer supports the `==` matcher.
 
 ### Identity
 
 ```ruby
-actual.should be(expected)    # passes if actual.equal?(expected)
-actual.should equal(expected) # passes if actual.equal?(expected)
+expect(actual).to be(expected)    # passes if actual.equal?(expected)
+expect(actual).to equal(expected) # passes if actual.equal?(expected)
 ```
 
 ### Comparisons
 
 ```ruby
-actual.should be >  expected
-actual.should be >= expected
-actual.should be <= expected
-actual.should be <  expected
-actual.should be_within(delta).of(expected)
+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
-actual.should match(/expression/)
-actual.should =~ /expression/
+expect(actual).to match(/expression/)
 ```
 
+Note: The new `expect` syntax no longer supports the `=~` matcher.
+
 ### Types/classes
 
 ```ruby
-actual.should be_an_instance_of(expected)
-actual.should be_a_kind_of(expected)
+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_an(expected)             # an alias for be_a
+expect(actual).to be_a_kind_of(expected)      # another alias
 ```
 
 ### Truthiness
 
 ```ruby
-actual.should be_true  # passes if actual is truthy (not nil or false)
-actual.should be_false # passes if actual is falsy (nil or false)
-actual.should 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
 ```
 
 ### Expecting errors
@@ -134,91 +135,118 @@ expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [
 ### Predicate matchers
 
 ```ruby
-actual.should be_xxx         # passes if actual.xxx?
-actual.should have_xxx(:arg) # passes if actual.has_xxx?(:arg)
+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
-(1..10).should cover(3)
+expect(1..10).to cover(3)
 ```
 
 ### Collection membership
 
 ```ruby
-actual.should include(expected)
-actual.should start_with(expected)
-actual.should end_with(expected)
+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
-[1,2,3].should include(1)
-[1,2,3].should include(1, 2)
-[1,2,3].should start_with(1)
-[1,2,3].should start_with(1,2)
-[1,2,3].should end_with(3)
-[1,2,3].should end_with(2,3)
-{:a => 'b'}.should include(:a => 'b')
-"this string".should include("is str")
-"this string".should start_with("this")
-"this string".should end_with("ring")
+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` syntax
+## `should` syntax
 
-In addition to the `should` syntax, rspec-expectations supports
-a new `expect` syntax as of version 2.11.0:
+In addition to the `expect` syntax, rspec-expectations continues to support the
+`should` syntax:
 
 ```ruby
-expect(actual).to eq expected
-expect(actual).to be > 3
-expect([1, 2, 3]).to_not include 4
+actual.should eq expected
+actual.should be > 3
+[1, 2, 3].should_not include 4
 ```
 
-If you want your project to only use one of these syntaxes, you can
-configure it:
+See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/master/Should.md)
 
-```ruby
-RSpec.configure do |config|
-  config.expect_with :rspec do |c|
-    c.syntax = :expect
-    # or
-    c.syntax = :should
-    # or
-    c.syntax = [:should, :expect]
-  end
-end
-```
-
-See
-[RSpec::Expectations::Syntax#expect](http://rubydoc.info/gems/rspec-expectations/RSpec/Expectations/Syntax:expect)
-for more information.
+## Compound Matcher Expressions
 
-### Motivation for `expect`
+You can also create compound matcher expressions using `and` or `or`:
 
-We added the `expect` syntax to resolve some edge case issues, most notably
-that objects whose definitions wipe out all but a few methods were throwing
-`should` and `should_not` away. `expect` solves that by not monkey patching
-those methods onto `Kernel` (or any global object).
+``` ruby
+expect(alphabet).to start_with("a").and end_with("z")
+expect(stoplight.color).to eq("red").or eq("green").or eq("yellow")
+```
 
-See
-[http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax](http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax)
-for a detailed explanation.
+## Composing Matchers
 
-### One-liners
+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.
 
-The one-liner syntax supported by
-[rspec-core](http://rubydoc.info/gems/rspec-core)  uses `should` even when
-`config.syntax = :expect`. It reads better than the alternative, and does not
-require a global monkey patch:
+### Examples
 
 ```ruby
-describe User do
-  it { should validate_presence_of :email }
-end
+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(Fixnum)
+    ),
+    :c => { :d => (a_value < 3) }
+  }
+)
+
+expect { |probe|
+  [1, 2, 3].each(&probe)
+}.to yield_successive_args( a_value < 2, 2, a_value > 2 )
 ```
 
 ## Also see
@@ -226,3 +254,4 @@ end
 * [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)

data/lib/rspec/{matchers → expectations}/configuration.rb

@@ -1,8 +1,22 @@
-require 'rspec/expectations/syntax'
+RSpec::Support.require_rspec_expectations "syntax"
 
 module RSpec
-  module Matchers
+  module Expectations
     # Provides configuration options for rspec-expectations.
+    # If you are using rspec-core, you can access this via a
+    # block passed to `RSpec::Core::Configuration#expect_with`.
+    # Otherwise, you can access it via RSpec::Expectations.configuration.
+    #
+    # @example
+    #   RSpec.configure do |rspec|
+    #     rspec.expect_with :rspec do |c|
+    #       # c is the config object
+    #     end
+    #   end
+    #
+    #   # or
+    #
+    #   RSpec::Expectations.configuration
     class Configuration
       # Configures the supported syntax.
       # @param [Array<Symbol>, Symbol] values the syntaxes to enable
@@ -32,6 +46,10 @@ module RSpec
 
       # The list of configured syntaxes.
       # @return [Array<Symbol>] the list of configured syntaxes.
+      # @example
+      #   unless RSpec::Matchers.configuration.syntax.include?(:expect)
+      #     raise "this RSpec extension gem requires the rspec-expectations `:expect` syntax"
+      #   end
       def syntax
         syntaxes = []
         syntaxes << :should if Expectations::Syntax.should_enabled?
@@ -39,14 +57,21 @@ module RSpec
         syntaxes
       end
 
-      # color config for expectations
-      # fallback if rspec core not available
       if ::RSpec.respond_to?(:configuration)
         def color?
           ::RSpec.configuration.color_enabled?
         end
       else
-        attr_writer :color
+        # Indicates whether or not diffs should be colored.
+        # Delegates to rspec-core's color option if rspec-core
+        # is loaded; otherwise you can set it here.
+        def color=(value)
+          @color = value
+        end
+
+        # Indicates whether or not diffs should be colored.
+        # Delegates to rspec-core's color option if rspec-core
+        # is loaded; otherwise you can set it here.
         def color?
           @color
         end
@@ -74,20 +99,25 @@ module RSpec
       # will be used (including respecting the presence or absence of
       # the `--backtrace` option).
       #
-      # @overload backtrace_formatter
-      #   @return [#format_backtrace] the backtrace formatter
-      # @overload backtrace_formatter=
-      #   @param value [#format_backtrace] sets the backtrace formatter
+      # @!attribute [rw] backtrace_formatter
       attr_writer :backtrace_formatter
       def backtrace_formatter
-        @backtrace_formatter ||= if defined?(::RSpec::Core::BacktraceFormatter)
-          ::RSpec::Core::BacktraceFormatter
+        @backtrace_formatter ||= if defined?(::RSpec.configuration.backtrace_formatter)
+         ::RSpec.configuration.backtrace_formatter
         else
           NullBacktraceFormatter
         end
       end
 
+      # @private
+      def reset_syntaxes_to_default
+        self.syntax = [:should, :expect]
+        RSpec::Expectations::Syntax.warn_about_should!
+      end
+
       # @api private
+      # Null implementation of a backtrace formatter used by default
+      # when rspec-core is not loaded. Does no filtering.
       NullBacktraceFormatter = Module.new do
         def self.format_backtrace(backtrace)
           backtrace
@@ -95,14 +125,14 @@ module RSpec
       end
     end
 
-    # The configuration object
-    # @return [RSpec::Matchers::Configuration] the configuration object
+    # The configuration object.
+    # @return [RSpec::Expectations::Configuration] the configuration object
     def self.configuration
       @configuration ||= Configuration.new
     end
 
     # set default syntax
-    configuration.syntax = [:expect, :should]
+    configuration.reset_syntaxes_to_default
   end
 end
 

data/lib/rspec/expectations/expectation_target.rb

@@ -1,23 +1,43 @@
 module RSpec
   module Expectations
     # Wraps the target of an expectation.
+    #
     # @example
-    #   expect(something) # => ExpectationTarget wrapping something
+    #   expect(something)       # => ExpectationTarget wrapping something
+    #   expect { do_something } # => ExpectationTarget wrapping the block
     #
     #   # used with `to`
     #   expect(actual).to eq(3)
     #
-    #   # with `to_not`
-    #   expect(actual).to_not eq(3)
+    #   # with `not_to`
+    #   expect(actual).not_to eq(3)
+    #
+    # @note `ExpectationTarget` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
     class ExpectationTarget
-      class << self
-        attr_accessor :deprecated_should_enabled
-        alias deprecated_should_enabled? deprecated_should_enabled
-      end
+      # @private
+      # Used as a sentinel value to be able to tell when the user
+      # did not pass an argument. We can't use `nil` for that because
+      # `nil` is a valid value to pass.
+      UndefinedValue = Module.new
 
       # @api private
-      def initialize(target)
-        @target = target
+      def initialize(value)
+        @target = value
+      end
+
+      # @private
+      def self.for(value, block)
+        if UndefinedValue.equal?(value)
+          unless block
+            raise ArgumentError, "You must pass either an argument or a block to `expect`."
+          end
+          BlockExpectationTarget.new(block)
+        elsif block
+          raise ArgumentError, "You cannot pass both an argument and a block to `expect`."
+        else
+          new(value)
+        end
       end
 
       # Runs the given expectation, passing if `matcher` returns true.
@@ -26,61 +46,74 @@ module RSpec
       #   expect { perform }.to raise_error
       # @param [Matcher]
       #   matcher
-      # @param [String] message optional message to display when the expectation fails
+      # @param [String or Proc] message optional message to display when the expectation fails
       # @return [Boolean] true if the expectation succeeds (else raises)
       # @see RSpec::Matchers
       def to(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:to, matcher)
+        prevent_operator_matchers(:to) unless matcher
         RSpec::Expectations::PositiveExpectationHandler.handle_matcher(@target, matcher, message, &block)
       end
 
       # Runs the given expectation, passing if `matcher` returns false.
       # @example
-      #   expect(value).to_not eq(5)
       #   expect(value).not_to eq(5)
       # @param [Matcher]
       #   matcher
-      # @param [String] message optional message to display when the expectation fails
+      # @param [String or Proc] message optional message to display when the expectation fails
       # @return [Boolean] false if the negative expectation succeeds (else raises)
       # @see RSpec::Matchers
-      def to_not(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:to_not, matcher)
+      def not_to(matcher=nil, message=nil, &block)
+        prevent_operator_matchers(:not_to) unless matcher
         RSpec::Expectations::NegativeExpectationHandler.handle_matcher(@target, matcher, message, &block)
       end
-      alias not_to to_not
+      alias to_not not_to
 
-      def self.enable_deprecated_should
-        return if deprecated_should_enabled?
+    private
 
-        def should(*args)
-          RSpec.deprecate "`expect { }.should`", "`expect { }.to`", 3
-          @target.should(*args)
-        end
+      def prevent_operator_matchers(verb)
+        raise ArgumentError, "The expect syntax does not support operator matchers, " +
+                             "so you must pass a matcher to `##{verb}`."
+      end
+    end
 
-        def should_not(*args)
-          RSpec.deprecate "`expect { }.should_not`", "`expect { }.to_not`", 3
-          @target.should_not(*args)
-        end
+    # @private
+    # Validates the provided matcher to ensure it supports block
+    # expectations, in order to avoid user confusion when they
+    # use a block thinking the expectation will be on the return
+    # value of the block rather than the block itself.
+    class BlockExpectationTarget < ExpectationTarget
+      def to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
 
-        self.deprecated_should_enabled = true
+      def not_to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
       end
+      alias to_not not_to
 
-      def self.disable_deprecated_should
-        return unless deprecated_should_enabled?
+    private
 
-        remove_method :should
-        remove_method :should_not
+      def enforce_block_expectation(matcher)
+        return if supports_block_expectations?(matcher)
 
-        self.deprecated_should_enabled = false
+        raise ExpectationNotMetError,
+          "You must pass an argument rather than a block to use the provided " +
+          "matcher (#{description_of matcher}), or the matcher must implement " +
+          "`supports_block_expectations?`."
       end
 
-    private
-
-      def prevent_operator_matchers(verb, matcher)
-        return if matcher
+      def supports_block_expectations?(matcher)
+        matcher.supports_block_expectations?
+      rescue NoMethodError
+        false
+      end
 
-        raise ArgumentError, "The expect syntax does not support operator matchers, " +
-                             "so you must pass a matcher to `##{verb}`."
+      def description_of(matcher)
+        matcher.description
+      rescue NoMethodError
+        matcher.inspect
       end
     end
   end

data/lib/rspec/expectations/fail_with.rb

@@ -1,9 +1,14 @@
+RSpec::Support.require_rspec_support 'differ'
+
 module RSpec
   module Expectations
     class << self
       # @private
       def differ
-        @differ ||= Differ.new
+        RSpec::Support::Differ.new(
+          :object_preparer => lambda {|object| RSpec::Matchers::Composable.surface_descriptions_in(object) },
+          :color => RSpec::Matchers.configuration.color?
+        )
       end
 
       # Raises an RSpec::Expectations::ExpectationNotMetError with message.
@@ -16,53 +21,16 @@ module RSpec
       def fail_with(message, expected=nil, actual=nil)
         if !message
           raise ArgumentError, "Failure message is nil. Does your matcher define the " +
-                               "appropriate failure_message_for_* method to return a string?"
-        end
-
-        if actual && expected
-          if all_strings?(actual, expected)
-            if any_multiline_strings?(actual, expected)
-              message << "\nDiff:" << differ.diff_as_string(coerce_to_string(actual), coerce_to_string(expected))
-            end
-          elsif no_procs?(actual, expected) && no_numbers?(actual, expected)
-            message << "\nDiff:" << differ.diff_as_object(actual, expected)
-          end
+                               "appropriate failure_message[_when_negated] method to return a string?"
         end
 
-        raise(RSpec::Expectations::ExpectationNotMetError.new(message))
-      end
-
-    private
-
-      def no_procs?(*args)
-        args.flatten.none? {|a| Proc === a}
-      end
-
-      def all_strings?(*args)
-        args.flatten.all? {|a| String === a}
-      end
+        diff = differ.diff(actual, expected)
 
-      def any_multiline_strings?(*args)
-        all_strings?(*args) && args.flatten.any? { |a| multiline?(a) }
-      end
-
-      def no_numbers?(*args)
-        args.flatten.none? {|a| Numeric === a}
-      end
-
-      def coerce_to_string(string_or_array)
-        return string_or_array unless Array === string_or_array
-        string_or_array.join(',')
-      end
-
-      if String.method_defined?(:encoding)
-        def multiline?(string)
-          string.include?("\n".encode(string.encoding))
-        end
-      else
-        def multiline?(string)
-          string.include?("\n")
+        unless diff.empty?
+          message = "#{message}\nDiff:#{diff}"
         end
+
+        raise RSpec::Expectations::ExpectationNotMetError.new(message)
       end
     end
   end