rspec-expectations 2.13.0 → 2.14.0

data/Changelog.md

@@ -1,3 +1,49 @@
+### 2.14.0 / 2013-07-06
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.14.0.rc1...v2.14.0)
+
+Bug fixes
+
+* Values that are not matchers use `#inspect`, rather than `#description` for
+  documentation output (Andy Lindeman, Sam Phippen).
+* Make `expect(a).to be_within(x).percent_of(y)` work with negative y
+  (Katsuhiko Nishimra).
+* Make the `be_predicate` matcher work as expected used with `expect{...}.to
+  change...`  (Sam Phippen).
+
+### 2.14.0.rc1 / 2013-05-27
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.13.0...v2.14.0.rc1)
+
+Enhancements
+
+* Enhance `yield_control` so that you can specify an exact or relative
+  number of times: `expect { }.to yield_control.exactly(3).times`,
+  `expect { }.to yield_control.at_least(2).times`, etc (Bartek
+  Borkowski).
+* Make the differ that is used when an expectation fails better handle arrays
+  by splitting each element of the array onto its own line. (Sam Phippen)
+* Accept duck-typed strings that respond to `:to_str` as expectation messages.
+  (Toby Ovod-Everett)
+
+Bug fixes
+
+* Fix differ to not raise errors when dealing with differently-encoded
+  strings (Jon Rowe).
+* Fix `expect(something).to be_within(x).percent_of(y)` where x and y are both
+  integers (Sam Phippen).
+* Fix `have` matcher to handle the fact that on ruby 2.0,
+  `Enumerator#size` may return nil (Kenta Murata).
+* Fix `expect { raise s }.to raise_error(s)` where s is an error instance
+  on ruby 2.0 (Sam Phippen).
+* Fix `expect(object).to raise_error` passing. This now warns the user and
+  fails the spec (tomykaira).
+
+Deprecations
+
+* Deprecate `expect { }.not_to raise_error(SpecificErrorClass)` or
+  `expect { }.not_to raise_error("some specific message")`. Using
+  these was prone to hiding failures as they would allow _any other
+  error_ to pass. (Sam Phippen and David Chelimsky)
+
 ### 2.13.0 / 2013-02-23
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.12.1...v2.13.0)
 

data/README.md

@@ -3,7 +3,7 @@
 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
 
@@ -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,50 @@ 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 `==` 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 `=~` 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)
+expect(actual).to be_a_kind_of(expected)
 ```
 
 ### 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_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
 ```
 
 ### Expecting errors
@@ -134,92 +131,51 @@ 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)
 ```
 
 #### 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` syntax
-
-In addition to the `should` syntax, rspec-expectations supports
-a new `expect` syntax as of version 2.11.0:
-
-```ruby
-expect(actual).to eq expected
-expect(actual).to be > 3
-expect([1, 2, 3]).to_not include 4
-```
+## `should` syntax
 
-If you want your project to only use one of these syntaxes, you can
-configure it:
+In addition to the `expect` syntax, rspec-expectations continues to support the
+`should` syntax:
 
 ```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
+actual.should eq expected
+actual.should be > 3
+[1, 2, 3].should_not include 4
 ```
 
-See
-[RSpec::Expectations::Syntax#expect](http://rubydoc.info/gems/rspec-expectations/RSpec/Expectations/Syntax:expect)
-for more information.
-
-### Motivation for `expect`
-
-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).
-
-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.
-
-### One-liners
-
-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:
-
-```ruby
-describe User do
-  it { should validate_presence_of :email }
-end
-```
+See [detailed information on the `should` syntax and its usage.](https://github.com/rspec/rspec-expectations/blob/master/Should.md)
 
 ## Also see
 

data/features/README.md

@@ -2,7 +2,7 @@ rspec-expectations is used to define expected outcomes.
 
     describe Account do
       it "has a balance of zero when first created" do
-        Account.new.balance.should eq(Money.new(0))
+        expect(Account.new.balance).to eq(Money.new(0))
       end
     end
 
@@ -10,17 +10,16 @@ rspec-expectations is used to define expected outcomes.
 
 The basic structure of an rspec expectation is:
 
-    actual.should matcher(expected)
-    actual.should_not matcher(expected)
+    expect(actual).to matcher(expected)
+    expect(actual).not_to matcher(expected)
 
-## `should` and `should_not`
+Note: You can also use `expect(..).to_not` instead of `expect(..).not_to`.
+      One is an alias to the other, so you can use whichever reads better to you.
 
-`rspec-expectations` adds `should` and `should_not` to every object in
-the system. These methods each accept a matcher as an argument. This allows
-each matcher to work in a positive or negative mode:
+#### Examples
 
-    5.should eq(5)
-    5.should_not eq(4)
+    expect(5).to eq(5)
+    expect(5).not_to eq(4)
 
 ## What is a matcher?
 

data/features/built_in_matchers/README.md

@@ -1,55 +1,55 @@
 # Built-in Matchers
 
-Here is a list of matchers that ship with rspec-expectations. Each matcher
-can be used with `should` or `should_not` e.g.
+rspec-expectations ships with a number of built-in matchers.
+Each matcher can be used with `expect(..).to` or `expect(..).not_to` to define
+positive and negative expectations respectively on an object. Most matchers can
+also be accessed using the `(...).should` and `(...).should_not` syntax, see
+[using should syntax](https://github.com/rspec/rspec-expectations/blob/master/Should.md)
+for why we recommend using `expect`.
 
-    result.should eq(3)
-    list.should_not be_empty
+e.g.
+
+    expect(result).to   eq(3)
+    expect(list).not_to be_empty
+    pi.should be > 3
 
 ## Object identity
 
-    actual.should be(expected) # passes if actual.equal?(expected)
-    
+    expect(actual).to be(expected) # passes if actual.equal?(expected)
+
 ## Object equivalence
 
-    actual.should eq(expected) # passes if actual == expected
+    expect(actual).to eq(expected) # passes if actual == expected
 
 ## Optional APIs for identity/equivalence
 
-    actual.should == expected     # passes if actual == expected
-    actual.should eql(expected)   # passes if actual.eql?(expected)
-    actual.should equal(expected) # passes if actual.equal?(expected)
+    expect(actual).to eql(expected)   # passes if actual.eql?(expected)
+    expect(actual).to equal(expected) # passes if actual.equal?(expected)
 
-    # NOTE: this can't work in Ruby 1.8, so we don't support it at all:
-    #   actual.should != expected
-    # The reason is that Ruby 1.8 parses it as:
-    #   !(actual.should.==(expected)),
-    # so by the time RSpec sees it it has no way to know that it's
-    # been negated. Use either of these instead:
-    #   actual.should_not eq(expected)
-    #   actual.should_not == expected
+    # NOTE: `expect` does not support `==` matcher.
 
 ## Comparisons
 
-    actual.should be >  expected
-    actual.should be >= expected
-    actual.should be <= expected
-    actual.should be <  expected
-    actual.should =~ /expression/
-    actual.should match(/expression/)
-    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 match(/expression/)
+    expect(actual).to be_within(delta).of(expected)
+
+    # NOTE: `expect` does not support `=~` matcher.
 
 ## Types/classes
 
-    actual.should be_instance_of(expected)
-    actual.should be_kind_of(expected)
+    expect(actual).to be_instance_of(expected)
+    expect(actual).to be_kind_of(expected)
 
 ## Truthiness and existentialism
 
-    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
-    actual.should be       # passes if actual is truthy (not nil or false)
+    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)
 
 ## Expecting errors
 
@@ -66,25 +66,25 @@ can be used with `should` or `should_not` e.g.
 
 ## Predicate matchers
 
-    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)
 
 ### Examples
 
-    [].should be_empty # passes because [].empty? returns true
-    { :a => 1 }.should have_key(:a) # passes because the hash has the key :a
+    expect([]).to      be_empty
+    expect(:a => 1).to have_key(:a)
 
 ## Collection membership
 
-    actual.should include(expected)
+    expect(actual).to include(expected)
 
 ### Examples
 
-    [1,2,3].should include(1)
-    [1,2,3].should include(1, 2)
-    {:a => 'b'}.should include(:a => 'b')
-    "this string".should include("is str")
+    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")
 
 ## Ranges (1.9 only)
 
-    (1..10).should cover(3)
+    expect(1..10).to cover(3)

data/features/built_in_matchers/be_within.feature

@@ -4,11 +4,11 @@ Feature: be_within matcher
   Consider this irb session:
 
       > radius = 3
-        => 3 
+        => 3
       > area_of_circle = radius * radius * Math::PI
-        => 28.2743338823081 
+        => 28.2743338823081
       > area_of_circle == 28.2743338823081
-        => false 
+        => false
 
   Instead, you should use the be_within matcher to check that the value
   is within a delta of your expected value:

data/features/built_in_matchers/expect_change.feature

@@ -11,14 +11,14 @@ Feature: expect change
             @count ||= 0
             @count += 1
           end
-          
+
           def count
             @count ||= 0
           end
         end
       end
       """
-  
+
   Scenario: expect change
     Given a file named "spec/example_spec.rb" with:
       """ruby
@@ -45,13 +45,13 @@ Feature: expect change
       require "counter"
 
       describe Counter, "#increment" do
-        it "should not increment the count by 1 (using to_not)" do
-          expect { Counter.increment }.to_not change{Counter.count}
-        end
-
         it "should not increment the count by 1 (using not_to)" do
           expect { Counter.increment }.not_to change{Counter.count}
         end
+
+        it "should not increment the count by 1 (using to_not)" do
+          expect { Counter.increment }.to_not change{Counter.count}
+        end
       end
       """
     When I run `rspec spec/example_spec.rb`

data/features/built_in_matchers/expect_error.feature

@@ -124,7 +124,7 @@ Feature: raise_error matcher
       describe Object, "#public_instance_methods" do
         it "does not raise" do
           expect { Object.public_instance_methods }.
-            to_not raise_error(NameError)
+            not_to raise_error(NameError)
         end
       end
       """
@@ -136,7 +136,7 @@ Feature: raise_error matcher
       """
       describe "#to_s" do
         it "does not raise" do
-          expect { Object.new.to_s }.to_not raise_error
+          expect { Object.new.to_s }.not_to raise_error
         end
       end
       """

data/features/built_in_matchers/start_with.feature

@@ -1,6 +1,6 @@
 Feature: start_with matcher
 
-  Use the `start_with` matcher to specify that a string or array starts with 
+  Use the `start_with` matcher to specify that a string or array starts with
   the expected characters or elements.
 
     ```ruby

data/features/built_in_matchers/throw_symbol.feature

@@ -26,11 +26,11 @@ Feature: throw_symbol matcher
       describe "throw" do
         specify { expect { throw :foo    }.to     throw_symbol }
         specify { expect { throw :bar, 7 }.to     throw_symbol }
-        specify { expect { 5 + 5         }.to_not throw_symbol }
+        specify { expect { 5 + 5         }.not_to throw_symbol }
 
         # deliberate failures
-        specify { expect { throw :foo    }.to_not throw_symbol }
-        specify { expect { throw :bar, 7 }.to_not throw_symbol }
+        specify { expect { throw :foo    }.not_to throw_symbol }
+        specify { expect { throw :bar, 7 }.not_to throw_symbol }
         specify { expect { 5 + 5         }.to     throw_symbol }
       end
       """
@@ -47,12 +47,12 @@ Feature: throw_symbol matcher
       describe "throw symbol" do
         specify { expect { throw :foo    }.to     throw_symbol(:foo) }
         specify { expect { throw :foo, 7 }.to     throw_symbol(:foo) }
-        specify { expect { 5 + 5         }.to_not throw_symbol(:foo) }
-        specify { expect { throw :bar    }.to_not throw_symbol(:foo) }
+        specify { expect { 5 + 5         }.not_to throw_symbol(:foo) }
+        specify { expect { throw :bar    }.not_to throw_symbol(:foo) }
 
         # deliberate failures
-        specify { expect { throw :foo    }.to_not throw_symbol(:foo) }
-        specify { expect { throw :foo, 7 }.to_not throw_symbol(:foo) }
+        specify { expect { throw :foo    }.not_to throw_symbol(:foo) }
+        specify { expect { throw :foo, 7 }.not_to throw_symbol(:foo) }
         specify { expect { 5 + 5         }.to     throw_symbol(:foo) }
         specify { expect { throw :bar    }.to     throw_symbol(:foo) }
       end
@@ -70,12 +70,12 @@ Feature: throw_symbol matcher
       """ruby
       describe "throw symbol with argument" do
         specify { expect { throw :foo, 7 }.to     throw_symbol(:foo, 7) }
-        specify { expect { throw :foo, 8 }.to_not throw_symbol(:foo, 7) }
-        specify { expect { throw :bar, 7 }.to_not throw_symbol(:foo, 7) }
-        specify { expect { throw :foo    }.to_not throw_symbol(:foo, 7) }
+        specify { expect { throw :foo, 8 }.not_to throw_symbol(:foo, 7) }
+        specify { expect { throw :bar, 7 }.not_to throw_symbol(:foo, 7) }
+        specify { expect { throw :foo    }.not_to throw_symbol(:foo, 7) }
 
         # deliberate failures
-        specify { expect { throw :foo, 7 }.to_not throw_symbol(:foo, 7) }
+        specify { expect { throw :foo, 7 }.not_to throw_symbol(:foo, 7) }
         specify { expect { throw :foo, 8 }.to     throw_symbol(:foo, 7) }
         specify { expect { throw :bar, 7 }.to     throw_symbol(:foo, 7) }
         specify { expect { throw :foo    }.to     throw_symbol(:foo, 7) }

data/features/built_in_matchers/yield.feature

@@ -30,6 +30,10 @@ Feature: yield matchers
           yield *args
         end
 
+        def self.yield_twice_with(*args)
+          2.times { yield *args }
+        end
+
         def self.raw_yield
           yield
         end
@@ -47,17 +51,28 @@ Feature: yield matchers
       describe "yield_control matcher" do
         specify { expect { |b| MyClass.yield_once_with(1, &b) }.to yield_control }
         specify { expect { |b| MyClass.dont_yield(&b) }.not_to yield_control }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.to yield_control.twice }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.to yield_control.exactly(2).times }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.to yield_control.at_least(1) }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.to yield_control.at_most(3).times }
 
         # deliberate failures
         specify { expect { |b| MyClass.yield_once_with(1, &b) }.not_to yield_control }
         specify { expect { |b| MyClass.dont_yield(&b) }.to yield_control }
+        specify { expect { |b| MyClass.yield_once_with(1, &b) }.to yield_control.at_least(2).times }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.not_to yield_control.twice }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.not_to yield_control.at_least(2).times }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.not_to yield_control.at_least(1) }
+        specify { expect { |b| MyClass.yield_twice_with(1, &b) }.not_to yield_control.at_most(3).times }
       end
       """
     When I run `rspec yield_control_spec.rb`
     Then the output should contain all of these:
-      | 4 examples, 2 failures                      |
-      | expected given block to yield control       |
-      | expected given block not to yield control   |
+      | 13 examples, 7 failures                                   |
+      | expected given block to yield control                     |
+      | expected given block not to yield control                 |
+      | expected given block not to yield control at least twice  |
+      | expected given block not to yield control at most 3 times |
 
   Scenario: yield_with_args matcher
     Given a file named "yield_with_args_spec.rb" with:

data/features/custom_matchers/define_diffable_matcher.feature

@@ -12,7 +12,7 @@ Feature: define diffable matcher
         match do |actual|
           actual == expected
         end
-        
+
         diffable
       end
 

data/features/custom_matchers/define_matcher_outside_rspec.feature

@@ -9,19 +9,19 @@ Feature: define matcher outside rspec
       """ruby
       require "rspec/expectations"
       require "test/unit"
-      
+
       RSpec::Matchers.define :be_a_multiple_of do |expected|
         match do |actual|
           actual % expected == 0
         end
       end
-      
+
       class Test::Unit::TestCase
         include RSpec::Matchers
       end
-      
+
       class TestMultiples < Test::Unit::TestCase
-      
+
         def test_9_should_be_a_multiple_of_3
           9.should be_a_multiple_of(3)
         end
@@ -29,10 +29,10 @@ Feature: define matcher outside rspec
         def test_9_should_be_a_multiple_of_4
           9.should be_a_multiple_of(4)
         end
-        
+
       end
       """
     When I run `ruby test_multiples.rb`
-    Then the exit status should not be 0 
+    Then the exit status should not be 0
     And the output should contain "expected 9 to be a multiple of 4"
     And the output should contain "2 tests, 0 assertions, 0 failures, 1 errors"

data/features/custom_matchers/define_matcher_with_fluent_interface.feature

@@ -1,7 +1,7 @@
 Feature: define matcher with fluent interface
 
   Use the chain() method to define matchers with a fluent interface.
-  
+
   Scenario: chained method with argumetn
     Given a file named "between_spec.rb" with:
       """ruby

data/features/customized_message.feature

@@ -3,7 +3,7 @@ Feature: customized message
   RSpec tries to provide useful failure messages, but for cases in which you
   want more specific information, you can define your own message right in the
   example. This works for any matcher _other than the operator matchers_.
-  
+
   Scenario: customize failure message
     Given a file named "example_spec.rb" with:
       """ruby