Skip to content
Newer
Older
100644 171 lines (126 sloc) 4.11 KB
d5a1da7 @spicycode Initial jeweler repository creation
spicycode authored
1 # RSpec Expectations
2
17325de @dchelimsky Remove relative links from README, since they can't work correctly on
dchelimsky authored
3 RSpec::Expectations lets you express expected outcomes on an object in an
4 example.
3feb655 @dchelimsky rdoc
dchelimsky authored
5
6 account.balance.should eq(Money.new(37.42, :USD))
b8e248b @dchelimsky links to docs
dchelimsky authored
7
8 ## Install
9
3feb655 @dchelimsky rdoc
dchelimsky authored
10 If you want to use rspec-expectations with rspec, just install the rspec gem
11 and RubyGems will also install rspec-expectations for you (along with
12 rspec-core and rspec-mocks):
13
14 gem install rspec
15
16 If you want to use rspec-expectations with another tool, like Test::Unit,
17 Minitest, or Cucumber, you can install it directly:
18
19 gem install rspec-expectations
20
21 ## Basic usage
22
23 Here's an example using rspec-core:
24
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
25 ```ruby
26 describe Order do
27 it "sums the prices of the items in its line items" do
28 order = Order.new
29 order.add_entry(LineItem.new(:item => Item.new(
30 :price => Money.new(1.11, :USD)
31 )))
32 order.add_entry(LineItem.new(:item => Item.new(
33 :price => Money.new(2.22, :USD),
34 :quantity => 2
35 )))
36 order.total.should eq(Money.new(5.55, :USD))
37 end
38 end
39 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
40
41 The `describe` and `it` methods come from rspec-core. The `Order`, `LineItem`,
42 and `Item` classes would be from _your_ code. The last line of the example
43 expresses an expected outcome. If `order.total == Money.new(5.55, :USD)`, then
44 the example passes. If not, it fails with a message like:
45
46 expected: #<Money @value=5.55 @currency=:USD>
47 got: #<Money @value=1.11 @currency=:USD>
48
49 ## Built-in matchers
50
51 ### Equivalence
52
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
53 ```ruby
54 actual.should eq(expected) # passes if actual == expected
55 actual.should == expected # passes if actual == expected
56 actual.should eql(expected) # passes if actual.eql?(expected)
57 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
58
59 ### Identity
60
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
61 ```ruby
62 actual.should be(expected) # passes if actual.equal?(expected)
63 actual.should equal(expected) # passes if actual.equal?(expected)
64 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
65
66 ### Comparisons
67
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
68 ```ruby
69 actual.should be > expected
70 actual.should be >= expected
71 actual.should be <= expected
72 actual.should be < expected
73 actual.should be_within(delta).of(expected)
74 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
75
76 ### Regular expressions
77
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
78 ```ruby
79 actual.should =~ /expression/
80 actual.should match(/expression/)
81 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
82
83 ### Types/classes
84
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
85 ```ruby
86 actual.should be_an_instance_of(expected)
87 actual.should be_a_kind_of(expected)
88 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
89
90 ### Truthiness
91
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
92 ```ruby
93 actual.should be_true # passes if actual is truthy (not nil or false)
94 actual.should be_false # passes if actual is falsy (nil or false)
95 actual.should be_nil # passes if actual is nil
96 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
97
98 ### Expecting errors
99
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
100 ```ruby
101 expect { ... }.to raise_error
102 expect { ... }.to raise_error(ErrorClass)
103 expect { ... }.to raise_error("message")
104 expect { ... }.to raise_error(ErrorClass, "message")
105 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
106
107 ### Expecting throws
108
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
109 ```ruby
110 expect { ... }.to throw_symbol
111 expect { ... }.to throw_symbol(:symbol)
112 expect { ... }.to throw_symbol(:symbol, 'value')
113 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
114
b94da8d @myronmarston Add API docs for yield matchers.
myronmarston authored
115 ### Yielding
116
117 ```ruby
118 expect { |b| 5.tap(&b) }.to yield_control # passes regardless of yielded args
119
120 expect { |b| yield_if_true(true, &b) }.to yield_with_no_args # passes only if no args are yielded
121
122 expect { |b| 5.tap(&b) }.to yield_with_args(5)
123 expect { |b| 5.tap(&b) }.to yield_with_args(Fixnum)
124 expect { |b| "a string".tap(&b) }.to yield_with_args(/str/)
125
126 expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
127 expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2])
128 ```
129
3feb655 @dchelimsky rdoc
dchelimsky authored
130 ### Predicate matchers
131
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
132 ```ruby
133 actual.should be_xxx # passes if actual.xxx?
134 actual.should have_xxx(:arg) # passes if actual.has_xxx?(:arg)
135 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
136
137 ### Ranges (Ruby >= 1.9 only)
138
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
139 ```ruby
140 (1..10).should cover(3)
141 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
142
143 ### Collection membership
144
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
145 ```ruby
146 actual.should include(expected)
35d98aa @dchelimsky add start_with and end_with matchers to README [ci skip]
dchelimsky authored
147 actual.should start_with(expected)
148 actual.should end_with(expected)
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
149 ```
3feb655 @dchelimsky rdoc
dchelimsky authored
150
151 #### Examples
b8e248b @dchelimsky links to docs
dchelimsky authored
152
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
153 ```ruby
154 [1,2,3].should include(1)
155 [1,2,3].should include(1, 2)
35d98aa @dchelimsky add start_with and end_with matchers to README [ci skip]
dchelimsky authored
156 [1,2,3].should start_with(1)
157 [1,2,3].should start_with(1,2)
158 [1,2,3].should end_with(3)
159 [1,2,3].should end_with(2,3)
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
160 {:a => 'b'}.should include(:a => 'b')
161 "this string".should include("is str")
35d98aa @dchelimsky add start_with and end_with matchers to README [ci skip]
dchelimsky authored
162 "this string".should start_with("this")
163 "this string".should end_with("ring")
f574614 @dchelimsky use github-flavored-markdown in the readme
dchelimsky authored
164 ```
4958cc2 @dchelimsky words
dchelimsky authored
165
f492095 @dchelimsky words
dchelimsky authored
166 ## Also see
3fd7744 @dchelimsky update readme
dchelimsky authored
167
4958cc2 @dchelimsky words
dchelimsky authored
168 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)
169 * [http://github.com/rspec/rspec-core](http://github.com/rspec/rspec-core)
170 * [http://github.com/rspec/rspec-mocks](http://github.com/rspec/rspec-mocks)
Something went wrong with that request. Please try again.