Introduction

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

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.

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

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:

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?