rspec-expectations 2.13.0 → 2.14.0.rc1

data/Changelog.md

@@ -1,3 +1,37 @@
+### 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`