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
|
# Shoulda Context [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge] [![Hound][hound-badge]][hound]
[version-badge]: https://img.shields.io/gem/v/shoulda-context.svg
[rubygems]: https://rubygems.org/gems/shoulda-matchers
[travis-badge]: https://img.shields.io/travis/thoughtbot/shoulda-context/master.svg
[travis]: https://travis-ci.org/thoughtbot/shoulda-context
[downloads-badge]: https://img.shields.io/gem/dtv/shoulda-context.svg
[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
[hound]: https://houndci.com
Shoulda Context makes it easy to write understandable and maintainable tests
under Minitest and Test::Unit within Rails projects or plain Ruby projects. It's
fully compatible with your existing tests and requires no retooling to use.
## Quick links
📖 **[Read the documentation for the latest version.][rubydocs]**
📢 **[See what's changed in recent versions.][changelog]**
[rubydocs]: http://rubydoc.info/github/thoughtbot/shoulda-context/master/frames
[changelog]: CHANGELOG.md
## Usage
Instead of writing Ruby methods with `lots_of_underscores`, Shoulda Context lets
you name your tests and group them together using English.
At a minimum, the gem provides some convenience layers around core Minitest /
Test::Unit functionality. For instance, this test case:
```ruby
class CalculatorTest < Minitest::Test
context "a calculator" do
setup do
@calculator = Calculator.new
end
should "add two numbers for the sum" do
assert_equal 4, @calculator.sum(2, 2)
end
should "multiply two numbers for the product" do
assert_equal 10, @calculator.product(2, 5)
end
end
end
```
turns into:
```ruby
class CalculatorTest < Minitest::Test
def setup
@calculator = Calculator.new
end
define_method "test_: a calculator should add two numbers for the sum" do
assert_equal 4, @calculator.sum(2, 2)
end
define_method "test_: a calculator should multiply two numbers for the product" do
assert_equal 10, @calculator.product(2, 5)
end
end
```
However, Shoulda Context also provides functionality apart from Minitest /
Test::Unit that allows you to shorten tests drastically by making use of
RSpec-compatible matchers. For instance, with [Shoulda
Matchers][shoulda-matchers] you can write such tests as:
```ruby
class User < ActiveSupport::TestCase
context "validations" do
subject { FactoryBot.build(:user) }
should validate_presence_of(:first_name)
should validate_presence_of(:last_name)
should validate_uniqueness_of(:email)
should_not allow_value('weird').for(:email)
end
end
```
[shoulda-matchers]: https://github.com/thoughtbot/shoulda-matchers
## API
### DSL
The primary method in Shoulda Context's API is `context`, which declares a group
of a tests.
These methods are available inside of a `context`:
* `setup` — a DSL-y alternative to defining a `setup` method
* `teardown` — a DSL-y alternative to defining a `teardown` method
* `should` — There are two forms:
1. when passed a name + block, creates a test equivalent to defining a
`test_` method
2. when passed a matcher, creates a test that will run the matcher, asserting
that it passes
* `should_not` — like the matcher version of `should`, but creates a test that
asserts that the matcher fails
* `should_eventually` — allows you to temporarily skip tests
* `context` — creates a subcontext
These methods are available within a test case class, but outside of a
`context`:
* `should` — same as above
* `should_not` — same as above
* `should_eventually` — same as above
* `described_type` — returns the class being tested, as determined by the class
name of the outermost class
* `subject` — lets you define an object that is the primary focus of the tests
within a context; this is most useful when using a matcher as the matcher will
make use of this as _its_ subject
And these methods are available inside of a test (whether defined via a method
or via `should`):
* `subject` — an instance of the class under test, which is derived
automatically from the name of the test case class but is overridable via the
class method version of `subject` above
### Assertions
In addition to the main API, the gem also provides some extra assertions that
may be of use:
* `assert_same_elements` — compares two arrays for equality, but ignoring
ordering
* `assert_contains` — asserts that an array has an item
* `assert_does_not_contain` — the opposite of `assert_contains`
* `assert_accepts` — what `should` uses internally; asserts that a matcher
object matches against a value
* `assert_reject` — what `should_not` uses internally; asserts that a matcher
object does not match against a value
## Note on running tests
Normally, you will run a single test like this:
ruby -I lib -I test path_to_test.rb -n name_of_test_method
When using Shoulda Context, however, you'll need to put a space after the test
name:
ruby -I lib -I test path_to_test.rb -n "test_: a calculator should add two numbers for the sum. "
If this is too cumbersome, consider using the [m] gem to run tests instead:
m path_to_test.rb:39
[m]: https://github.com/qrush/m
## Compatibility
Shoulda Context is tested and supported against Rails 4.x+, Minitest 4.x,
Test::Unit 3.x, and Ruby 2.4+.
## Credits
Shoulda Context is maintained by [Elliot Winkler][elliot-winkler], [Travis
Jeffery][travis-jeffery], and thoughtbot. Thank you to all the [contributors].
[elliot-winkler]: https://github.com/mcmire
[travis-jeffery]: https://github.com/travisjeffery
[contributors]: https://github.com/thoughtbot/shoulda-context/contributors
## License
Shoulda Context is copyright © 2006-2020 [thoughtbot, inc][thoughtbot-website].
It is free software, and may be redistributed under the terms specified in the
[MIT-LICENSE](MIT-LICENSE) file.
[thoughtbot-website]: https://thoughtbot.com
|
