The Absolute Beginner’s Guide to Capybara/RSpec

Sometimes the biggest challenge of using a new tool is not the syntax (there are always many examples for that) but getting set up. This is especially true and sometimes challenging for Rails, which is a convention-over-configuration kind of framework.

The situation

I need to write functional (aka integration or end-to-end) tests for a one-page app that relies entirely on AJAX to interact with a REST API.

Picking the tool

At the beginning I considered Cucumber. But I started seeing a lot of documentation for using Capybara in conjunction with RSpec, which I’m somewhat familiar with. It’s said to have an [intuitive API]( and uses an easy to understand DSL (domain-specific language). So I decided on using Capybara/RSpec.

Running into problems

It was rather challenging to figure out how to configure the two gems and where to put the tests inside the ‘/spec’ folder. After about 2 hours and running ‘rspec’ unsuccessfully 30 times, I narrowed down the *key* steps in setting up Capybara test framework in a Rails app:

1. Gemfile

group :development, :test do
  gem 'rspec-rails'
  gem 'capybara'

2. spec/spec_helper.rb

require 'rspec/rails'
require 'rspec/autorun'
require 'capybara/rails'
require 'capybara/rspec'
require 'capybara/dsl'

The first two lines are automatically generated when you do ‘rails g rspec:install’. However, you need to require the capybara pieces manually.

3. Config the gems in spec/spec_helper.rb

Apparently selenium is the default driver for Capybara but I set it explicitly to be safe (actually I was trying everything I could get my hands on).
Capybara.default_driver = :selenium

You also need to include Capybara::DSL module so you can use phrases like ‘visit ‘/’ ‘, ‘fill_in’, ‘click_button’ in the tests.
RSpec.configure do |config|
  config.include Capybara::DSL

4. Where to put spec files

For RSpec, tests go under ‘spec/lib’. However, with Capybara, I have seen tests being put both under ‘spec/features’ and ‘spec/integration’. I went with the latter: ‘spec/integration/name_spec.rb’

5. Require spec_helper

At the top of each of your test file, put ‘require ‘spec_helper’ ‘

6. Test syntax

According to documentation I have come across, you can write tests either with RSpec or Capybara conventions:

describe 'log in process' do
  it 'lets user log in' do
   # Test goes in here

I went with the Capybara way:
feature 'log in process', :js => true do
  scenario 'lets user log in' do
    # Test goes in here

`:js => true` is supposed to help you switch to the Capybara.javascript_driver (instead of the selenium default). However, my app ended needing to use selenium web driver.

7. Capybara DSL syntax

feature 'log in process', :js => true do
  scenario 'lets user log in' do
    visit '/sessions/new'
    fill_in 'Email', :with => ''
    fill_in 'Password', :with => 'password'
    click_button 'Sign in'
    expect(page).to have_content 'Success'

8. Capybara selectors

For ‘click_link’ you can select the element by id or text. But for ‘click_button’ or ‘fill_in’, you have to select by the button value or input placeholder value.
click_link('Link Text')
click_on('Link Text') # clicks on either links or buttons
click_on('Button Value')

You can also find element by its id or html tag:
find_field('First Name').value

9. Web driver!

Last but not least, after I set up everything else correctly and was able to run rspec without getting `undefined method` error for Capybara, my terminal told me I was missing this gem:
gem 'selenium-webdriver'


As promised, when you successfully execute Capybara, the test will open up a browser and fill out username and password in the field you told it to and decide whether it fails or succeeds.

This blog post barely touches the surface of testing with Capybara. But getting to this point was a great accomplishment for me, and writing the rest promises to be easier with the help of documentation.


2 thoughts on “The Absolute Beginner’s Guide to Capybara/RSpec

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s