Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Guard::Minitest automatically run your tests (much like autotest)

Fix example in README

Explicitly use 'guard' in example, because there's no dependency on Guard.
latest commit 7738c49bfe
Cezary Baginski e2 authored


Gem Version Build Status Dependency Status Code Climate Coverage Status

Guard::Minitest allows to automatically & intelligently launch tests with the minitest framework when files are modified.

  • Compatible with minitest >= 3.0 (optimal support for 5.x).
  • Tested against Ruby 1.9.3, 2.0.0, JRuby and Rubinius (1.9 mode).


Please be sure to have Guard installed before you continue.

The simplest way to install Guard::Minitest is to use Bundler.

Add Guard::Minitest to your Gemfile:

group :development do
  gem 'guard' # NOTE: this is necessary in newer versions
  gem 'guard-minitest'

and install it by running Bundler:

$ bundle

Add guard definition to your Guardfile by running the following command:

guard init minitest

Ruby on Rails

Ruby on Rails lazy loads gems as needed in its test suite. As a result Guard::Minitest may not be able to run all tests until the gem dependencies are resolved.

To solve the issue either add the missing dependencies or remove the tests.


Specify ruby-prof as application's dependency in Gemfile to run benchmarks.

Rails automatically generates a performance test stub in the test/performance directory which can trigger this error. Either add ruby-prof to your Gemfile (inside the test group):

group :test do
   gem 'ruby-prof'

Or remove the test (or even the test/performance directory if it isn't necessary).


Please read Guard usage doc


Guard::Minitest can be adapated to all kind of projects. Please read guard doc for more info about the Guardfile DSL.

Standard Guardfile when using Minitest::Unit

guard :minitest do
  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
  watch(%r{^test/test_helper\.rb$})      { 'test' }

Standard Guardfile when using Minitest::Spec

guard :minitest do
  watch(%r{^lib/(.+)\.rb$})         { |m| "spec/#{m[1]}_spec.rb" }
  watch(%r{^spec/spec_helper\.rb$}) { 'spec' }


List of available options

all_on_start: false               # run all tests in group on startup, default: true
all_after_pass: true              # run all tests in group after changed specs pass, default: false
cli: '--test'                     # pass arbitrary Minitest CLI arguments, default: ''
test_folders: ['tests']           # specify an array of paths that contain test files, default: %w[test spec]
include: ['lib']                  # specify an array of include paths to the command that runs the tests
test_file_patterns: %w[test_*.rb] # specify an array of patterns that test files must match in order to be run, default: %w[*_test.rb test_*.rb *_spec.rb]
spring: true                      # enable spring support, default: false
zeus: true                        # enable zeus support; default: false
drb: true                         # enable DRb support, default: false
bundler: false                    # don't use "bundle exec" to run the minitest command, default: true
rubygems: true                    # require rubygems when running the minitest command (only if bundler is disabled), default: false
env: {}                           # specify some environment variables to be set when the test command is invoked, default: {}
all_env: {}                       # specify additional environment variables to be set when all tests are being run, default: false
autorun: false                    # require 'minitest/autorun' automatically, default: true

Options usage examples

:test_folders and :test_file_patterns

You can change the default location of test files using the :test_folders option and change the pattern of test files using the :test_file_patterns option:

guard :minitest, test_folders: 'test/unit', test_file_patterns: '*_test.rb' do
  # ...


You can pass any of the standard MiniTest CLI options using the :cli option:

guard :minitest, cli: '--seed 123456 --verbose' do
  # ...


Spring is supported (Ruby 1.9.X / Rails 3.2+ only), but you must enable it:

guard :minitest, spring: true do
  # ...

Since version 2.3.0, the default Spring command works is bin/rake test making the integration with your Rails >= 4.1 app effortless.

If you're using an older version of Rails (or no Rails at all), you might want to customize the Spring command, e.g.:

guard :minitest, spring: 'spring rake test' do
  # ...


Zeus is supported, but you must enable it. Please note that notifications support is very basic when using Zeus. The zeus client exit status is evaluated, and a Guard :success or :failed notification is triggered. It does not include the test results though.

If you're interested in improving it, please open a new issue.

If your test helper matches the test_file_patterns, it can lead to problems as guard-minitest will submit the test helper itself to the zeus test command when running all tests. For example, if the test helper is called test/test_helper.rb it will match test_*.rb. In this case you can either change the test_file_patterns or rename the test helper.

guard :minitest, zeus: true do
  # ...


Spork / spork-testunit is supported, but you must enable it:

guard :minitest, drb: true do
  # ...

The drb test runner honors the :include option, but does not (unlike the default runner) automatically include :test_folders. If you want to include the test paths, you must explicitly add them to :include.


Pull requests are very welcome! Please try to follow these simple rules if applicable:

  • Please create a topic branch for every separate change you make.
  • Make sure your patches are well tested. All specs run by Travis CI must pass.
  • Update the README.
  • Please do not change the version number.

For questions please join us in our Google group or on #guard (


Eric Steele


Yann Lugrin


Something went wrong with that request. Please try again.