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.
📖 Read the documentation for the latest version. 📢 See what's changed in recent versions.
If you're working on a Rails app, then make sure to add this gem to the test
group in your Gemfile:
group :test do
gem 'shoulda-context', '~> 3.0.0.rc1'
end
If you're not working on a Rails app, then you can simply add:
gem 'shoulda-context', '~> 3.0.0.rc1'
Then run bundle install
.
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:
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:
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 you can write such tests as:
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
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 asetup
methodteardown
— a DSL-y alternative to defining ateardown
methodshould
— There are two forms:- when passed a name + block, creates a test equivalent to defining a
test_
method - when passed a matcher, creates a test that will run the matcher, asserting that it passes
- when passed a name + block, creates a test equivalent to defining a
should_not
— like the matcher version ofshould
, but creates a test that asserts that the matcher failsshould_eventually
— allows you to temporarily skip testscontext
— creates a subcontext
These methods are available within a test case class, but outside of a
context
:
should
— same as aboveshould_not
— same as aboveshould_eventually
— same as abovedescribed_type
— returns the class being tested, as determined by the class name of the outermost classsubject
— 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 ofsubject
above
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 orderingassert_contains
— asserts that an array has an itemassert_does_not_contain
— the opposite ofassert_contains
assert_accepts
— whatshould
uses internally; asserts that a matcher object matches against a valueassert_reject
— whatshould_not
uses internally; asserts that a matcher object does not match against a value
Shoulda Context is tested and supported against Ruby 2.7+, Rails 6.0+, Minitest 4.x, and Test::Unit 3.x.
Shoulda Context follows Semantic Versioning 2.0 as defined at http://semver.org.
Shoulda Context is currently maintained by Pedro Paiva. Previous maintainers include Elliot Winkler, Travis Jeffery, Gabe Berke-Williams, Ryan McGeary, Joe Ferris, Dan Croaky, and Tammer Saleh.
Shoulda Context is copyright © Tammer Saleh and thoughtbot, inc. It is free and opensource software and may be redistributed under the terms specified in the LICENSE file.
This repo is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.
We love open source software! See our other projects. We are available for hire.