rspec_starter
rspec_starter is a Ruby gem that simplifies the process of running RSpec. Large development teams often manage multiple projects. Those projects tend to have subtle differences in how rspec should be invoked. Hopefully someone took the time to explain how to do it in the README, but this frequently doesn't happen.
With rspec_starter, a script is created which specifies how to run RSpec properly for the application. Anyone can invoke the bin/start_rspec
script to run the rspec test suite. No confusion. Self documenting. Amazing.
rspec_starter also helps smooth out differences between operating systems. For example, MacOS provides it's own display server for running feature tests whereas Linux operating systems may need to start a display sever, like XVFB, before feature tests will pass. Once rspec_starter is setup, developers simply execute the script and rspec_starter does the rest.
At the moment, rspec_starter works for Rails applications, Rails Engines and raw ruby applications/gems that are not database dependent.
Main Steps
rspec_starter can curently perform the following steps (these steps can be toggled on or off)
- Prepare a Rails database (or dummy database inside a Rails engine) by running
rake db:drop db:create db:migrate RAILS_ENV=test
- Remove the
tmp
folder if it exists - Verify XVFB is installed when running on a Linux box
- Start RSpec with
bundle exec rspec
orxvfb-run bundle exec rspec
(depending on the needs of the OS)
Versioning Strategy
This gem uses Semver 2.0.0.
Supported Ruby Versions
2.2.0+
Installation
Rails Applications & Rails Engines
Add this line to your Gemfile of your Rails application or Rails Engine:
group :development do
gem 'rspec_starter', require: false
end
And then execute:
$ bundle
Run the installer
$ rspec_starter --init
The above command installs the script you will use to run rspec. The file is named start_rspec
, but you can rename it to anything you like.
Usage
cd
into the root of your application/project and invoke the script. For these examples, it is assumed you placed the script in the bin
folder of your app (but you could put it anywhere you like).
$ bin/start_rspec
The above command will run the entire test suite. You can pass options to the script as well. Some of the options will be consumed by start_rspec and some will be forwarded on to rspec. As a result, you could do something like
$ bin/start_rspec spec/features
which tells start_rspec, to tell rspec, to only run the feature tests. Run the following command to see other ways to use the script
$ bin/start_rspec --help
Configuration
The entire idea behind start_rspec is to standardize the process of starting application. You can modify the bin/start_rspec
file to do whatever you want. If you open that file, you'll see that it does one thing - it calls the following command in the context of the root folder, of your project:
RspecStarter.start(prepare_db: true, remove_tmp: true, allow_xvfb: true)
The arguments passed to start_rspec
, represent the defaults you consider important for achieving a clean RSpec run. If your particular project doesn't have a DB, or you don't need it prepared before each Rspec run, you could turn that step off by passing prepare_db: false
.
Be careful about the steps you enable/disable inside the script file. The goal is to define steps that help people, with limited knowledge of the project, successfully run RSpec. It's best to have the bin/start_rspec define the best way to run rspec for newbies. You can disable specific steps by passing in command line options. Run bin/start_rspec --help
to see a list of available options.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/roberts1000/rspec_starter.