Browse files

Merge pull request #221 from gautamkpai/update_readme

Update README to use expect syntax.
  • Loading branch information...
2 parents a68dfdc + 9e03395 commit 32740b56ca5cbfab10836f2bb26828b8f476f38a @myronmarston myronmarston committed Mar 14, 2013
Showing with 58 additions and 56 deletions.
  1. +58 −56 README.md
View
114 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
@@ -51,52 +51,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,61 +132,75 @@ 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
+## `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
```
+### 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.
+
+
+### Using either `expect` or `should` or both
+
If you want your project to only use one of these syntaxes, you can
configure it:
```ruby
RSpec.configure do |config|
config.expect_with :rspec do |c|
- c.syntax = :expect
+ c.syntax = :expect # disables `should`
# or
- c.syntax = :should
+ c.syntax = :should # disables `expect`
# or
- c.syntax = [:should, :expect]
+ c.syntax = [:should, :expect] # enables both `should` and `expect`
end
end
```
@@ -197,16 +209,6 @@ 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

0 comments on commit 32740b5

Please sign in to comment.