Skip to content
Tutorials Center
My learning

Topics

Lesson 100 of 134 ยท Testing and Tooling

Testing with Minitest

Learn Minitest, the test library that ships with Ruby. Write test classes, use assertions, read failures and errors, share setup code and try the spec style.

A test is a small program that checks another program. Instead of running your code by hand and looking at the result, you write down what you expect once, and the computer checks it every time you change something. Good tests let you rename a method, rewrite a loop or upgrade Ruby and know within seconds whether anything broke.

Ruby comes with a test library called Minitest. It is small, fast and written in plain Ruby, so everything you learned about classes and methods applies. Rails uses it by default, and many popular gems use it too. In this lesson you will write test classes, learn the assertions you will use every day, read the three kinds of failing results, share setup code and meet the describe/it spec style.

In a real project you put tests in files such as test/wallet_test.rb and run them from a terminal. On this website everything runs as one script, so the examples define the class and its tests in the same file and start the run ourselves with Minitest.run. A small helper, run_suite, hides the one thing that changes between runs (the timing line) so the output you read here is exactly what you get.

Your first test

Here is a tiny class to test: a wallet that holds money in cents. A test class inherits from Minitest::Test, and every method whose name starts with test_ is one test. Inside a test you call assertions; the test passes if none of them fails.

Ruby A first Minitest test class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Read the report from top to bottom. Run options: --seed 1 is the number that decides the order of the tests (more on that soon). Under # Running: each dot is one passing test. The last line, 2 runs, 2 assertions, 0 failures, 0 errors, 0 skips, is the summary you will look at most: a run is a test method, an assertion is a single check inside it.

The most important assertion takes the expected value first and the actual value second: assert_equal expected, actual. When the order is swapped, the failure message still prints, but "Expected" and "Actual" are the wrong way around, which confuses whoever reads it.

Reading failures, errors and skips

A test can end in four ways, and the difference matters when you debug.

  • Pass (a dot): every assertion held.
  • Failure (F): an assertion said "no". Your code returned something other than expected.
  • Error (E): the test raised an unexpected exception. Your code (or the test) crashed.
  • Skip (S): the test called skip on purpose, for example for work that is not finished.

Let us produce one of each, with a bug in withdraw on purpose.

Ruby Failure, error and skip in one run (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Each problem gets a numbered block after the progress line. A failure shows the test name, the file and line of the assertion that failed (main.rb: followed by a line number), and Expected and Actual: here we expected 300 but got 299, because the buggy withdraw subtracts one cent too many. An error shows the exception class and message, then a backtrace: the @log instance variable was never set, so it is nil, and the report reads NoMethodError: undefined method 'last' for nil. A skip is only counted (1 skips) and hinted at with "Run with --verbose for details"; add -v to see the reason you gave, such as interest is not designed yet. Failures and errors both make the run fail, and a skip does not, but skips are a to-do list: never let them pile up.

Also notice the summary: 3 runs, 1 assertions, 1 failures, 1 errors, 1 skips. Only one assertion ran, because the errored test crashed before reaching any assertion and the skipped one stopped early.

When a test fails, read the first line of the message and the line number first. Nine times out of ten that is all you need. The backtrace of an error is longer; look for the first line that mentions your own file.

The assertions you will use every day

Minitest has more than thirty assertions, but a handful do almost all the work. Every assert_* has a refute_* twin that checks the opposite (assert_nil/refute_nil, assert_includes/refute_includes).

Assertion Passes when
assert(value) value is truthy (anything but nil and false)
assert_equal(expected, actual) expected == actual
assert_nil(value) value is nil
assert_includes(collection, item) collection.include?(item)
assert_empty(collection) collection.empty?
assert_match(regexp, string) the string matches the pattern
assert_in_delta(expected, actual, delta) the numbers differ by at most delta
assert_instance_of(Class, object) object.instance_of?(Class) exactly
assert_kind_of(Class, object) object.is_a?(Class)
assert_predicate(object, :empty?) object.empty? is truthy
assert_same(a, b) a and b are the very same object
assert_raises(Class) { ... } the block raises that exception (and returns it)
assert_output(out, err) { ... } the block prints exactly that to stdout and stderr
Ruby A tour of common assertions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Two details deserve attention. First, refute_equal 0.3, 0.1 + 0.2 passes because floating-point addition is not exact, so you compare floats with assert_in_delta, never assert_equal. Second, assert_raises returns the exception object, so you can check its message, as the exception test does. If you write assert_raises(Class) without a block, or the block raises a different class, the test fails with a clear message.

assert_equal nil, value is not allowed in the Minitest that ships with Ruby 4.0 (version 6): the test fails with the message Use assert_nil if expecting nil. even when the value really is nil. Always write assert_nil value.

Setup and teardown

Many tests start the same way. Instead of copying lines, define setup: Minitest calls it before every test method, on a fresh instance of your test class. Instance variables you set there are available in the test. If you need to clean something up afterwards (close a file, restore a setting), define teardown, which runs after each test, even when the test fails.

Ruby setup and teardown run around every test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Both tests see a playlist with exactly two songs, even though one of them adds a third, because setup builds a new playlist each time. The log shows the order setup, teardown repeated once per test. This is test isolation: no test may depend on what another test did.

Random order and the seed

Minitest runs your tests in a random order on purpose. If one test only passes because another ran before it, random order eventually exposes that hidden dependency. The --seed number makes a particular order repeatable: when a test fails in an odd way, run the suite again with the same seed to get the same order. The report prints the seed on its first line, so you can always copy it from there.

In a normal project you start the tests with a command such as the ones below (a read-only example, since it needs files on your computer):

Terminal
ruby -Itest test/wallet_test.rb
ruby -Itest test/wallet_test.rb -n test_deposit_adds_money
ruby -Itest test/wallet_test.rb --seed 4242
ruby -Itest test/wallet_test.rb -v

The first line runs a file. -n runs a single test by name (or a /pattern/), --seed repeats an order, and -v prints each test name as it runs. At the top of such a file you write require "minitest/autorun", which does for you what our run_suite helper does: it runs all tests when the script ends.

The spec style

If you prefer sentences to method names, Minitest also offers a describe/it syntax, called Minitest::Spec. It is the same engine with a different surface: describe creates a test class, it defines a test, before is setup, and expectations such as must_equal read like English.

Ruby The same tests in spec style

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The wrapper _( ... ) turns any value into an expectation object, so must_equal is not added to every object in your program. The verbose flag -v prints each test with the class name Stack plus a numbered, readable name. Nested describe blocks group related cases. Choose either style and stay consistent in a project; the assertion style (assert_equal) is plainer, the spec style reads more like a description. RSpec Overview shows the well-known third-party relative of this style.

Writing good tests

  • One idea per test. Name the test after the behavior: test_withdraw_rejects_overdraft, not test1.
  • Arrange, act, assert. Prepare the objects, call the code, then check the result. Keep a blank line between the three parts.
  • Test behavior, not implementation. Check what a method returns or does, not which private helpers it calls. Then you can refactor freely.
  • Test the edges. Empty input, zero, one, the largest value, and invalid input are where bugs live.
  • Keep tests fast and independent. No test should need another test to run first, and none should need the network.
  • A test you have never seen fail proves nothing. When you add one, make it fail first (see Test-Driven Development).

Common mistakes

  • Forgetting the test_ prefix. A method called check_total is never run, and nothing warns you.
  • Swapping expected and actual. It works until it fails, and then the message misleads you.
  • Comparing floats with assert_equal. Use assert_in_delta.
  • Sharing state between tests with constants, globals or class variables. Build fresh objects in setup.
  • Testing too much in one method. After the first failed assertion the rest never run.
  • Not testing the failure path. Use assert_raises for errors your code promises to raise, as in Exceptions.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which method name is picked up as a test by Minitest::Test?

    Minitest::Test runs every public instance method whose name starts with test_. Other names are ignored silently.
  2. 2. In assert_equal 300, wallet.cents, which argument is the expected value?

    The convention is expected first, actual second. The failure message labels them Expected and Actual, so the wrong order produces a misleading report.
  3. 3. A test raises NoMethodError because of a nil value inside your code. How does Minitest report it?

    A failure means an assertion did not hold. An unexpected exception is an error, shown with the exception class, message and backtrace.
  4. 4. What does setup do in a Minitest::Test class?

    setup runs before each test, so instance variables created there are fresh for every test. teardown runs after each one.
  5. 5. Why does Minitest run tests in random order by default?

    A test that only passes after another one is a hidden dependency. Random order finds it, and --seed lets you repeat a failing order.

Summary

  • Minitest ships with Ruby. A test class inherits from Minitest::Test, and each method named test_* is one test.
  • assert_equal expected, actual is the workhorse; assert_raises, assert_in_delta, assert_includes, assert_nil and friends cover most needs, and every assert_* has a refute_* opposite.
  • Results are pass (.), failure (F, a wrong value), error (E, an exception) or skip (S).
  • setup and teardown run around every test so tests stay independent.
  • Tests run in random order; --seed repeats an order, -n selects a test, -v is verbose.
  • describe/it with _(value).must_equal is the spec style of the same library.

Next: Test-Driven Development