1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
# Built in matchers
`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/main/Should.md) for why we recommend using `expect`.
e.g.
```ruby
expect(result).to eq(3)
expect(list).not_to be_empty
pi.should be > 3
```
## Object identity
```ruby
expect(actual).to be(expected) # passes if actual.equal?(expected)
```
## Object equivalence
```ruby
expect(actual).to eq(expected) # passes if actual == expected
```
## Optional APIs for identity/equivalence
```ruby
expect(actual).to eql(expected) # passes if actual.eql?(expected)
expect(actual).to equal(expected) # passes if actual.equal?(expected)
# NOTE: `expect` does not support `==` matcher.
```
## Comparisons
```ruby
expect(actual).to be > expected
expect(actual).to be >= expected
expect(actual).to be <= expected
expect(actual).to be < expected
expect(actual).to be_between(minimum, maximum).inclusive
expect(actual).to be_between(minimum, maximum).exclusive
expect(actual).to match(/expression/)
expect(actual).to be_within(delta).of(expected)
expect(actual).to start_with expected
expect(actual).to end_with expected
# NOTE: `expect` does not support `=~` matcher.
```
## Types/classes/response
```ruby
expect(actual).to be_instance_of(expected)
expect(actual).to be_kind_of(expected)
expect(actual).to respond_to(expected)
```
## Truthiness and existentialism
```ruby
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
expect(actual).to exist # passes if actual.exist? and/or actual.exists? are truthy
expect(actual).to exist(*args) # passes if actual.exist?(*args) and/or actual.exists?(*args) are truthy
```
## Expecting errors
```ruby
expect { ... }.to raise_error
expect { ... }.to raise_error(ErrorClass)
expect { ... }.to raise_error("message")
expect { ... }.to raise_error(ErrorClass, "message")
```
## Expecting throws
```ruby
expect { ... }.to throw_symbol
expect { ... }.to throw_symbol(:symbol)
expect { ... }.to throw_symbol(:symbol, 'value')
```
## Predicate matchers
```ruby
expect(actual).to be_xxx # passes if actual.xxx?
expect(actual).to have_xxx(:arg) # passes if actual.has_xxx?(:arg)
```
### Examples
```ruby
expect([]).to be_empty
expect(:a => 1).to have_key(:a)
```
## Collection membership
```ruby
expect(actual).to include(expected)
expect(array).to match_array(expected_array)
# ...which is the same as:
expect(array).to contain_exactly(individual, elements)
```
### Examples
```ruby
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 contain_exactly(2, 1, 3)
expect([1, 2, 3]).to match_array([3, 2, 1])
```
## Ranges (1.9+ only)
```ruby
expect(1..10).to cover(3)
```
## Change observation
```ruby
expect { object.action }.to change(object, :value).from(old).to(new)
expect { object.action }.to change(object, :value).by(delta)
expect { object.action }.to change(object, :value).by_at_least(minimum_delta)
expect { object.action }.to change(object, :value).by_at_most(maximum_delta)
```
### Examples
```ruby
expect { a += 1 }.to change { a }.by(1)
expect { a += 3 }.to change { a }.from(2)
expect { a += 3 }.to change { a }.by_at_least(2)
```
## Satisfy
```ruby
expect(actual).to satisfy { |value| value == expected }
```
## Output capture
```ruby
expect { actual }.to output("some output").to_stdout
expect { actual }.to output("some error").to_stderr
```
## Block expectation
```ruby
expect { |b| object.action(&b) }.to yield_control
expect { |b| object.action(&b) }.to yield_with_no_args # only matches no args
expect { |b| object.action(&b) }.to yield_with_args # matches any args
expect { |b| object.action(&b) }.to yield_successive_args(*args) # matches args against multiple yields
```
### Examples
```ruby
expect { |b| User.transaction(&b) }.to yield_control
expect { |b| User.transaction(&b) }.to yield_with_no_args
expect { |b| 5.tap(&b) }.not_to yield_with_no_args # because it yields with `5`
expect { |b| 5.tap(&b) }.to yield_with_args(5) # because 5 == 5
expect { |b| 5.tap(&b) }.to yield_with_args(Integer) # because Integer === 5
expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
```
|
