Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Guard::Spork automatically manage Spork DRb servers
Latest commit da16fbb @xrkhill xrkhill Merge pull request #133 from chrismar035/patch-1
Add license to gemspec

Guard::Spork Build Status Dependency Status Gem Version

Guard::Spork allows to automatically & intelligently start/reload your RSpec/Cucumber/Test::Unit Spork server(s).

  • Compatible with Spork 0.8.4 & 0.9.0.rcX.
  • Tested against Ruby 1.9.3, 2.0.0, 2.1.2, and JRuby.


Please be sure to have Guard installed before continuing.

Install the gem:

$ gem install guard-spork

Add it to your Gemfile (inside development group):

group :development do
  gem 'guard-spork'

Add guard definition to your Guardfile with:

$ guard init spork


Please read the Guard usage documentation.


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

IMPORTANT: place Spork guard before RSpec/Cucumber/Test::Unit guards!

Rails app

guard 'spork' do
  watch('spec/spec_helper.rb') { :rspec }
  watch('test/test_helper.rb') { :test_unit }
  watch(%r{features/support/}) { :cucumber }

Running specs over Spork

Pass the :cmd => "rspec --drb" option to Guard::RSpec and/or Guard::Cucumber to run them over the Spork DRb server:

guard 'rspec', :cmd => "rspec --drb" do
  # ...

guard 'cucumber', :cmd => "rspec --drb" do
  # ...

For MiniTest Guard you should pass the :drb => true option:

guard 'minitest', :drb => true do
  # ...


Guard::Spork automatically detect RSpec/Cucumber/Test::Unit/Bundler presence but you can disable any of them with the corresponding options:

guard 'spork', :rspec => false, :cucumber => false, :test_unit => false, :bundler => false do
  # ...

You can provide additional environment variables for RSpec, Cucumber, and Test::Unit with the :rspec_env, :cucumber_env, and :test_unit_env options:

guard 'spork', :cucumber_env => { 'RAILS_ENV' => 'cucumber' }, :rspec_env => { 'RAILS_ENV' => 'test' }, :test_unit_env => { 'RAILS_ENV' => 'test' } do
  # ...

If your application runs on Heroku or otherwise uses Foreman, you can provide the :foreman => true option to have environment variables present in the .env file passed on to the Spork server.

Available options:

:wait => 60                                # Seconds to wait for the server to start, default: 30. Setting it to nil will cause it to wait indefinitely.
:retry_delay => 60                         # Seconds to wait before retrying booting the server, default: 30. Setting it to nil will cause it to wait indefinitely.
:cucumber => false
:rspec => false
:test_unit => false
:minitest => false
:bundler => false                          # Don't use "bundle exec"
:test_unit_port => 1233                    # Default: 8988
:rspec_port => 1234                        # Default: 8989
:cucumber_port => 4321                     # Default: 8990
:test_unit_env => { 'RAILS_ENV' => 'baz' } # Default: nil
:rspec_env => { 'RAILS_ENV' => 'foo' }     # Default: nil
:cucumber_env => { 'RAILS_ENV' => 'bar' }  # Default: nil
:aggressive_kill => false                  # Default: true, will search Spork pids from `ps aux` and kill them all on start.
:notify_on_start => true                   # Default: false, will notify as soon as starting begins.
:foreman => true                           # Default: false, will start Spork through `foreman run` to pick up environment variables used by Foreman. Pass an env file {:env => ".env.test"}
:quiet => true                             # Default: false, will silence some of the debugging output which can get repetitive (only work with Spork edge at the moment).

Common troubleshooting

If you can start Spork manually but get the following error message when using Guard::Spork:

Starting Spork for RSpec ERROR: Could not start Spork for RSpec/Cucumber. Make sure you can use it manually first.

Try to increase the value of the :wait => 60 option before any further investigation. It's possible that this error is the result of an unnecessary /test directory in the root of your application. Removing the /test directory entirely may resolve this error.


Pull requests are very welcome! Please try to follow these simple "rules", though:

  • Please create a topic branch for every separate change you make.
  • Make sure your patches are well tested.
  • Update the README (if applicable).
  • Please do not change the version number.

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


Thibaud Guillaume-Gentil

Something went wrong with that request. Please try again.