Have a look at our new "Complete Guide to Optimizing Slow Tests"! Discover →

24 Nov 2021 · Software Engineering

Setting up a BDD Stack on a Rails 5 Application

This post is adapted from Rails Testing Handbook, a free ebook on building sustainable Rails apps with BDD.

In this tutorial, we will guide you through the process of generating a new Rails 5 application, with all the necessary tools to set up a behavior-driven development (BDD) flow.

We will set up 5 tools that represent the base of BDD development in Rails:

When you’re finished setting up the project on your machine, we will set it up on Semaphore, and establish a fully automated continuous integration workflow.

System Prerequisites

To follow our guide, you need to have the following installed on your Unix-based machine.

Bootstrapping a Rails Application

Let’s start by installing Rails on our machines. Run the following command in your terminal:

gem install rails

Now, we are ready to generate a new Rails application.

rails new bdd-app -d postgresql

The -d postgresql specifies that our application will use PostgreSQL as our database management system instead of SQLite, which is set as a default for Rails.

Let’s now switch to your application’s directory:

cd bdd-app

Install your Rails application’s dependencies:

bundle install --path vendor/bundle

By passing the --path parameter we are telling bundler to install gems in the bdd-app/vendor/bundle directory. If you leave off the parameter, gems will be installed globally, which isn’t a good practice if you are working on more than one Ruby application on the development machine.

Finally, set up your database:

bundle exec rails db:create
bundle exec rails db:migrate

Installing RSpec

First, we will set up RSpec for writing unit specs.

Start by adding rspec in the Gemfile file, under the development and test group:

group :development, :test do
  gem 'rspec-rails', '~> 3.5'

Run bundle install to install the gem on your local machine.

To finish the install, invoke the rails generator to set up the spec directory in your application.

bundle exec rails generate rspec:install

When the command finishes, you should have a new spec directory in your project. This directory is the base for all of your unit specs.

Installing Cucumber

Next, we will continue to set up Cucumber, the tool used for writing acceptance tests.

Add cucumber-rails gems to the :development, :test group of your Gemfile:

group :development, :test do
  gem 'cucumber-rails', require: false

Run bundle install to install the gem on your local machine.

To finish the install, invoke the rails generator to set up the features directory in your application:

$ bundle exec rails generate cucumber:install

Running via Spring preloader in process 2192
      create  config/cucumber.yml
      create  script/cucumber
       chmod  script/cucumber
      create  features/step_definitions
      create  features/step_definitions/.gitkeep
      create  features/support
      create  features/support/env.rb
       exist  lib/tasks
      create  lib/tasks/cucumber.rake
        gsub  config/database.yml
        gsub  config/database.yml
       force  config/database.yml

When the command finishes, you should have a new features directory in your project. This directory is the base for all of your acceptance tests.

Installing Shoulda-matchers

The Shoulda-matchers gem speeds up our testing time by using wrappers around common Rails functionality, such as validations, associations, and redirects.

To install shoulda-matchers, we need to add the shoulda-matchers gem to our development and test group inside the Gemfile:

group :development, :test do
  gem 'shoulda-matchers', git: 'https://github.com/thoughtbot/shoulda-matchers.git', branch: 'rails-5'

Install the gem by running:

bundle install

We need to configure this gem by specifying the test frameworks and libraries we want to use it with. Open spec/rails_helper.rb and paste the following block at the end:

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec

    with.library :active_record
    with.library :active_model
    with.library :action_controller
    with.library :rails

Installing FactoryBot

Factory Bot is a gem used for making “fake” objects as test data. It is essentially a fixtures replacement with a clear definition syntax. It allows you to create fake objects in tests without providing a value for each attribute of the given object. If you don’t provide any values to the attributes of the object, factory_bot uses the default values that are previously defined in factory’s definition.

Add the following line to the development and test group of your Gemfile:

group :development, :test do
  gem 'factory_bot_rails'

Install the gem with:

bundle install

After the installation, you can place factories for your database models in the spec/factories directory.

Installing the Database Cleaner

We want to make sure that the state of the application is consistent every time we run our tests. The best way to do this is to clean all the data in the database between each test run, and construct a new clean state for each test.

The database-cleaner gem is a set of strategies for cleaning our database between test runs.

First, add the gem to the :test group in your Gemfile:

# Gemfile
group :test do
  gem 'database_cleaner'

Run bundle install to install the gem.

When the gem is installed, we will set up a cleaning strategy for RSpec tests. Open the spec/rails_helper.rb file, and add the following snippet:

RSpec.configure do |config|

  config.before(:suite) do
    DatabaseCleaner.strategy = :transaction

  config.around(:each) do |example|
    DatabaseCleaner.cleaning do


We don’t have to make any modifications to Cucumber. The cucumber-rails generator already created all the necessary hooks to integrate itself with the database-cleaner gem.

Setting up the Rails Controller Testing gem

The rails-controller-testing gem expands the capabilities of our controller specs. It allows us to test variable and template assignments.

Add it to your Gemfile under the test group:

gem 'rails-controller-testing'

Run bundle install to install the gem.

RSpec automatically integrates with this gem. Adding the gem to your Gemfile is sufficient for the helpers to work in your controller specs.

Setting up a Repository

We will use GitHub to set up your repository for this project.

First, let’s make sure that our repository is ready to be published and that we won’t push any unnecessary file or directory to GitHub.

Add the vendor/bundle directory to your .gitignore file to prevent pushing gems to Github.

echo 'vendor/bundle' >> .gitignore

Then, let’s create our first commit.

git add .
git commit -m "Bootstrapping Rails BDD application"

Visit https://github.com/new and create a new repository for your project. GitHub will give show you the instructions how to connect your local repository with the remote one.

New GitHub repository

Finally, add the new remote and push your code to GitHub.

git remote add origin git@github.com:<YOUR-USERNAME>/<YOUR-REPO>.git
git push -u origin master

Setting up Continuous Integration

As the final step in this tutorial, we will ensure that our project is started with a clean, greens build. This will be our first safe point of return for our application, and will act as the solid foundation for further development.

The first step is to create a free Semaphore account.

Choose your GitHub repository from the list:

Choose GitHub Repository

Follow the setup guide. Semaphore will recognize that you have a Rails project with Postgresql, and will generate all the commands for a successful first build.

Let’s tweak the command list, and add our RSpec and Cucumber test suites.

Semaphore Commands

Hit “Build With These Settings” to start the first build for your project.

First Green Build


Congratulations! You’ve set up a great foundation for behavior-driven development with Rails 5, RSpec and Cucumber. You are now fully equipped to work in the BDD cycle and deliver clean, working code.

Looking for more hands-on examples? Download the free Rails Testing Handbook to get in-depth knowledge on building sustainable Rails apps with tests.

Leave a Reply

Your email address will not be published.

Writen by:
Marko Anastasov is a software engineer, author, and co-founder of Semaphore. He worked on building and scaling Semaphore from an idea to a cloud-based platform used by some of the world’s engineering teams.