Setting up a BDD Stack on a Rails 5 Application
Tags: ruby, rails, testing, tutorial
Published: 2018-06-21 08:48:23

---
title: Setting up a BDD Stack on a Rails 5 Application
published: true
description: "Learn how to generate a new Ruby on Rails 5 application with all the necessary tools to set up a behavior-driven development (BDD) flow - RSpec, Cucumber, FactoryBot, etc."
tags: ruby, rails, testing, tutorial
canonical_url: https://semaphoreci.com/community/tutorials/setting-up-a-bdd-stack-on-a-rails-5-application
---

_This post is adapted from [Rails Testing Handbook](http://bit.ly/2K6gaDZ), 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](https://semaphoreci.com/ebooks/rails-testing-handbook).

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

- [RSpec](http://rspec.info) for writing unit test,
- [Cucumber](https://cucumber.io) for writing acceptance tests,
- [Shoulda Matchers](https://github.com/thoughtbot/shoulda-matchers) for enhancing model tests,
- [Factory Bot](https://github.com/thoughtbot/factory_bot) for factory based database fixtures, and
- [Database Cleaner](https://github.com/DatabaseCleaner/database_cleaner) for setting up a clean environment between test runs.
- [Rails Controller Testing](https://github.com/rails/rails-controller-testing) for expanding our controlling testing arsenal

When you're finished setting up the project on your machine, we will set it up on [Semaphore](https://semaphoreci.com), and establish a fully automated [continuous integration workflow](https://semaphoreci.com/blog/2017/03/02/what-is-proper-continuous-integration.html).

## System Prerequisites

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

- [Git](https://git-scm.com),
- [Ruby 2.4.0](https://www.ruby-lang.org/en) or newer,
- [Node.js](https://nodejs.org/en), and
- [PostgreSQL 9.5+](https://www.postgresql.org).

## Bootstrapping a Rails Application

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

``` bash
gem install rails
```

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

``` bash
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:

``` bash
cd bdd-app
```

Install your Rails application's dependencies:

``` bash
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:

``` bash
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:

``` ruby
group :development, :test do
  ...
  gem 'rspec-rails', '~> 3.5'
end
```

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.

``` bash
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:

``` ruby
group :development, :test do
  ...
  gem 'cucumber-rails', require: false
end
```

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:

``` bash
$ 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](https://github.com/thoughtbot/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`:

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

Install the gem by running:

``` bash
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:

``` ruby
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
  end
end
```

## Installing FactoryBot

[Factory Bot](https://github.com/thoughtbot/factory_bot_rails) 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`:

``` ruby
group :development, :test do
  ...
  gem 'factory_bot_rails'
end
```

Install the gem with:

``` bash
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](https://github.com/DatabaseCleaner/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'
end
```

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:

``` ruby
RSpec.configure do |config|

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

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

end
```

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](https://github.com/rails/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:

``` ruby
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.

``` bash
echo 'vendor/bundle' >> .gitignore
```

Then, let's create our first commit.

``` bash
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](https://s3.amazonaws.com/semaphore-imagecloud/dunja-radulov/004-new-repository.png)

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

``` bash
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](https://semaphoreci.com/users/sign_up).

Choose your GitHub repository from the list:

![Choose GitHub Repository](https://s3.amazonaws.com/semaphore-imagecloud/dunja-radulov/004-choose-github-repository.png)

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](https://s3.amazonaws.com/semaphore-imagecloud/dunja-radulov/004-semaphore-commands.png)

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

![First Green Build](https://s3.amazonaws.com/semaphore-imagecloud/dunja-radulov/004-first-green-build.png)

## Conclusion

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.

For more hands-on examples, download the free [Rails Testing Handbook](http://bit.ly/2K6gaDZ) to get in-depth knowledge on building sustainable Rails apps with tests.

Thanks for reading, and let me know your thoughts in the comments. :)