Configuring Your Rails App for Rspec, Cabybara and Selenium Tests

Writing the first integration test for a rails app could sometimes be unpleasant. It happened to me, so I know how it feels. I searched for days, found materials but they were just always half solutions.

The intention was to test my app with Rspec and Capybara. Little did I know that the feature I wanted from Capybara was a feature of Selenium which would be like a support to Capybara. I wanted to see my tests run in a full screen web browser so I could get insight on what was going on.

I finally found the way! I’m writing on this subject because I don’t want others to spend days figuring out how to test their rails app with these tools and also because I don’t want them to get somethings wrong when they think they have found it.

I hope to make this as understandable and helpful as possible.

To get started, add the following to your gemfile in the development/test group:

gem “rspec-rails”, “~> 3.0”

gem “capybara”

gem “selenium-webdriver”

You may use the following if you do not have a development and test group already:

group :development, :test do

gem “rspec-rails”, “~> 3.0”

gem “capybara”

gem “selenium-webdriver”


NB: Please specify your rspec version if it is not up to 3.0 or close to it.

Run bundle on your terminal to install the gems and you should be ready to cruise.

Then create a feature directory inside your spec directory.

Create a file with the name of the feature you want to test within the feature directory, with the command below, this would generate a file that ends with ‘_spec.rb’.

rails g rspec:spec feature your_feature_file_name

Ideally, your rails helper should already require your spec helper. If it doesn’t, just add:

require “spec_helper”

Add the following to your rails helper:

require “rspec/rails”

require “capybara/rspec”

require “capybara/rails”

You can add them to your spec helper too, since they would automatically be required in your rails helper but I prefer them here, no specific reasons, maybe just part of those little things that do not matter in the life of a programmer.

At the top of all your test files you should:

require “rails_helper”

After which you should have a block like this:

RSpec.feature “#{your_test_case_title}”, type: :feature do

before do

Capybara.default_driver = :selenium


# Your examples should go here.


The block initiates a rspec test with the title you specify and also informs rspec that this is a feature test.

Right within the feature block above, you should create a before block similar to the one I placed up there(in italics) before any of your examples:

PS: Please do not make the mistake of setting your Capybara default server to localhost(as I found in a tutorial I once used). It could generate errors that may cause you wasted hours of figuring and fixing.

The rest is Capybara. That should be all about configuration.

Capybara is basically a group of scenario blocks, let us take the following as an instance:

scenario “visit” do

visit “/”

expect(page).to have_title “#{your_page_title}”

expect(page).to have_css “h1”, text: “# {any_text_within_h1_tag_on_your_page}”


What the test above does can be implied-

#visit “/”: We want to test for things on the homepage

expect(page).to have_title “#{your_page_title}” : We want to know if the page(which is the homepage in this case) has its title set to what we specified.

expect(page).to have_css “h1”, text: “#{any_text_within_h1_tag_on_your_page}”: We want to know if the page has a h1 tag with the content specified above.

As expected it reads like normal English grammar.

The Technicality:

The expect(page).to have_title “#{your_page_title}”.

Here, we pass the ‘page’ as a parameter to the ‘expect’ method. Then, we call the ‘to’ method on it, passing the ‘have_title’ method with the page title as its parameter to it.

I feel the chaining should not be an issue if you already have some basic understanding of ruby. However, here is a resource for those who may find it confusing.

To run your tests, you can run single test files as in:

bundle exec rspec spec/features/search_spec.rb

or run the whole suite as in:

bundle exec rspec

if you want the test to read like a document just append the following to the bundle command:

-f documentation

The following are useful resources to get you started with Rspec and Capybara:

Please note that rspec for rails is a little different from ruby. You may find the following useful for ruby:

It is important to note that Selenium initiates firefox to run your test. Therefore, you may have to install firefox if you haven’t already. Although there’s a way to make it work with Chrome, I have not tried it and I don’t think it is necessary but this could be a useful resource if you choose to try it out.

There are also a number of drivers you can use with Capybara instead of Selenium, one of which is webkit but that is not the focus of this writing.

I believe you may not necessarily have to test your controllers and views separately if your code and integration tests are properly written because they would have been tested with your integration suite. You may just have to write separate unit tests for your models and maybe decorators, presenters, concerns, POROs et al (if you have any and they haven’t been tested already).

I hope this gets you up to speed while testing your rails app.

Please do not hesitate to contact me if you have any questions, observations or feedback.

You can also read this article on quora.


Backend Engineer |

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store