Shoulda Context

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.
📢 See what's changed in recent versions.

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:

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

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

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, Travis Jeffery, and thoughtbot. Thank you to all the contributors.

License

Shoulda Context is copyright © 2006-2020 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.