Bootstrapping a Rails 5 application with Rspec and Capybara

This is a guide for my Lighthouse Labs students who asked me to demonstrate unit-testing. Whenever a I initialize a new project, I have to relearn the whole setup process, so this serves as handy primer to both my students and myself.

Assuming Rails 5 is all set up and ready to go…

Create a new project

1
2
rails new myapp -T
cd myapp

The -T option skips creation of the default test files.

Add all the testing dependencies

There are a bunch of gems I regularly use for testing:

Add them all these gems to the development/test group in your application’s Gemfile:

1
2
3
4
5
6
7
8
9
10
# Gemfile

# ...

group :development, :test do
  gem 'rspec-rails', '~> 3.5'
  gem 'shoulda-matchers'
  gem 'capybara'
  gem 'factory_girl_rails'
end

Install, of course:

1
bundle install

Configuration

Naturally, each of these new testing gems requires a bit of configuration to get working.

rspec

rspec is one of many great test suites. I like it the best, but that’s probably just because it’s the one I’m used to. It’s also great because a lot of people use it. So if you don’t know how to test something, chances are someone on StackOverflow does.

The rspec-rails gem comes with a handy generator that does a bunch of the setup work for you:

1
rails generate rspec:install

This added a new spec/ directory with a couple of helper files to your project. All your tests are stored in this directory. Run your rspec tests like this:

1
bundle exec rspec

We haven’t written any tests yet so you should see something like this:

1
2
3
4
5
No examples found.


Finished in 0.00028 seconds (files took 0.16948 seconds to load)
0 examples, 0 failures

shoulda-matchers

shoulda-matchers make testing common Rails functionality much faster and easier. You can write identical tests in rspec all by itself, but with shoulda-matcher these common tests are reduced to one line.

To set this up, you paste the following to your spec/rails_helper.rb file:

1
2
3
4
5
6
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

The tests you write with shoulda-matcher get executed when you run your rspec tests.

capybara

capybara tests the totality of your application’s functionality by simulating how a real-world agent actually interacts with your app.

First, paste the following into your spec/rails_helper.rb file:

1
require 'capybara/rails'

Now, paste the following into your spec/spec_helper.rb file:

1
require 'capybara/rspec'

factory_girl_rails

This provides a nice way to spoof the models you create in your application. To use it, you need to add a couple of things to your spec/spec_helper.rb file.

First, paste the following requirement:

1
require 'factory_girl_rails'

Then, add the following to the RSpec.configure block:

1
2
3
4
5
6
7
8
9
10
# RSpec
RSpec.configure do |config|

  # ...
  
  config.include FactoryGirl::Syntax::Methods

  # ...

end

Try it out

If everything is configured correctly, all the necessary test files will be created each time you generate some scaffolding. To see the options available, run

1
rails generate

This will show you a list of installed generators, including all the rspec and factory_girl stuff.

See what happens when you run

1
rails generate scaffold Agent

Take a peak in the spec/ directory now. You’ll see a bunch of boilerplate test code waiting for you to fill in the blanks with meaningful tests.

Before you run the tests, though, you’ll need to migrate the database:

1
bin/rails db:migrate RAILS_ENV=test

Now you can run the tests:

1
bundle exec rspec

You’ll see a whole bunch of pending tests like this:

1
2
3
4
5
Pending: (Failures listed here are expected and do not affect your suite's status)

  1) AgentsController GET #index assigns all agents as @agents
       # Add a hash of attributes valid for your model
       # ./spec/controllers/agents_controller_spec.rb:40

Get testing!