= Minitest Style Guide :idprefix: :idseparator: - :sectanchors: :sectlinks: :toc: preamble :toclevels: 1 ifndef::backend-pdf[] :toc-title: pass:[
== Introduction
[quote, Officer Alex J. Murphy / RoboCop]
Role models are important.
ifdef::env-github[] TIP: You can find a beautiful version of this guide with much improved navigation at https://minitest.rubystyle.guide. endif::[]
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.
https://github.com/rubocop/rubocop[RuboCop], a static code analyzer (linter) and formatter, has a https://github.com/rubocop/rubocop-minitest[`rubocop-minitest`] extension, provides a way to enforce the rules outlined in this guide.
You can generate a PDF copy of this guide using https://asciidoctor.org/docs/asciidoctor-pdf/[AsciiDoctor PDF], and an HTML copy https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html[with] https://asciidoctor.org/#installation[AsciiDoctor] using the following commands:
asciidoctor-pdf -a allow-uri-read README.adoc
Install the rouge gem to get nice syntax highlighting in the generated document.
====
== 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 [[assert-nil]]
Use assert_nil if expecting nil.
assert_equal(nil, actual)
=== Refute Nil [[refute-nil]]
Use refute_nil if not expecting nil.
assert(!actual.nil?) refute(actual.nil?)
=== Assert Equal Arguments Order[[assert-equal-args-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.
assert_equal(actual, "rubocop-minitest")
=== Refute Equal[[refute-equal]]
Use refute_equal if expected and actual should not be same.
assert("rubocop-minitest" != actual)
=== Assert Same [[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.
assert(expected.equal?(actual))
=== Refute Same [[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.
refute(expected.equal?(actual)) assert(!expected.equal?(actual))
=== Assert Truthy [[assert-truthy]]
Use assert if expecting truthy value.
assert_equal(true, actual)
=== Refute false [[refute-false]]
Use refute if expecting false.
assert_equal(false, actual)
assert(!something)
=== Assert Includes [[assert-includes]]
Use assert_includes to assert if the object is included in the collection.
assert(collection.include?(object))
=== Refute Includes [[refute-includes]]
Use refute_includes if the object is not included in the collection.
refute(collection.include?(object)) assert(!collection.include?(object))
=== Assert In Delta [[assert-in-delta]]
Use assert_in_delta if comparing floats. Assertion passes if the expected value is within the delta of actual value.
assert_equal(Math::PI, actual)
=== Refute In Delta [[refute-in-delta]]
Use refute_in_delta if comparing floats. Assertion passes if the expected value is NOT within the delta of actual value.
refute_equal(Math::PI, actual)
=== Assert Empty [[assert-empty]]
Use assert_empty if expecting object to be empty.
assert(object.empty?)
=== Refute Empty [[refute-empty]]
Use refute_empty if expecting object to be not empty.
assert(!object.empty?) refute(object.empty?)
=== Assert Operator [[assert-operator]]
Use assert_operator if comparing expected and actual object using operator.
assert(expected < actual)
=== Refute Operator [[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.
assert(!(expected > actual)) refute(expected > actual)
=== Assert Output [[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.
$stdout = StringIO.new puts object.method $stdout.rewind assert_match expected, $stdout.read
=== Assert Silent [[assert-silent]]
Use assert_silent to assert that nothing was written to stdout and stderr.
assert_output('', '') { puts object.do_something }
=== Assert Path Exists [[assert-path-exists]]
Use assert_path_exists if expecting path to exist.
assert(File.exist?(path))
=== Refute Path Exists [[refute-path-exists]]
Use refute_path_exists if expecting path to not exist.
assert(!File.exist?(path)) refute(File.exist?(path))
=== Assert Match [[assert-match]]
Use assert_match if expecting matcher regex to match actual object.
assert(pattern.match?(object))
=== Refute Match [[refute-match]]
Use refute_match if expecting matcher regex to not match actual object.
assert(!pattern.match?(object)) refute(pattern.match?(object))
=== Assert Predicate [[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.
assert expected.zero? # => Expected false to be truthy assert_equal 0, expected # => Expected: 0 Actual: 2
=== Refute Predicate [[refute-predicate]]
Use refute_predicate if expecting to test the predicate on the expected object and on applying predicate returns false.
assert(!expected.zero?) refute(expected.zero?)
=== Assert Responds To Method [[assert-respond-to]]
Use assert_respond_to if expecting object to respond to a method.
assert(object.respond_to?(some_method))
=== Refute Responds To Method [[refute-respond-to]]
Use refute_respond_to if expecting object to not respond to a method.
assert(!object.respond_to?(some_method)) refute(object.respond_to?(some_method))
=== Assert Instance Of [[assert-instance-of]]
Prefer assert_instance_of(class, object) over assert(object.instance_of?(class)).
assert('rubocop-minitest'.instance_of?(String))
=== Refute Instance Of [[refute-instance-of]]
Prefer refute_instance_of(class, object) over refute(object.instance_of?(class)).
refute('rubocop-minitest'.instance_of?(String))
=== Assert Kind Of [[assert-kind-of]]
Prefer assert_kind_of(class, object) over assert(object.kind_of?(class)).
assert('rubocop-minitest'.kind_of?(String))
=== Refute Kind Of [[refute-kind-of]]
Prefer refute_kind_of(class, object) over refute(object.kind_of?(class)).
refute('rubocop-minitest'.kind_of?(String))
=== Unspecified exception [[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.
assert_raises { 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 [[global-expectations]]
Use _() wrapper if using global expectations which are deprecated methods.
do_something.must_equal 2 { raise_exception }.must_raise TypeError
Check the http://docs.seattlerb.org/minitest/Minitest/Expectations.html[Minitest::Expectations doc] for more information about its usage.
=== Hooks [[hooks]]
If using a module containing setup or teardown methods, be sure to call super in the test class setup or
teardown.
class TestMeme < Minitest::Test include MyHelper
def setup do_something end
def teardown clean_something end end
class TestMeme < Minitest::Test include MyHelper
def setup super do_something end
=== Hooks Ordering [[hooks-ordering]]
Order hooks in the order in which they will be executed.
class SomethingTest < Minitest::Test def teardown; end def setup; end end
=== Extension Hooks [[extension-hooks]]
The before_* and after_* hooks are meant for libraries that extend minitest.
They are not meant to be used by test developers.
class SomethingTest < Minitest::Test def before_setup; end def before_teardown; end def after_setup; end def after_teardown; end end
=== Skipping Runnable Methods [[skipping-runnable-methods]]
Prefer skip over return for skipping runnable methods that start with test_.
def test_something return if condition? assert_equal(42, something) end
== File Naming [[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.
A common alternative is https://github.com/freerange/mocha[Mocha].
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.
class ParentTest < Minitest::Test def test_1
end end
class ChildTest < ParentTest def test_2
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
== 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 https://www.patreon.com/bbatsov[Patreon].
=== How to Contribute?
It's easy, just follow the contribution guidelines below:
== License
image:https://i.creativecommons.org/l/by/3.0/88x31.png[Creative Commons License] This work is licensed under a http://creativecommons.org/licenses/by/3.0/deed.en_US[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?