This is the ultimate, step by step Ruby on Rails guide to RSpec testing framework configuration in Ruby on Rails project.
Table of contents
Let's learn all about configuring RSpec...
...or have it done
Yes, Hix does this - so you don't have to.
RSpec is the most popular Ruby on Rails testing framework according to Ruby on Rails community. It is also perfectly capable to test any Ruby-written code. RSpec organization repository is neatly organized into smaller parts, such as:
and then some more. It all builds up into a comprehensive, fully-featured Ruby and Ruby on Rails testing framework.
One can easily see that the RSpec for Ruby on Rails is the most frequently developed of all the gems.
As stated on the official RSpec informative website, RSpec provides a Behavior-Driven Development, BDD for Ruby, and it makes Test-Driven Development, TDD, fun and productive.
Thorough documentation of the RSpec framework and all of its gems with executable examples is available thanks to Relish on their official website dedicated to RSpec.
Altogether it seems an awful lot, but it's definitely worth using RSpec in Ruby on Rails applications, as it is the most advanced Rails testing framework of all.
Now that we review what is the RSpec testing framework, let's take a look at why it should be your choice when it comes to Ruby on Rails testing.
As stated at the beginning, RSpec is the most popular choice for Ruby on Rails projects testing. However, it does not come with the default Ruby on Rails application setup, it needs to be installed manually.
The default framework for Ruby on Rails applications testing is a MiniTest. It is a built-in mechanism with the official Ruby on Rails documentation on how to write unit, functional, integration and system tests, and all of its terminologies explained.
Another noteworthy testing framework widely used with Ruby and Ruby on Rails - as with Java, Electron and many others - is a Cucumber framework.
So what does make RSpec the best choice for testing Ruby on Rails applications?
First of all, RSpec has the best documentation, which provides a ton of helpful examples and real-life scenarios that are commonly needed to be covered by developers. This is crucial for using anything that provides its own Domain-Specific Language - DSL- as the RSpec does.
On top of that, RSpec out of the box has all the features that developers need, and all of them are highly maintained.
MiniTest on the other hand, along with its claim that everything done by RSpec might be accomplished using dedicated plugins, does not maintain them successfully, and a lot of them are broken and have not been updated in a long time.
At last, RSpec is an application, while MiniTest and Cucumber are simply frameworks. I cannot stress enough how important it is for daily usage. It does not require anything else to run the test suite, providing an end to end solution for Ruby testing.
RSpec provides a mature, well maintained and documented command-line interface program. It works exactly as one would expect it to, with the CLI help available via the
Summing it all up, RSpec is the most popular community choice for testing Ruby on Rails applications. Thanks to that, as it's open-sourced, it is highly maintained, a lot of solutions to the common problems are easily googleable and it grows in power rapidly.
Code coverage, also known as test coverage, is a measure responsible for calculating the percentage of code used while running the program's test suite.
On its own, a 100% code coverage does not guarantee that the code does not contain any bugs, as a simple code execution does not guarantee its accuracy.
However, it gives a nice overview of the program's test suite as a whole, telling the developers which parts are safe to edit, and which are yet to be tested.
Using RSpec in Ruby on Rails, the most popular choice for calculating the project's code coverage reports is SimpleCov.
By default, it provides a simple total percentage of the project's test suite code coverage.
On top of that, SimpleCov allows grouping the reports by meaningful categories such as Ruby on Rails Controllers, Models, Views and Mailers, Sidekiq Workers and anything else that comes to mind for the given Ruby on Rails application, such as Service, Query, and Form Objects.
Using the SimpleCov gem, one can set it up to fail - which means returning a non-zero value CLI-wise - for a minimum (and maximum) test code coverage limits, enforcing developers to meet the established limitations.
It is a super helpful way to make people write tests when implemented in the Continuous Integration suite.
If you are serious about the code coverage, we recommend using Coveralls.
It is a SaaS that provides a comprehensive dashboard showing the test coverage history and statistics for the selected projects and can be easily integrated with any of the most used git repository hosting providers such as Github, Gitlab and Bitbucket.
You might have met it already, as it provides a very popular coverage badge, commonly included in the README files of Open Source projects, as Coveralls is free to use with any open-sourced code, forever.
Coveralls is an overall great tool to ensure a better Ruby on Rails application maintenance, providing both the simple and sophisticated overviews of the projects testing suite code coverage.
If you use Hix on Rails, you don't need to do any of the following - simply go through the setup wizard and be done with it, anytime you start a new project.
Otherwise, if you sadly did not automate this part of your life yet, read on.
Let us now configure the RSpec testing framework in the Ruby on Rails project, following a simple step by step guide.
In order to use RSpec with your Ruby on Rails application, you need to install the dedicated rspec-rails gem. Open your project's Gemfile and add it to the test and development groups.
group :development, :test do gem 'rspec-rails' end
Next, run the
bundle install command in your CLI after navigating to your project's root path, in order to include the gem in your Ruby on Rails project's Gemfile.lock file.
RSpec is equipped with the
rspec command, that comes with an initialization option. However, in Ruby on Rails, there's a dedicated generator to do just that. In your CLI, run the following command.
rails generate rspec:install
It generates three files: .rspec, spec/spec_helper.rb and spec/rails_helper.rb. The first file is loaded every time the
rspec command runs via CLI, passing the RSpec options to it. By default, it only tells RSpec to include the other helper files that are responsible for defining the gem's configuration.
A full list of options available resides under the
rspec --help command.
By default, there are three options defined in the second generated file, all of which are going to be the defaults in the next major version of the RSpec framework, the RSpec 4. It is recommended by the framework authors to leave them this way. Options are:
On top of that, there are some commented-out configuration options:
The last generated file, spec/rails_helper.rb, is responsible for defining the Ruby on Rails specific configuration. Those two are separated for performance reasons.
The third file does a multitude of helpful things:
From now on, whenever adding anything related to Ruby on Rails to the RSpec configuration, we are going to do so in the spec/rails_helper.rb file.
Let us do just that by adding a few helpful gems that make testing easier and more predictable.
In order to keep our Ruby on Rails project's test database clean between test runs, we are going to install an additional gem dedicated to doing just that, the DatabaseCleaner.
First of all, select and install one of the gems dedicated to specific Ruby on Rails ORMs supported by DatabaseCleaner. The most popular choice is going to be the Active Record gem. In your Gemfile file, add the gem of your choice to the test group.
group :test do gem 'database_cleaner-active_record' end
and run the
bundle install command from the root path of your Ruby on Rails project.
Next, let us tell RSpec to clean the Ruby on Rails project tests database in between the test suite runs. Open the spec/rails_helper.rb and add the following.
RSpec.configure do |config| # some # other # configuration config.before(:suite) do DatabaseCleaner.strategy = :truncation DatabaseCleaner.clean_with(:truncation) end config.before do DatabaseCleaner.strategy = :transaction DatabaseCleaner.start end config.append_after do DatabaseCleaner.clean end end
This set of configuration hooks tells RSpec to do the following:
Cleaning the Ruby on Rails tests database on all of these stages prevents the test's failures caused by any rubbish data leftovers generated between the RSpec tests run.
One of the most popular gems that support testing Ruby on Rails applications with RSpec is ShouldaMatchers. It provides a great toolkit for testing the methods commonly used in the classes provided in Ruby on Rails framework, such as
In order to use ShouldaMatchers in your Ruby on Rails project with RSpec, we need to install the shoulda-matchers gem first. Open the Gemfile file and add it to the tests group.
group :test do gem 'shoulda-matchers' end
bundle install command in your Ruby on Rails project's root directory, and edit the spec/rails_helper.rb with the following.
Shoulda::Matchers.configure do |config| config.integrate do |with| with.test_framework :rspec with.library :rails end end
That's it - your Ruby on Rails project is ready to use all the matchers provided by the ShouldaMatchers in the RSpec tests.
FactoryBot is the replacement of the most popular fixtures for Ruby on Rails projects. It provides a straightforward definition syntax and supports both multiple build strategies and factories for the same class, including inheritance.
In order to use FactoryBot in the Ruby on Rails project with RSpec, install the dedicated FactoryBotRails gem. Open the Gemfile file and add the following to the development and test groups.
group :development, :test do gem 'factory_bot_rails' end
Adding the gem to the development group results in modifying the default Ruby on Rails generators to produce related factories - from now on, whenever you generate the new model via command line, the corresponding factory will be generated as well.
In order to include the FactoryBot in the RSpec configuration, add the following to the spec/rails_helper.rb.
RSpec.configure do |config| # some other configuration config.include FactoryBot::Syntax::Methods end
You can take the full advantage of the FactoryBot gem whenever writing RSpec tests in your Ruby on Rails project.
As stated in the RSpec Ruby Styleguide, the best way to deal with time when testing Ruby on Rails applications with RSpec is to use the TimeCop gem.
TimeCop provides time freezing, travel, and acceleration capabilities, giving developers oneliners to deal with the time, instead of stubbing anything on
In order to use the TimeCop gem in your Ruby on Rails project, simply add it to the test group of your Gemfile file.
group :test do gem 'timecop' end
It does not require any configuration specific to RSpec in the Ruby on Rails project.
In order to take the quality of your RSpec Ruby tests to the next level, visit the Ruby on Rails RuboCop configuration guide - it provides the way to validate your RSpec tests suite in the Ruby on Rails project against aforementioned RSpec Style Guide automatically.
In order to generate the coverage reports in the Ruby on Rails application tested with RSpec, we are going to install the aforementioned SimpleCov gem. In your project's Gemfile, add the required gem to the test group.
group :test do gem 'simplecov' end
and next, navigate to your projects root path and run the
bundle install command.
By default, SimpleCov is going to generate all of its reports into the coverage directory of our project. Let's add it to the project's .gitignore file in order to avoid a massive amount of changes accompanying every test run.
Next, we are going to follow the gem instructions in order to turn on the SimpleCov code coverage gem every time the test suite runs. Open the spec/spec_helper.rb file and add the following at the beginning of it.
require 'simplecov' SimpleCov.start 'rails'
In the simplest manner possible, you're done - every test run is going to result in the code coverage report generation.
Now that we are generating the code coverage reports, let us track their history along the Ruby on Rails application development via Coveralls.
Follow the step by step guide in order to set up your Coveralls account and adding your Ruby on Rails project to it.
Be aware that you are going to subscribe to the Coveralls PRO in order to set up private repositories here.
After obtaining the Coveralls repository key and enabling it in the tool's interface, we are going to set it up in our Ruby on Rails project.
First, let's install the provided gem. Open the Gemfile file and add the coveralls to the test group.
group :test do gem 'coveralls' end
bundle install command and open the spec/spec_helper.rb file, in order to tell RSpec to use the provided formatter.
# frozen_string_literal: true require 'coveralls' require 'simplecov' SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new([SimpleCov::Formatter::HTMLFormatter, Coveralls::SimpleCov::Formatter]) SimpleCov.start 'rails'
The last step is to create a dedicated Coveralls configuration file with our previously generated repository key.
service_name: service-name repo_token: YOUR_COVERALLS_REPOSITORY_KEY
Depending on the Continuous Integration service that you use, update the service name accordingly.
My advice is to take another five minutes to figure out how to skip using the .coveralls.yml file completely, as keeping secrets checked into your remote repository might not be the best idea
It is better to define them as environment variables, and most of the Continuous Integration providers enable that option. Coveralls documentation gives you guidelines on how to do just that for their supported services.
The main goal here is to generate your code coverage reports via your RSpec tests run on the Continuous Integration whenever you merge the new feature to develop and master branches. This way your Coveralls history and statistics will not clutter with endless reports of identical feature branches code coverage data.
As stated multiple times in this guide, RSpec is the most popular choice for testing the Ruby on Rails applications, and for a number of good reasons.
If you care about Ruby on Rails tests, setting up the code coverage reporting is recommended - it gives developers a nice overview of the project's maintenance quality.
The SimpleCov gem is a simple to use solution to do just that in your Ruby on Rails projects that use RSpec - all it takes are two extra lines of code and the dedicated gem installed.
For those who want more control, enforcing the minimal code coverage in the Ruby on Rails application takes only the single line of code in the RSpec configuration file.
If you're looking for a professional overview of the code coverage statistics and history for your Ruby on Rails projects, use Coveralls - it aggregates your code coverage data and exposes it via sophisticated web UI.
As you can see, there's a lot of configuration related to the RSpec testing framework set up in the Ruby on Rails project -fortunately, you can skip most of it by using the Hix on Rails, the Ruby on Rails project generator.