Role models are important.

— Officer Alex J. Murphy / RoboCop

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

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.


This section discusses the idiomatic way to structure tests.

This section is currently a stub. Contributions welcome!


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

Refute Nil

Use refute_nil if not expecting nil.

# bad

# good

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.

# 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)
assert(!"rubocop-minitest" == (actual))

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

Assert Truthy

Use assert if expecting truthy value.

# bad
assert_equal(true, actual)

# good

Refute false

Use refute if expecting false.

# bad
assert_equal(false, actual)

# bad

# good

Assert Includes

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

# bad

# good
assert_includes(collection, object)

Refute Includes

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

# bad

# 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

# good

Refute Empty

Use refute_empty if expecting object to be not empty.

# bad

# good

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 =
puts object.method
assert_match expected, $

# 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

# good

Refute Path Exists

Use refute_path_exists if expecting path to not exist.

# bad

# good

Assert Match

Use assert_match if expecting matcher regex to match actual object.

# bad

# good
assert_match(pattern, object)

Refute Match

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

# bad

# 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 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

# good
refute_predicate expected, :zero?

Assert Responds To Method

Use assert_respond_to if expecting object to respond to a method.

# bad

# 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

# good
refute_respond_to(object, some_method)

Assert Instance Of

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

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

Refute Instance Of

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

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

Assert Kind Of

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

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

Refute Kind Of

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

# bad
# 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 }


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

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.


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:


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?