rspec-expectations 3.1.2 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55fe7e69aa2f95c64cc33b1805bbd01569c0c269
-  data.tar.gz: 1315e9e9bb890c7088a2ba123fe0ad8af077f2a8
+  metadata.gz: a17c12beef7f8a1e2fa131987dbd3f487b9df046
+  data.tar.gz: 0854aa31f5d41a21d11f7cb33feccb38f19f76f6
 SHA512:
-  metadata.gz: 20496ddf5da00c886e02c27353860d953803fe33d76603955c8398758a8f86d05e3a3245e460fca389dd82ba012ee609f8d7b2cf92166b4568e17ab98f4d769e
-  data.tar.gz: 75767f0423ca2911f4161091aac4bc5b66e8b9deb01eb9490e00da0277ee036ab06be3d1f9f63930394fc46c426818227852f2f90a04c98288e7d69ca2ecad95
+  metadata.gz: 7952e648e91578f32c772b5f1d4679e06bbec42483a84b15c9e96828f4246a43f7e96a63d4bb7a50c0f809c6aa03a6df3a7439cc0815130518165b4e18cd2193
+  data.tar.gz: 50ca10401b8ead80b338c126b132381fd70df460c52a6d7df426f19020ac2fc5e423d7636456855099122be84df1e396a0a024e27849f8ac959becf7e82c29ba

data/Changelog.md

@@ -1,3 +1,48 @@
+### 3.2.0 / 2015-02-03
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.1.2...v3.2.0)
+
+Enhancements:
+
+* Add `block_arg` method to custom matcher API, which allows you to
+  access the block passed to a custom matcher, if there is one.
+  (Mike Dalton, #645)
+* Provide more detail in failure message of `yield_control` matcher.
+  (Jon Rowe, #650)
+* Add a shorthand syntax for `chain` in the matcher DSL which assigns values
+  for use elsewhere, for example `chain :and_smaller_than, :small_value`
+  creates an `attr_reader` for `small_value` (Tom Stuart, #644)
+* Provide a more helpful deprecation message when using the `should` syntax.
+  (Elia Schito, #663)
+* Provide more detail in the `have_attributes` matcher failure message.
+  (Jon Rowe,  #668)
+* Make the `have_attributes` matcher diffable.
+  (Jon Rowe, Alexey Fedorov, #668)
+* Add `output(...).to_std(out|err)_from_any_process` as alternatives
+  to `output(...).to_std(out|err)`. The latter doesn't work when a sub
+  process writes to the named stream but is much faster.
+  (Alex Genco, #700)
+* Improve compound matchers (created by `and` and `or`) so that diffs
+  are included in failures when one or more of their matchers
+  are diffable. (Alexey Fedorov, #713)
+
+Bug Fixes:
+
+* Avoid calling `private_methods` from the `be` predicate matcher on
+  the target object if the object publicly responds to the predicate
+  method. This avoids a possible error that can occur if the object
+  raises errors from `private_methods` (which can happen with celluloid
+  objects). (@chapmajs, #670)
+* Make `yield_control` (with no modifier) default to
+  `at_least(:once)` rather than raising a confusing error
+  when multiple yields are encountered.
+  (Myron Marston, #675)
+* Fix "instance variable @color not initialized" warning when using
+  rspec-expectations outside of an rspec-core context. (Myron Marston, #689)
+* Fix `start_with` and `end_with` to work properly when checking a
+  string against an array of strings. (Myron Marston, #690)
+* Don't use internally delegated matchers when generating descriptions
+  for examples without doc strings. (Myron Marston, #692)
+
 ### 3.1.2 / 2014-09-26
 [Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.1.1...v3.1.2)
 

data/README.md

@@ -1,4 +1,4 @@
-# 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.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.
@@ -13,6 +13,15 @@ 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 => "git://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:
 
@@ -52,6 +61,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.
@@ -93,11 +103,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

data/lib/rspec/expectations.rb

@@ -63,6 +63,7 @@ module RSpec
     # the user sets an expectation, it can't be caught in their
     # code by a bare `rescue`.
     # @api public
-    ExpectationNotMetError = Class.new(::Exception)
+    class ExpectationNotMetError < ::Exception
+    end
   end
 end

data/lib/rspec/expectations/configuration.rb

@@ -71,7 +71,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
 

data/lib/rspec/expectations/fail_with.rb

@@ -24,8 +24,7 @@ module RSpec
                                "appropriate failure_message[_when_negated] method to return a string?"
         end
 
-        diff = differ.diff(actual, expected)
-        message = "#{message}\nDiff:#{diff}" unless diff.empty?
+        message = ::RSpec::Matchers::ExpectedsForMultipleDiffs.from(expected).message_with_diff(message, differ, actual)
 
         raise RSpec::Expectations::ExpectationNotMetError, message
       end

data/lib/rspec/expectations/handler.rb

@@ -21,10 +21,13 @@ module RSpec
         LegacyMatcherAdapter::RSpec1.wrap(matcher) || matcher
       end
 
-      def self.setup(handler, matcher, message)
+      def self.with_matcher(handler, matcher, message)
         check_message(message)
+        matcher = modern_matcher_from(matcher)
+        yield matcher
+      ensure
         ::RSpec::Matchers.last_expectation_handler = handler
-        ::RSpec::Matchers.last_matcher = modern_matcher_from(matcher)
+        ::RSpec::Matchers.last_matcher = matcher
       end
 
       def self.handle_failure(matcher, message, failure_message_method)
@@ -42,10 +45,10 @@ module RSpec
     # @private
     class PositiveExpectationHandler
       def self.handle_matcher(actual, initial_matcher, message=nil, &block)
-        matcher = ExpectationHelper.setup(self, initial_matcher, message)
-
-        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
-        matcher.matches?(actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message)
+        ExpectationHelper.with_matcher(self, initial_matcher, message) do |matcher|
+          return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
+          matcher.matches?(actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message)
+        end
       end
 
       def self.verb
@@ -64,10 +67,10 @@ module RSpec
     # @private
     class NegativeExpectationHandler
       def self.handle_matcher(actual, initial_matcher, message=nil, &block)
-        matcher = ExpectationHelper.setup(self, initial_matcher, message)
-
-        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
-        !(does_not_match?(matcher, actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message_when_negated))
+        ExpectationHelper.with_matcher(self, initial_matcher, message) do |matcher|
+          return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
+          !(does_not_match?(matcher, actual, &block) || ExpectationHelper.handle_failure(matcher, message, :failure_message_when_negated))
+        end
       end
 
       def self.does_not_match?(matcher, actual, &block)

data/lib/rspec/expectations/minitest_integration.rb

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

data/lib/rspec/expectations/syntax.rb

@@ -27,7 +27,7 @@ module RSpec
 
         RSpec.deprecate(
           "Using `#{method_name}` from rspec-expectations' old `:should` syntax without explicitly enabling the syntax",
-          :replacement => "the new `:expect` syntax or explicitly enable `:should`"
+          :replacement => "the new `:expect` syntax or explicitly enable `:should` with `config.expect_with(:rspec) { |c| c.syntax = :should }`"
         )
 
         @warn_about_should = false

data/lib/rspec/expectations/version.rb

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

data/lib/rspec/matchers.rb

@@ -10,6 +10,7 @@ RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relat
   dsl
   matcher_delegator
   aliased_matcher
+  expecteds_for_multiple_diffs
 ].each { |file| RSpec::Support.require_rspec_matchers(file) }
 
 # RSpec's top level namespace. All of rspec-expectations is contained
@@ -220,19 +221,16 @@ module RSpec
     # @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
-    #   description. The yielded arg is the original description. If no block is
-    #   provided, a default description override is used based on the old and
-    #   new names.
+    # @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
@@ -261,16 +259,20 @@ module RSpec
     #
     # @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
-    #   description. The yielded arg is the original description. If no block is
-    #   provided, a default description override is used based on the old and
-    #   new names.
+    # @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"
     #
-    #   RSpec::Matchers.define_negated_matcher :a_value_not_between, :a_value_between
-    #   a_value_between(3, 5).description # => "a value between 3 and 5"
-    #   a_value_not_between(3, 5).description # => "a value not between 3 and 5"
+    # @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
@@ -329,7 +331,6 @@ module RSpec
     # Passes if actual.instance_of?(expected)
     #
     # @example
-    #
     #   expect(5).to     be_an_instance_of(Fixnum)
     #   expect(5).not_to be_an_instance_of(Numeric)
     #   expect(5).not_to be_an_instance_of(Float)
@@ -342,7 +343,6 @@ module RSpec
     # Passes if actual.kind_of?(expected)
     #
     # @example
-    #
     #   expect(5).to     be_a_kind_of(Fixnum)
     #   expect(5).to     be_a_kind_of(Numeric)
     #   expect(5).not_to be_a_kind_of(Float)
@@ -360,7 +360,6 @@ module RSpec
     # but you can make it `exclusive` by chaining that off the matcher.
     #
     # @example
-    #
     #   expect(5).to      be_between(1, 10)
     #   expect(11).not_to be_between(1, 10)
     #   expect(10).not_to be_between(1, 10).exclusive
@@ -372,7 +371,6 @@ module RSpec
     # Passes if actual == expected +/- delta
     #
     # @example
-    #
     #   expect(result).to     be_within(0.5).of(3.0)
     #   expect(result).not_to be_within(0.5).of(3.0)
     def be_within(delta)
@@ -407,7 +405,6 @@ module RSpec
     # * `by_at_most`
     #
     # @example
-    #
     #   expect {
     #     team.add_player(player)
     #   }.to change(roster, :count)
@@ -474,7 +471,6 @@ module RSpec
     #       but `=~` is not supported with `expect`.
     #
     # @example
-    #
     #   expect([1, 2, 3]).to contain_exactly(1, 2, 3)
     #   expect([1, 2, 3]).to contain_exactly(1, 3, 2)
     #
@@ -509,7 +505,6 @@ module RSpec
     # `expected.length` elements of the actual array.
     #
     # @example
-    #
     #   expect("this string").to   end_with "string"
     #   expect([0, 1, 2, 3, 4]).to end_with 4
     #   expect([0, 2, 3, 4, 4]).to end_with 3, 4
@@ -526,7 +521,6 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #
     #   expect(5).to     eq(5)
     #   expect(5).not_to eq(3)
     def eq(expected)
@@ -541,7 +535,6 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #
     #   expect(5).to     eql(5)
     #   expect(5).not_to eql(3)
     def eql(expected)
@@ -556,7 +549,6 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #
     #   expect(5).to       equal(5)   # Fixnums are equal
     #   expect("5").not_to equal("5") # Strings that look the same are not the same object
     def equal(expected)
@@ -579,7 +571,6 @@ module RSpec
     # This works no matter how you define your attribute readers.
     #
     # @example
-    #
     #   Person = Struct.new(:name, :age)
     #   person = Person.new("Bob", 32)
     #
@@ -589,7 +580,6 @@ module RSpec
     # @note It will fail if actual doesn't respond to any of the expected attributes.
     #
     # @example
-    #
     #   expect(person).to have_attributes(:color => "red")
     def have_attributes(expected)
       BuiltIn::HaveAttributes.new(expected)
@@ -601,13 +591,18 @@ module RSpec
     # and it will only pass if all args are found in collection.
     #
     # @example
-    #
     #   expect([1,2,3]).to      include(3)
     #   expect([1,2,3]).to      include(2,3)
     #   expect([1,2,3]).to      include(2,3,4) # fails
     #   expect([1,2,3]).not_to  include(4)
     #   expect("spread").to     include("read")
     #   expect("spread").not_to include("red")
+    #   expect(:a => 1, :b => 2).to include(:a)
+    #   expect(:a => 1, :b => 2).to include(:a, :b)
+    #   expect(:a => 1, :b => 2).to include(:a => 1)
+    #   expect(:a => 1, :b => 2).to include(:b => 2, :a => 1)
+    #   expect(:a => 1, :b => 2).to include(:c) # fails
+    #   expect(:a => 1, :b => 2).not_to include(:a => 2)
     def include(*expected)
       BuiltIn::Include.new(*expected)
     end
@@ -616,11 +611,10 @@ module RSpec
     alias_matcher :a_hash_including,       :include
     alias_matcher :including,              :include
 
-    # Passes if actual all expected objects pass. This works for
-    # any enumerable object.
+    # Passes if the provided matcher passes when checked against all
+    # elements of the collection.
     #
     # @example
-    #
     #   expect([1, 3, 5]).to all be_odd
     #   expect([1, 3, 6]).to all be_odd # fails
     #
@@ -642,12 +636,10 @@ module RSpec
     # pair of elements.
     #
     # @example
-    #
     #   expect(email).to match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
     #   expect(email).to match("@example.com")
     #
     # @example
-    #
     #   hash = {
     #     :a => {
     #       :b => ["foo", 5],
@@ -682,7 +674,6 @@ module RSpec
     # that splatted out as individual items.
     #
     # @example
-    #
     #   expect(results).to contain_exactly(1, 2)
     #   # is identical to:
     #   expect(results).to match_array([1, 2])
@@ -693,11 +684,14 @@ module RSpec
     end
 
     # With no arg, passes if the block outputs `to_stdout` or `to_stderr`.
-    # With a string, passes if the blocks outputs that specific string `to_stdout` or `to_stderr`.
-    # With a regexp or matcher, passes if the blocks outputs a string `to_stdout` or `to_stderr` that matches.
+    # With a string, passes if the block outputs that specific string `to_stdout` or `to_stderr`.
+    # With a regexp or matcher, passes if the block outputs a string `to_stdout` or `to_stderr` that matches.
     #
-    # @example
+    # To capture output from any spawned subprocess as well, use `to_stdout_from_any_process` or
+    # `to_stderr_from_any_process`. Output from any process that inherits the main process's corresponding
+    # standard stream will be captured.
     #
+    # @example
     #   expect { print 'foo' }.to output.to_stdout
     #   expect { print 'foo' }.to output('foo').to_stdout
     #   expect { print 'foo' }.to output(/foo/).to_stdout
@@ -710,10 +704,15 @@ module RSpec
     #
     #   expect { do_something }.to_not output.to_stderr
     #
-    # @note This matcher works by temporarily replacing `$stdout` or `$stderr`,
-    #   so it's not able to intercept stream output that explicitly uses `STDOUT`/`STDERR`
+    #   expect { system('echo foo') }.to output("foo\n").to_stdout_from_any_process
+    #   expect { system('echo foo', out: :err) }.to output("foo\n").to_stderr_from_any_process
+    #
+    # @note `to_stdout` and `to_stderr` work by temporarily replacing `$stdout` or `$stderr`,
+    #   so they're not able to intercept stream output that explicitly uses `STDOUT`/`STDERR`
     #   or that uses a reference to `$stdout`/`$stderr` that was stored before the
-    #   matcher is used.
+    #   matcher was used.
+    # @note `to_stdout_from_any_process` and `to_stderr_from_any_process` use Tempfiles, and
+    #   are thus significantly (~30x) slower than `to_stdout` and `to_stderr`.
     def output(expected=nil)
       BuiltIn::Output.new(expected)
     end
@@ -726,7 +725,6 @@ module RSpec
     # Pass an optional block to perform extra verifications on the exception matched
     #
     # @example
-    #
     #   expect { do_something_risky }.to raise_error
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError)
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError) { |error| expect(error.data).to eq 42 }
@@ -751,7 +749,6 @@ module RSpec
     # provided. Names can be Strings or Symbols.
     #
     # @example
-    #
     #   expect("string").to respond_to(:length)
     #
     def respond_to(*names)
@@ -771,7 +768,6 @@ module RSpec
     # a custom matcher, which would likely make your specs more expressive.
     #
     # @example
-    #
     #   expect(5).to satisfy { |n| n > 3 }
     def satisfy(&block)
       BuiltIn::Satisfy.new(&block)
@@ -785,7 +781,6 @@ module RSpec
     # `expected.length` elements of the actual array.
     #
     # @example
-    #
     #   expect("this string").to   start_with "this s"
     #   expect([0, 1, 2, 3, 4]).to start_with 0
     #   expect([0, 2, 3, 4, 4]).to start_with 0, 1
@@ -804,7 +799,6 @@ module RSpec
     # specified Symbol with the specified arg.
     #
     # @example
-    #
     #   expect { do_something_risky }.to throw_symbol
     #   expect { do_something_risky }.to throw_symbol(:that_was_risky)
     #   expect { do_something_risky }.to throw_symbol(:that_was_risky, 'culprit')
@@ -828,14 +822,11 @@ module RSpec
     # of whether or not arguments are yielded.
     #
     # @example
-    #
     #   expect { |b| 5.tap(&b) }.to yield_control
     #   expect { |b| "a".to_sym(&b) }.not_to yield_control
     #
     # @note Your expect block must accept a parameter and pass it on to
     #   the method-under-test as a block.
-    # @note This matcher is not designed for use with methods that yield
-    #   multiple times.
     def yield_control
       BuiltIn::YieldControl.new
     end
@@ -846,7 +837,6 @@ module RSpec
     # no arguments. Fails if it does not yield, or yields with arguments.
     #
     # @example
-    #
     #   expect { |b| User.transaction(&b) }.to yield_with_no_args
     #   expect { |b| 5.tap(&b) }.not_to yield_with_no_args # because it yields with `5`
     #   expect { |b| "a".to_sym(&b) }.not_to yield_with_no_args # because it does not yield
@@ -873,7 +863,6 @@ module RSpec
     # operator, the matcher will pass.
     #
     # @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
@@ -901,7 +890,6 @@ module RSpec
     # operator, the matcher will pass.
     #
     # @example
-    #
     #   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])
     #   expect { |b| [1, 2, 3].each(&b) }.not_to yield_successive_args(1, 2)