minitest: Ruby's Fast and Explicit Testing Framework for TDD, BDD, and Benchmarking

What minitest Provides and Who It Is For

minitest is the standard library testing framework that ships with Ruby. It covers four testing modes: minitest/test for unit tests, minitest/spec for spec-style tests, minitest/benchmark for performance assertions, and minitest/pride for colorized output. These share a common runner and reporting infrastructure rather than being separate tools.

The primary audience is Ruby developers who want to write tests using the same language constructs they use in application code. The README contains a direct quote summarizing the design intent: "rspec is a testing DSL. minitest is ruby." This distinction matters in practice: test files are plain Ruby classes, test methods are plain Ruby methods, and refactoring tools like extract-method work on them without framework-specific knowledge.

The project has a notable AI policy. The README states that AI is not allowed in pull requests or issues. The last push was on 2026-07-22. The license is listed as unknown in the repository metadata, though the README has historically accompanied Ruby's own licensing.

Writing Unit Tests with minitest/test

Unit tests are Ruby classes that inherit from Minitest::Test. Test methods begin with test_ and use assertion methods to verify outcomes:

require "minitest/autorun"

class TestMeme < Minitest::Test
  def setup
    @meme = Meme.new
  end

  def test_that_kitty_can_eat
    assert_equal "OHAI!", @meme.i_can_has_cheezburger?
  end

  def test_that_it_will_not_blend
    refute_match /^no/i, @meme.will_it_blend?
  end

  def test_that_will_be_skipped
    skip "test this later"
  end
end

The require "minitest/autorun" line is the standard way to register all test classes for automatic execution when the file runs. The setup method runs before each test method; there is also a teardown method for cleanup. Because test discovery has no magic, only methods whose names start with test_ are run as tests: a method named check_something does not run automatically, which is different from some frameworks that introspect method signatures.

The README notes that minitest/test is designed for language implementors who need a minimal set of methods to bootstrap a working test suite.

Writing Specs with minitest/spec

minitest/spec provides a spec-style syntax using describe and it blocks that hooks onto the underlying minitest/test infrastructure. The expectations work through a wrapper method called _ that wraps the value being tested:

require "minitest/autorun"

describe Meme do
  before do
    @meme = Meme.new
  end

  describe "when asked about cheeseburgers" do
    it "must respond positively" do
      _(@meme.i_can_has_cheezburger?).must_equal "OHAI!"
    end
  end

  describe "when asked about blending possibilities" do
    it "won't say no" do
      _(@meme.will_it_blend?).wont_match /^no/i
    end
  end
end

The _ wrapper (a value call) is required in minitest 5 and later. The README notes that older code using direct chaining without _ may not work in current versions. The spec syntax generates the same Minitest::Test subclasses underneath; it is syntactic sugar rather than a separate test runner.

For additional matchers beyond what minitest/spec provides, the README links to minitest-matchers and minitest-matchers_vaccine as external projects.

Benchmarking with minitest/benchmark

minitest/benchmark adds performance assertions to the testing suite. Rather than just checking correctness, benchmark tests assert that an algorithm's runtime scales at a particular complexity class:

require "minitest/benchmark" if ENV["BENCH"]

class TestMeme < Minitest::Benchmark
  def bench_my_algorithm
    assert_performance_linear 0.9999 do |n|
      @obj.my_algorithm(n)
    end
  end
end

The assert_performance_linear call measures the algorithm at each value in the bench_range (defaulting to [1, 10, 100, 1000, 10000]) and checks that the timing fits a linear model with the given minimum R-squared value. Analogous assertions exist for constant, logarithmic, polynomial, and exponential complexity.

The ENV["BENCH"] guard shown in the README makes benchmarks optional; they only run when the BENCH environment variable is set. This keeps the main test suite fast by default while allowing CI jobs to run benchmarks separately. Output is tab-delimited to make it easy to paste into a spreadsheet.

Running Tests and Command-Line Options

The standard way to run a single test file is:

ruby -Ilib:test test/minitest/test_minitest_test.rb

The -Ilib:test flag adds both lib and test to the load path so that require statements in the test file can find both application code and test helpers. For larger suites, a Rake task generated by minitest/test_task is the recommended approach, and the README includes setup code for this.

Runtime options include --seed to set the random seed (test order is randomized by default), --verbose to show which tests are running, --name to filter by a string or regexp pattern, and --exclude to skip matching tests. The full option list appears when running with --help. Known extensions like pride and autotest also add their own flags to this output.

minitest vs. RSpec: The Practical Difference

RSpec and minitest occupy the same testing space in Ruby but with different philosophies. RSpec provides an extensive DSL with subject, let, shared_examples, custom matchers, and multi-line failure diffs. These make RSpec tests read as readable specification documents, at the cost of learning a non-Ruby vocabulary and adding a substantial gem dependency.

minitest uses Ruby directly: classes, methods, and assertions. A developer new to the codebase who knows Ruby but not minitest can read a minitest file immediately. Extract-method refactoring works on test methods. Private helper methods are just private methods on the test class.

The README describes minitest's runner as "incredibly small and fast" but does not provide benchmark comparison numbers against RSpec. The practical speed difference depends on the test suite size and the number of loaded gems. In suites with many files and a heavy boot time, the difference in test execution speed is often smaller than the difference in startup time.

Mocking and Stubbing Built In

minitest includes a built-in mocking library, minitest/mock. It provides a simple mock object that records expected method calls and raises Minitest::MockExpectationError if the expectations are not met. A mock is created with MiniTest::Mock.new, expectations are set with expect, and verification is done with verify.

For simpler stub-only needs, Minitest::Mock also allows using the stub method to temporarily replace a method on any object within a block. This covers a wide range of test isolation use cases without requiring a separate mocking library. For more complex mocking needs involving partial doubles or spy objects, external gems like mocha integrate with minitest.

The mock library design follows the same principle as the rest of minitest: use Ruby objects and methods rather than a separate DSL. The mock object is just a Ruby object, and verify is just a method call.

Editorial conclusion

minitest is the right choice for Ruby projects that value small dependencies, transparent internals, and a testing framework that uses ordinary Ruby objects and methods rather than a separate syntax layer. It is not the right choice for teams that rely on shared RSpec ecosystem tooling, specific matchers, or RSpec's rich failure formatting. Before adopting minitest in a Rails project, check whether your team's existing test infrastructure, including CI reporters and Vim or Emacs integrations, supports it; the minitest-reporters and editor plugins linked from the README cover most of these gaps.

Frequently asked questions

Official sources

1. Issues
2. minitest/minitest on GitHub
3. Project website
4. README