Capybara and Poltergeist with RSpec


capybara

I used to think cucumber for Rails is a little bit over kill for the developer. Because every time you have to write a lot of regular expression to work it out. But in the recently project, we use Capybara and poltergeist with RSpec to solve this problem. It even can test your SPA and integrate with CI very nicely.

Poltergeist is a driver for Capybara. It allows you to run your Capybara tests on a headless WebKit browser, provided by PhantomJS. So, what is headless? That means you don’t need to fire up your browser. What’s that mean? Fast!!

  • Poltergeist is a wrapper for PhantomJS, so make sure your test env have that. If not brew install phantomjs in Mac.
  • Travis CI and codeship has PhantomJS pre-installed.


1. How to install Capybara and Poltergeist for your Rails project

Installation is really easy, you just need to install the gem capybara and poltergeist, put those lines in your Gemfile

1
2
3
4
group :test do
  gem 'capybara'
  gem 'poltergeist'
end

Then run bundle install.

2. Configure Poltergeist

Then in your spec_helper.rb. add those lines

1
2
3
4
5
6
7
8
9
10
11
require 'capybara'
require 'capybara/poltergeist'
Capybara.default_driver = :poltergeist
Capybara.javascript_driver = :poltergeist
Capybara.register_driver :poltergeist do |app|
  options = {:js_errors => true,
             :timeout => 120}
  Capybara::Poltergeist::Driver.new(app, options)
end

In the options, you can configure poltergeist. etc, If your :js_errors is false, then Javascript errors do not get re-raised in Ruby.
You can find all the setting options in poltergeist github page

3. Capybara with RSpec

If you are using Rails, put your Capybara specs in spec/features.

If you are not using Rails, tag all the example groups in which you want to use Capybara with :type => :feature.

You can now write your specs under spec/features/sign_in like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
describe "users signin process" do
  before :each do
    User.make(:email => 'user@example.com', :password => 'password')
  end
  it "signs the user in" do
    visit '/sessions/new'
    within("#session") do
      fill_in 'Email', :with => 'user@example.com'
      fill_in 'Password', :with => 'password'
    end
    click_button 'Sign in'
    expect(page).to have_content 'Success'
  end
end

As you can see, the syntax is more nice and clear, all you need to do is

  1. fill_in fields with data
  2. click button
  3. expect page have_content

But sometime, you still find some trick problems like

  • Could not find the field by fill_in, or how could i know the name of my field
  • Could not fire the click_button because I use Javascript event to handle that
  • Dont have the content for the Ajax call back



Here’s some tips for that

*Could not find the field by fill_in/dont know the name of my field

Capybara fill_in use css selector as the main selector, so if your field class is user_email, you can easily use fill_in 'user_email', with: 'user@example.com'


*Could not fire the click_button because I use Javascript event to handle that

This is a trick one. But capybara can execute the javascript script, so you still can ask javascript to simulate the click event for you.
for example, if you want to trigger a keyup event for Enter for an input. 

1
2
keypress_script = "var e = $.Event('keyup', { keyCode: 13 }); $('input.ui-autocomplete-input').trigger(e);"
page.driver.execute_script(keypress_script)

As you can see, the script have two main part, one is the event, the other is the place need to trigger that event. You need to find the keycode (13 for enter) from the key you need to simulate, and the event name(keyup/keydown). And make that field trigger it.

*Dont have the content for the Ajax call back

You use ajax, and expect the page have your ajax return content after you click/fire the event. But why the test still fail? Because capybara is not waiting for the ajax call. So you need to ask capybara wait for your ajax result by using sleep. You can try sleep 1 or 2 seconds. And then expect your page have that content. Thoughtbot have a nice write up about this, please check this link.

4. Final Tips:

If you dont know what happen in the page, you always can debug with save_and_open_page. I am sure that will save your thousand of times.