Minitest Style Guide

Introduction

Role models are important.

— Officer Alex J. Murphy / RoboCop

Tip	You can find a beautiful version of this guide with much improved navigation at https://minitest.rubystyle.guide.

This Minitest style guide outlines the recommended best practices for real-world programmers to write code that can be maintained by other real-world programmers.

RuboCop, a static code analyzer (linter) and formatter, has a rubocop-minitest extension, provides a way to enforce the rules outlined in this guide.

You can generate a PDF copy of this guide using AsciiDoctor PDF, and an HTML copy with AsciiDoctor using the following commands:

# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc

# Generates README.html
asciidoctor

Tip	Install the rouge gem to get nice syntax highlighting in the generated document. gem install rouge

A Living Document

This guide is a work in progress - existing guidelines are constantly being improved, new guidelines are added, occasionally some guidelines would get removed.

Layout

This section discusses the idiomatic way to structure tests.

Note	This section is currently a stub. Contributions welcome!

Assertions

This section discusses idiomatic usage of the assertions provided by Minitest.

Assert Nil

Use assert_nil if expecting nil.

# bad
assert_equal(nil, actual)

# good
assert_nil(actual)

Refute Nil

Use refute_nil if not expecting nil.

# bad
assert(!actual.nil?)
refute(actual.nil?)

# good
refute_nil(actual)

Assert Equal Arguments Order

assert_equal should always have expected value as first argument because if the assertion fails the error message would say expected "rubocop-minitest" received "rubocop" not the other way around.

Note	If you’re used to working with RSpec then this in the opposite order.

# bad
assert_equal(actual, "rubocop-minitest")

# good
assert_equal("rubocop-minitest", actual)

Refute Equal

Use refute_equal if expected and actual should not be same.

# bad
assert("rubocop-minitest" != actual)

# good
refute_equal("rubocop-minitest", actual)

Assert Same

Use assert_same instead of assert with equal?.

Note	Use assert_same only when there is a need to compare by identity. Otherwise, use assert_equal.

# bad
assert(expected.equal?(actual))

# good
assert_same(expected, actual)

Refute Same

Use refute_same instead of refute with equal?.

Note	Use refute_same only when there is a need to compare by identity. Otherwise, use refute_equal.

# bad
refute(expected.equal?(actual))
assert(!expected.equal?(actual))

# good
refute_same(expected, actual)

Assert Truthy

Use assert if expecting truthy value.

# bad
assert_equal(true, actual)

# good
assert(actual)

Refute false

Use refute if expecting false.

# bad
assert_equal(false, actual)

# bad
assert(!something)

# good
refute(actual)

Assert Includes

Use assert_includes to assert if the object is included in the collection.

# bad
assert(collection.include?(object))

# good
assert_includes(collection, object)

Refute Includes

Use refute_includes if the object is not included in the collection.

# bad
refute(collection.include?(object))
assert(!collection.include?(object))

# good
refute_includes(collection, object)

Assert In Delta

Use assert_in_delta if comparing floats. Assertion passes if the expected value is within the delta of actual value.

# bad
assert_equal(Math::PI, actual)

# good
assert_in_delta(Math::PI, actual, 0.01)

Refute In Delta

Use refute_in_delta if comparing floats. Assertion passes if the expected value is NOT within the delta of actual value.

# bad
refute_equal(Math::PI, actual)

# good
refute_in_delta(Math::PI, actual, 0.01)

Assert Empty

Use assert_empty if expecting object to be empty.

# bad
assert(object.empty?)

# good
assert_empty(object)

Refute Empty

Use refute_empty if expecting object to be not empty.

# bad
assert(!object.empty?)
refute(object.empty?)

# good
refute_empty(object)

Assert Operator

Use assert_operator if comparing expected and actual object using operator.

# bad
assert(expected < actual)

# good
assert_operator(expected, :<, actual)

Refute Operator

Use refute_operator if expecting expected object is not binary operator of the actual object. Assertion passes if the expected object is not binary operator (example: greater than) the actual object.

# bad
assert(!(expected > actual))
refute(expected > actual)

# good
refute_operator(expected, :>, actual)

Assert Output

Use assert_output to assert the methods output. Assertion passes if the expected output or error are matched or equal to the standard output/error. The expected value can be a regex, string or nil.

# bad
$stdout = StringIO.new
puts object.method
$stdout.rewind
assert_match expected, $stdout.read

# good
assert_output(expected) { puts object.method }

Assert Silent

Use assert_silent to assert that nothing was written to stdout and stderr.

# bad
assert_output('', '') { puts object.do_something }

# good
assert_silent { puts object.do_something }

Assert Path Exists

Use assert_path_exists if expecting path to exist.

# bad
assert(File.exist?(path))

# good
assert_path_exists(path)

Refute Path Exists

Use refute_path_exists if expecting path to not exist.

# bad
assert(!File.exist?(path))
refute(File.exist?(path))

# good
refute_path_exists(path)

Assert Match

Use assert_match if expecting matcher regex to match actual object.

# bad
assert(pattern.match?(object))

# good
assert_match(pattern, object)

Refute Match

Use refute_match if expecting matcher regex to not match actual object.

# bad
assert(!pattern.match?(object))
refute(pattern.match?(object))

# good
refute_match(pattern, object)

Assert Predicate

Use assert_predicate if expecting to test the predicate on the expected object and on applying predicate returns true. The benefit of using the assert_predicate over the assert or assert_equal is the user friendly error message when assertion fails.

# bad
assert expected.zero?     # => Expected false to be truthy
assert_equal 0, expected  # => Expected: 0 Actual: 2

# good
assert_predicate expected, :zero? # => Expected 2 to be zero?.

Refute Predicate

Use refute_predicate if expecting to test the predicate on the expected object and on applying predicate returns false.

# bad
assert(!expected.zero?)
refute(expected.zero?)

# good
refute_predicate expected, :zero?

Assert Responds To Method

Use assert_respond_to if expecting object to respond to a method.

# bad
assert(object.respond_to?(some_method))

# good
assert_respond_to(object, some_method)

Refute Responds To Method

Use refute_respond_to if expecting object to not respond to a method.

# bad
assert(!object.respond_to?(some_method))
refute(object.respond_to?(some_method))

# good
refute_respond_to(object, some_method)

Assert Instance Of

Prefer assert_instance_of(class, object) over assert(object.instance_of?(class)).

# bad
assert('rubocop-minitest'.instance_of?(String))

# good
assert_instance_of(String, 'rubocop-minitest')

Refute Instance Of

Prefer refute_instance_of(class, object) over refute(object.instance_of?(class)).

# bad
refute('rubocop-minitest'.instance_of?(String))

# good
refute_instance_of(String, 'rubocop-minitest')

Assert Kind Of

Prefer assert_kind_of(class, object) over assert(object.kind_of?(class)).

# bad
assert('rubocop-minitest'.kind_of?(String))

# good
assert_kind_of(String, 'rubocop-minitest')

Refute Kind Of

Prefer refute_kind_of(class, object) over refute(object.kind_of?(class)).

# bad
refute('rubocop-minitest'.kind_of?(String))

# good
refute_kind_of(String, 'rubocop-minitest')

Unspecified exception

Specify the exception being captured by assert_raises. This avoids false-positives when the raised exception is not the same users were expected.

# bad
assert_raises { do_something }

# good
assert_raises(FooException) { do_something }

Expectations

This section discusses idiomatic usage of the expectations provided by Minitest.

Note	This section is currently a stub. Contributions welcome!

Global Expectations

Use _() wrapper if using global expectations which are deprecated methods.

# bad
do_something.must_equal 2
{ raise_exception }.must_raise TypeError

# good
_(do_something).must_equal 2
value(do_something).must_equal 2
expect(do_something).must_equal 2
_ { raise_exception }.must_raise TypeError

Check the Minitest::Expectations doc for more information about its usage.

Hooks

If using a module containing setup or teardown methods, be sure to call super in the test class setup or teardown.

# bad
class TestMeme < Minitest::Test
  include MyHelper

  def setup
    do_something
  end

  def teardown
    clean_something
  end
end

# good
class TestMeme < Minitest::Test
  include MyHelper

  def setup
    super
    do_something
  end

  def teardown
    clean_something
    super
  end
end

Hooks Ordering

Order hooks in the order in which they will be executed.

# bad
class SomethingTest < Minitest::Test
  def teardown; end
  def setup; end
end

# good
class SomethingTest < Minitest::Test
  def setup; end
  def teardown; end
end

Extension Hooks

The before_* and after_* hooks are meant for libraries that extend minitest. They are not meant to be used by test developers.

# bad
class SomethingTest < Minitest::Test
  def before_setup; end
  def before_teardown; end
  def after_setup; end
  def after_teardown; end
end

# good
class SomethingTest < Minitest::Test
  def setup; end
  def teardown; end
end

Skipping Runnable Methods

Prefer skip over return for skipping runnable methods that start with test_.

# bad
def test_something
  return if condition?
  assert_equal(42, something)
end

# good
def test_something
  skip if condition?
  assert_equal(42, something)
end

File Naming

Use a consistent naming pattern of either a test_ prefix or a _test suffix for filenames of tests.

For a Rails app, follow the _test suffix convention, as used by the Rails generators.

For a gem, follow the test_ prefix convention, as used by the bundle gem generator.

Test Doubles

Minitest includes minitest/mock, a simple mock/stub system.

# example
service = Minitest::Mock.new
service.expect(:execute, true)

A common alternative is Mocha.

# example
service = mock
service.expects(:execute).returns(true)

Choose only one to use – avoid mixing both approaches within one project.

Subclassing Test Cases

Minitest uses Ruby classes, if a Minitest class inherits from another class, it will also inherit its methods causing Minitest to run the parent’s tests twice.

# bad (unless multiple runs are the intended behavior)
class ParentTest < Minitest::Test
  def test_1
    #... Run twice
  end
end

class ChildTest < ParentTest
  def test_2
    #...
  end
end

In rare cases, we may want to run the tests twice, but in general avoid subclassing test cases.

Note: The minitest/spec alternative syntax disable inheritance between test classes and so does not have this behavior.

Related Guides

• Ruby Style Guide

• Rails Style Guide

• RSpec Style Guide

Contributing

The guide is still a work in progress - some guidelines are lacking examples, some guidelines don’t have examples that illustrate them clearly enough. Improving such guidelines is a great (and simple way) to help the Ruby community!

In due time these issues will (hopefully) be addressed - just keep them in mind for now.

Nothing written in this guide is set in stone. It’s our desire to work together with everyone interested in Ruby coding style, so that we could ultimately create a resource that will be beneficial to the entire Ruby community.

Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!

You can also support the project (and RuboCop) with financial contributions via Patreon.

How to Contribute?

It’s easy, just follow the contribution guidelines below:

• Fork rubocop/minitest-style-guide on GitHub

• Make your feature addition or bug fix in a feature branch.

• Include a good description of your changes

• Push your feature branch to GitHub

• Send a Pull Request

License

This work is licensed under a Creative Commons Attribution 3.0 Unported License

Spread the Word

A community-driven style guide is of little use to a community that doesn’t know about its existence. Tweet about the guide, share it with your friends and colleagues. Every comment, suggestion or opinion we get makes the guide just a little bit better. And we want to have the best possible guide, don’t we?