Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Guard::RSpec automatically run your specs (much like autotest)
Ruby Groff

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

Guard::RSpec Build Status

RSpec guard allows to automatically & intelligently launch specs when files are modified.

  • Compatible with RSpec >= 2.11 (use guard-rspec 1.2.x for older release, including RSpec 1.x)
  • Tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby & Rubinius.


Please be sure to have Guard installed before continue.

Install the gem:

$ gem install guard-rspec

Add it to your Gemfile (inside development group):

group :development do
  gem 'guard-rspec'

Add guard definition to your Guardfile by running this command:

$ guard init rspec


Please read Guard usage doc


RSpec guard can be really adapted to all kind of projects.

Standard RubyGem project

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

Typical Rails app

guard 'rspec' do
  watch('spec/spec_helper.rb')                        { "spec" }
  watch('config/routes.rb')                           { "spec/routing" }
  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
  watch(%r{^lib/(.+)\.rb$})                           { |m| "spec/lib/#{m[1]}_spec.rb" }
  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }

Please read Guard doc for more information about the Guardfile DSL.


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

guard 'rspec', :cli => "--color --format nested --fail-fast --drb" do
  # ...

By default, Guard::RSpec will only look for spec files within spec in your project root. You can configure Guard::RSpec to look in additional paths by using the :spec_paths option:

guard 'rspec', :spec_paths => ["spec", "vendor/engines/reset/spec"] do
  # ...

If you have only one path to look, you can configure :spec_paths option with a string:

guard 'rspec', :spec_paths => "test" do
  # ...

If you want to set an environment variable, you can configure :env option with a hash:

guard 'rspec', :env => {'RAILS_ENV' => 'guard'} do
  # ...

Turnip is supported (Ruby 1.9.X only), but you must enable it:

guard 'rspec', :turnip => true do
  # ...

Former :color, :drb, :fail_fast and :formatter options are deprecated and have no effect anymore.

List of available options:

:cli => "-c -f doc"          # pass arbitrary RSpec CLI arguments, default: "-f progress"
:bundler => false            # use "bundle exec" to run the RSpec command, default: true
:binstubs => true            # use "bin/rspec" to run the RSpec command (takes precedence over :bundle), default: false
:rvm => ['1.8.7', '1.9.2']   # directly run your specs on multiple Rubies, default: nil
:notification => false       # display Growl (or Libnotify) notification after the specs are done running, default: true
:all_after_pass => false     # run all specs after changed specs pass, default: true
:all_on_start => false       # run all the specs at startup, default: true
:keep_failed => false        # keep failed specs until they pass, default: true
:run_all => { :cli => "-p" } # cli arguments to use when running all specs, default: same as :cli
:spec_paths => ["spec"]      # specify an array of paths that contain spec files
:turnip => true              # enable turnip support; default: false
:zeus => true                # enable zeus support; default: false
:focus_on_failed => false    # focus on the first 10 failed specs first, rerun till they pass

You can also use a custom binstubs directory using :binstubs => 'some-dir'.

DRb mode

When you specify --drb within :cli, guard-rspec will circumvent the rspec command line tool by directly communicating with the RSpec DRb server. This avoids the extra overhead incurred by your shell, bundler and loading RSpec's environment just to send a DRb message. It shaves off a second or two before the specs start to run; they should run almost immediately.


The notification feature is only available for RSpec < 2, and RSpec >= 2.4 (due to the multiple-formatters feature that was present in RSpec 1, was removed in RSpec 2 and reintroduced in RSpec 2.4). So if you are using a version between 2 and 2.4, you should disable the notification with :notification => false. Otherwise, nothing will be displayed in the terminal when your specs will run.

The best solution is still to update RSpec to the latest version!


The :formatter option has been removed since CLI arguments can be passed through the :cli option. If you want to use the former Instafail formatter, you need to use rspec-instafail gem instead:

# in your Gemfile
gem 'rspec-instafail'

# in your Guardfile
guard 'rspec', :cli => '-r rspec/instafail -f RSpec::Instafail' do
  # ...

Default formatter is the progress formatter (same as RSpec default).

Running a subset of all specs

The :all_on_start and :all_after_pass options cause all specs located in the spec directory to be run. If there are some specs you want to skip, you can tag them with RSpec metadata (such as :slow => true) and skip them with the cli --tag option (i.e. --tag ~slow).

You can also use option :spec_paths to override paths used when running all specs. You can use this feature to create multiple groups of guarded specs with distinct paths, and execute each in own process:

# in your Guardfile
group 'acceptance-tests' do
  guard 'rspec', :spec_paths => ['spec/acceptance'] do
    # ...

group 'unit-tests' do
  guard 'rspec', :spec_paths => ['spec/models', 'spec/controllers', 'spec/routing'] do
    # ...


Pull requests are very welcome! Make sure your patches are well tested. Please create a topic branch for every separate change you make.


Please run rake spec:prepare_fixtures once before launching specs.


Thibaud Guillaume-Gentil

Something went wrong with that request. Please try again.