rspec-expectations 3.0.0.beta1 → 3.0.0.beta2

data.tar.gz.sig

@@ -1,2 +1,2 @@
-x�-w��//�ԭ㽞��%s�6�F�+C1[͞*��������(
2K���8��*��r�%
Z׵��X�-d�ي�98l���{�:�4
-{���d3��ReDm���gb=�����/f�u����u�Wh��5�[��y������k��q�ѓ���CWAl�%t-S
+b��y�8W����O~����(���^WK� "ڴj�z\�fF�~���0"�6��KSV�v/�t��K�rz[x��(�����n�BA?L�.=R���O}l=D�8�.��dI��S���~��4�Y����A+�����8��`��H�W��Oh"k���D�_�
+_���{�0�]��e��Ƭj����*Pz@�d�o�cLt�t���C�;��F(J����6���<7�v�X�r�gmi��I�-�B0

data/.yardopts

@@ -1,3 +1,4 @@
+--load ./yard/alias_matcher.rb
 --exclude features
 --no-private
 --markup markdown

data/Changelog.md

@@ -1,3 +1,101 @@
+### 3.0.0.beta2 / 2014-02-17
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v3.0.0.beta1...v3.0.0.beta2)
+
+Breaking Changes for 3.0.0:
+
+* Remove deprecated support for accessing the `RSpec` constant using
+  `Rspec` or `Spec`. (Myron Marston)
+* Remove deprecated `RSpec::Expectations.differ=`. (Myron Marston)
+* Remove support for deprecated `expect(...).should`. (Myron Marston)
+* Explicitly disallow `expect { }.not_to change { }` with `by`,
+  `by_at_least`, `by_at_most` or `to`. These have never been supported
+  but did not raise explicit errors. (Myron Marston)
+* Provide `===` rather than `==` as an alias of `matches?` for
+  all matchers.  The semantics of `===` are closer to an RSpec
+  matcher than `==`. (Myron Marston)
+* Remove deprecated `RSpec::Matchers::OperatorMatcher` constant.
+  (Myron Marston)
+* Make `RSpec::Expectations::ExpectationNotMetError` subclass
+  `Exception` rather than `StandardError` so they can bypass
+  a bare `rescue` in end-user code (e.g. when an expectation is
+  set from within a rspec-mocks stub implementation). (Myron Marston)
+* Remove Test::Unit and Minitest 4.x integration. (Myron Marston)
+
+Enhancements:
+
+* Simplify the failure message of the `be` matcher when matching against:
+  `true`, `false` and `nil`. (Sam Phippen)
+* Update matcher protocol and custom matcher DSL to better align
+  with the newer `expect` syntax. If you want your matchers to
+  maintain compatibility with multiple versions of RSpec, you can
+  alias the new names to the old. (Myron Marston)
+    * `failure_message_for_should` => `failure_message`
+    * `failure_message_for_should_not` => `failure_message_when_negated`
+    * `match_for_should` => `match`
+    * `match_for_should_not` => `match_when_negated`
+* Improve generated descriptions from `change` matcher. (Myron Marston)
+* Add support for compound matcher expressions using `and` and `or`.
+  Simply chain them off of any existing matcher to create an expression
+  like `expect(alphabet).to start_with("a").and end_with("z")`.
+  (Eloy Espinaco)
+* Add `contain_exactly` as a less ambiguous version of `match_array`.
+  Note that it expects the expected array to be splatted as
+  individual args: `expect(array).to contain_exactly(1, 2)` is
+  the same as `expect(array).to match_array([1, 2])`. (Myron Marston)
+* Update `contain_exactly`/`match_array` so that it can match against
+  other non-array collections (such as a `Set`). (Myron Marston)
+* Update built-in matchers so that they can accept matchers as arguments
+  to allow you to compose matchers in arbitrary ways. (Myron Marston)
+* Add `RSpec::Matchers::Composable` mixin that can be used to make
+  a custom matcher composable as well. Note that custom matchers
+  defined via `RSpec::Matchers.define` already have this. (Myron
+  Marston)
+* Define noun-phrase aliases for built-in matchers, which can be
+  used when creating composed matcher expressions that read better
+  and provide better failure messages. (Myron Marston)
+* Add `RSpec::Machers.alias_matcher` so users can define their own
+  matcher aliases. The `description` of the matcher will reflect the
+  alternate matcher name. (Myron Marston)
+* Add explicit `be_between` matcher. `be_between` has worked for a
+  long time as a dynamic predicate matcher, but the failure message
+  was suboptimal. The new matcher provides a much better failure
+  message. (Erik Michaels-Ober)
+* Enhance the `be_between` matcher to allow for `inclusive` or `exclusive`
+  comparison (e.g. inclusive of min/max or exclusive of min/max).
+  (Pedro Gimenez)
+* Make failure message for `not_to be #{operator}` less confusing by
+  only saying it's confusing when comparison operators are used.
+  (Prathamesh Sonpatki)
+* Improve failure message of `eq` matcher when `Time` or `DateTime`
+  objects are used so that the full sub-second precision is included.
+  (Thomas Holmes, Jeff Wallace)
+* Add `output` matcher for expecting that a block outputs `to_stdout`
+  or `to_stderr`. (Luca Pette, Matthias Günther)
+* Forward a provided block on to the `has_xyz?` method call when
+  the `have_xyz` matcher is used. (Damian Galarza)
+* Provide integration with Minitest 5.x. Require
+  `rspec/expectations/minitest_integration` after loading minitest
+  to use rspec-expectations with minitest. (Myron Marston)
+
+Bug Fixes:
+
+* Fix wrong matcher descriptions with falsey expected value (yujinakayama)
+* Fix `expect { }.not_to change { }.from(x)` so that the matcher only
+  passes if the starting value is `x`. (Tyler Rick, Myron Marston)
+* Fix hash diffing, so that it colorizes properly and doesn't consider trailing
+  commas when performing the diff. (Jared Norman)
+* Fix built-in matchers to fail normally rather than raising
+  `ArgumentError` when given an object of the wrong type to match
+  against, so that they work well in composite matcher expressions like
+  `expect([1.51, "foo"]).to include(a_string_matching(/foo/), a_value_within(0.1).of(1.5))`.
+  (Myron Marston)
+
+Deprecations:
+
+* Retain support for RSpec 2 matcher protocol (e.g. for matchers
+  in 3rd party extension gems like `shoulda`), but it will print
+  a deprecation warning. (Myron Marston)
+
 ### 3.0.0.beta1 / 2013-11-07
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.99.0.beta1...v3.0.0.beta1)
 
@@ -6,6 +104,10 @@ Breaking Changes for 3.0.0:
 * Remove explicit support for 1.8.6. (Jon Rowe)
 * Remove the deprecated `be_close` matcher, preferring `be_within` instead.
   (Sam Phippen)
+* Remove the deprecated `have`, `have_at_least` and `have_at_most` matchers.
+  You can continue using those matchers through https://github.com/rspec/rspec-collection_matchers,
+  or you can rewrite your expectations with something like 
+  `expect(your_object.size).to eq(num)`. (Hugo Baraúna)
 * Rename `be_true` and `be_false` to `be_truthy` and `be_falsey`. (Sam Phippen)
 * Make `expect { }.to_not raise_error(SomeSpecificClass, message)`,
        `expect { }.to_not raise_error(SomeSpecificClass)` and
@@ -17,6 +119,7 @@ Breaking Changes for 3.0.0:
   available to the `match` block (or any of the others). Instead
   `include` your helper module and define the helper method as an
   instance method. (Myron Marston)
+* Force upgrading Diff::LCS for encoding compatbility with diffs. (Jon Rowe)
 
 Enhancements:
 
@@ -34,6 +137,7 @@ Bug Fixes:
 
 * Allow `include` and `match` matchers to be used from within a
   DSL-defined custom matcher's `match` block. (Myron Marston)
+* Correct encoding error message on diff failure (Jon Rowe)
 
 Deprecations:
 
@@ -41,6 +145,32 @@ Deprecations:
    It will continue to work but will emit a deprecation warning in RSpec 3 if
    you do not explicitly enable it. (Sam Phippen)
 
+### 2.99.0.beta2 / 2014-02-17
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.99.0.beta1...v2.99.0.beta2)
+
+Deprecations:
+
+* Deprecate chaining `by`, `by_at_least`, `by_at_most` or `to` off of
+  `expect { }.not_to change { }`. The docs have always said these are
+  not supported for the negative form but now they explicitly raise
+  errors in RSpec 3. (Myron Marston)
+* Change the semantics of `expect { }.not_to change { x }.from(y)`.
+  In RSpec 2.x, this expectation would only fail if `x` started with
+  the value of `y` and changed. If it started with a different value
+  and changed, it would pass. In RSpec 3, it will pass only if the
+  value starts at `y` and it does not change. (Myron Marston)
+* Deprecate `matcher == value` as an alias for `matcher.matches?(value)`,
+  in favor of `matcher === value`. (Myron Marston)
+* Deprecate `RSpec::Matchers::OperatorMatcher` in favor of
+  `RSpec::Matchers::BuiltIn::OperatorMatcher`. (Myron Marston)
+* Deprecate auto-integration with Test::Unit and minitest.
+  Instead, include `RSpec::Matchers` in the appropriate test case
+  base class yourself. (Myron Marston)
+* Deprecate treating `#expected` on a DSL-generated custom matcher
+  as an array when only 1 argument is passed to the matcher method.
+  In RSpec 3 it will be the single value in order to make diffs
+  work properly. (Jon Rowe)
+
 ### 2.99.0.beta1 / 2013-11-07
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.14.4...v2.99.0.beta1)
 
@@ -66,6 +196,14 @@ Deprecations
   * RSpec 2.x allowed helper methods defined either way to be used for
     either purpose, but RSpec 3.0 will not.
 
+### 2.14.5 / 2014-02-01
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.14.4...v2.14.5)
+
+Bug fixes
+
+* Fix wrong matcher descriptions with falsey expected value
+  (yujinakayama)
+
 ### 2.14.4 / 2013-11-06
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.14.3...v2.14.4)
 

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) [![Coverage Status](https://coveralls.io/repos/rspec/rspec-expectations/badge.png?branch=master)](https://coveralls.io/r/rspec/rspec-expectations?branch=master)
+# 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 lets you express expected outcomes on an object in an
 example.
@@ -71,7 +71,6 @@ expect(actual).to be >= expected
 expect(actual).to be <= expected
 expect(actual).to be <  expected
 expect(actual).to be_within(delta).of(expected)
-expect(array).to match_array(expected)
 ```
 
 ### Regular expressions
@@ -152,21 +151,27 @@ expect(1..10).to cover(3)
 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([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
@@ -182,6 +187,68 @@ actual.should be > 3
 
 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(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
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)

data/features/README.md

@@ -26,12 +26,12 @@ Note: You can also use `expect(..).to_not` instead of `expect(..).not_to`.
 A Matcher is any object that responds to the following methods:
 
     matches?(actual)
-    failure_message_for_should
+    failure_message
 
 These methods are also part of the matcher protocol, but are optional:
 
     does_not_match?(actual)
-    failure_message_for_should_not
+    failure_message_when_negated
     description
 
 RSpec ships with a number of built-in matchers and a DSL for writing custom

data/features/built_in_matchers/README.md

@@ -46,10 +46,11 @@ e.g.
 
 ## Truthiness and existentialism
 
-    expect(actual).to be_true  # passes if actual is truthy (not nil or false)
-    expect(actual).to be_false # passes if actual is falsy (nil or false)
-    expect(actual).to be_nil   # passes if actual is nil
-    expect(actual).to be       # passes if actual is truthy (not nil or false)
+    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_falsey # 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
 
@@ -77,16 +78,18 @@ e.g.
 ## Collection membership
 
     expect(actual).to include(expected)
-    expect(array).to match_array(expected)
+    expect(array).to match_array(expected_array)
+    # ...which is the same as:
+    expect(array).to contain_exactly(individual, elements)
 
 ### Examples
 
-    expect([1,2,3]).to       include(1)
-    expect([1,2,3]).to       include(1, 2)
+    expect([1, 2, 3]).to     include(1)
+    expect([1, 2, 3]).to     include(1, 2)
     expect(:a => 'b').to     include(:a => 'b')
     expect("this string").to include("is str")
-    expect([1,2,3]).to       match_array([1,2,3])
-    expect([1,2,3]).to       match_array([3,2,1])
+    expect([1, 2, 3]).to     contain_exactly(2, 1, 3)
+    expect([1, 2, 3]).to     match_array([3, 2, 1])
 
 ## Ranges (1.9 only)
 

data/features/built_in_matchers/comparisons.feature

@@ -1,7 +1,7 @@
-Feature: comparsion matchers
+Feature: comparison matchers
 
   RSpec provides a number of matchers that are based on Ruby's built-in
-  operators. These can be used for generalized comparsion of values. E.g.
+  operators. These can be used for generalized comparison of values. E.g.
 
     ```ruby
     expect(9).to be > 6

data/features/built_in_matchers/contain_exactly.feature

@@ -0,0 +1,46 @@
+Feature: contain_exactly matcher
+
+  The `contain_exactly` matcher provides a way to test arrays against each other
+  in a way that disregards differences in the ordering between the actual
+  and expected array. For example:
+
+    ```ruby
+    expect([1, 2, 3]).to    contain_exactly(2, 3, 1) # pass
+    expect([:a, :c, :b]).to contain_exactly(:a, :c ) # fail
+    ```
+
+  This matcher is also available as `match_array`, which expects the
+  expected array to be given as a single array argument rather than
+  as individual splatted elements. The above could also be written as:
+
+    ```ruby
+    expect([1, 2, 3]).to    match_array [2, 3, 1] # pass
+    expect([:a, :c, :b]).to match_array [:a, :c]  # fail
+    ```
+
+  Scenario: array operator matchers
+    Given a file named "contain_exactly_matcher_spec.rb" with:
+      """ruby
+      describe do
+        example { expect([1, 2, 3]).to contain_exactly(1, 2, 3) }
+        example { expect([1, 2, 3]).to contain_exactly(1, 3, 2) }
+        example { expect([1, 2, 3]).to contain_exactly(2, 1, 3) }
+        example { expect([1, 2, 3]).to contain_exactly(2, 3, 1) }
+        example { expect([1, 2, 3]).to contain_exactly(3, 1, 2) }
+        example { expect([1, 2, 3]).to contain_exactly(3, 2, 1) }
+
+        # deliberate failures
+        example { expect([1, 2, 3]).to contain_exactly(1, 2, 1) }
+      end
+      """
+     When I run `rspec contain_exactly_matcher_spec.rb`
+     Then the output should contain "7 examples, 1 failure"
+      And the output should contain:
+      """
+           Failure/Error: example { expect([1, 2, 3]).to contain_exactly(1, 2, 1) }
+             expected collection contained:  [1, 1, 2]
+             actual collection contained:    [1, 2, 3]
+             the missing elements were:      [1]
+             the extra elements were:        [3]
+      """
+

data/features/built_in_matchers/expect_change.feature

@@ -37,7 +37,7 @@ Feature: expect change
       """
     When I run `rspec spec/example_spec.rb`
     Then the output should contain "1 failure"
-    Then the output should contain "should have been changed by 2, but was changed by 1"
+    Then the output should contain "expected result to have changed by 2, but was changed by 1"
 
   Scenario: expect no change
     Given a file named "spec/example_spec.rb" with:
@@ -56,4 +56,4 @@ Feature: expect change
       """
     When I run `rspec spec/example_spec.rb`
     Then the output should contain "2 failures"
-    Then the output should contain "should not have changed, but did change from 1 to 2"
+    Then the output should contain "expected result not to have changed, but did change from 1 to 2"

data/features/built_in_matchers/include.feature

@@ -124,51 +124,3 @@ Feature: include matcher
     When I run `rspec hash_include_matcher_spec.rb`
     Then the output should contain "13 failure"
 
-  Scenario: fuzzy usage with matchers
-    Given a file named "fuzzy_include_matcher_spec.rb" with:
-      """
-      require 'ostruct'
-
-      class User < OpenStruct
-        def inspect
-          name
-        end
-      end
-
-      RSpec::Matchers.define :a_user_named do |expected|
-        match do |actual|
-          actual.is_a?(User) && (actual.name == expected)
-        end
-        description do
-          "a user named '#{expected}'"
-        end
-      end
-
-      describe "Collection of users" do
-        subject do
-          [User.new(:name => "Joe"),
-           User.new(:name => "Fred"),
-           User.new(:name => "John"),
-           User.new(:name => "Luke"),
-           User.new(:name => "David")]
-        end
-
-        it { should include( a_user_named "Joe" ) }
-        it { should include( a_user_named "Luke" ) }
-        it { should_not include( a_user_named "Richard" ) }
-        it { should_not include( a_user_named "Hayley" ) }
-
-        # deliberate failures
-        it { should include( a_user_named "Richard" ) }
-        it { should_not include( a_user_named "Fred" ) }
-        it { should include( a_user_named "Sarah" ) }
-        it { should_not include( a_user_named "Luke" ) }
-      end
-      """
-    When I run `rspec fuzzy_include_matcher_spec.rb`
-    Then the output should contain all of these:
-      | 8 examples, 4 failures                                                     |
-      | expected [Joe, Fred, John, Luke, David] to include a user named 'Richard'  |
-      | expected [Joe, Fred, John, Luke, David] not to include a user named 'Fred' |
-      | expected [Joe, Fred, John, Luke, David] to include a user named 'Sarah'    |
-      | expected [Joe, Fred, John, Luke, David] not to include a user named 'Luke' |