Automated Rails testing with Capybara and PhantomJS

Capybara is one of those tools that sounds great but is often frustrating. The claims of ‘no setup’ and ‘intuitive API’ make it sound like automating your browser testing is going to be a simple task. Unfortunately, the nature of these full-stack tests mean they’re often very tricky to get working reliably, and this has always put me off before. Testing should save you time, not create extra work.

This weekend, starting on a new test suite, I decided to go about really getting a solid Capybara setup, and get a complex test passing every time without anysleep hacks. Here’s how I did it.

1. Prerequisites

I used the following gems (add them to your Gemfile):

rspec-rails
capybara
database_cleaner
poltergeist
factory_girl_rails

You might also want to install phantomjs with your package manager if poltergeist doesn’t install first time.

Install with bundle install and then rails g rspec:install.

2. Test authentication

One of the first problems is how to get your ‘logged-in’ tests working. Devise’s regular helpers don’t work with Capybara (it doesn’t have access to the Rails request), so I used Warden.test_mode! instead:

In spec/rails_helper.rb:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


include Warden::Test::Helpers
Warden.test_mode!

RSpec.configure do |config|
  # Fast login for tests that specify &#039;login: true&#039;
  config.before(:each, login: true) do
    @user = FactoryGirl.create(:user)
    login_as(@user, scope: :user)
  end
end

This creates a user with FactoryGirl and logs them in before every test that has login: true, eg:

1
2


&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span class="n"&gt;describe&lt;/span&gt; &lt;span class="err"&gt;&#039;My&lt;/span&gt; &lt;span class="n"&gt;test&#039;,&lt;/span&gt; &lt;span class="n"&gt;login:&lt;/span&gt; &lt;span class="nb"&gt;true,&lt;/span&gt; &lt;span class="n"&gt;js:&lt;/span&gt; &lt;span class="nb"&gt;true&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;

3. Database cleaner

Since Capybara runs in a separate thread, and your tests run within a database transaction, the Capybara browser won’t see your database changes without some extra effort. My solution was to disable transactional fixtures and configure database_cleaner as described in this post.

In spec/support/database_cleaner.rb:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span class="no"&gt;RSpec.configure&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="o"&gt;|config|&lt;/span&gt;
  &lt;span class="n"&gt;config.before(:suite)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="no"&gt;DatabaseCleaner.clean_with(:truncation)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="n"&gt;config.before(:each)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="no"&gt;DatabaseCleaner.strategy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="ss"&gt;:transaction&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="n"&gt;config.before(:each,&lt;/span&gt; &lt;span class="ss"&gt;js:&lt;/span&gt; &lt;span class="kp"&gt;true)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="no"&gt;DatabaseCleaner.strategy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="ss"&gt;:truncation&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="n"&gt;config.before(:each)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="no"&gt;DatabaseCleaner.start&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="n"&gt;config.after(:each)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="no"&gt;DatabaseCleaner.clean&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;&lt;/pre&gt;&lt;/div&gt;

Basically, this says that for js tests, don’t use transactions but truncate the database tables instead.

4. Poltergeist

Poltergeist is a Capybara driver for PhantomJS, a nice tool that lets you automate JS testing without a browser.

This doesn’t take much configuration, but if you want to enable remote debugging (so you can attach a javascript console to your tests), you can use the following helper.

In spec/support/capybara.rb:

1
2
3
4
5
6
7


&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s1"&gt;&#039;capybara/rspec&#039;&lt;/span&gt;
&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s1"&gt;&#039;capybara/poltergeist&#039;&lt;/span&gt;
&lt;span class="no"&gt;Capybara.register_driver&lt;/span&gt; &lt;span class="ss"&gt;:poltergeist_debug&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="o"&gt;|app|&lt;/span&gt;
  &lt;span class="ss"&gt;Capybara::Poltergeist::Driver.new(app,&lt;/span&gt; &lt;span class="ss"&gt;inspector:&lt;/span&gt; &lt;span class="kp"&gt;true,&lt;/span&gt; &lt;span class="ss"&gt;debug:&lt;/span&gt; &lt;span class="kp"&gt;true)&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="no"&gt;Capybara.javascript_driver&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="ss"&gt;:poltergeist_debug&lt;/span&gt;
&lt;span class="no"&gt;Capybara.default_wait_time&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt;&lt;/pre&gt;&lt;/div&gt;

5. Waiting for asynchronous JS events

Capybara gives you many tools to help avoid timing issues, but sometimes they’re still not enough. Capybara 2.0 removed the wait_until feature, so you have to find another way to replicate this feature if Capybara’s built-in waiting isn’t working for you. After reading this post, I adapted their become_truematcher.

In spec/support/wait_steps.rb:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s2"&gt;"timeout"&lt;/span&gt;

&lt;span class="ss"&gt;RSpec::Matchers.define&lt;/span&gt; &lt;span class="ss"&gt;:become_true&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;match&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="o"&gt;|block|&lt;/span&gt;
    &lt;span class="k"&gt;begin&lt;/span&gt;
      &lt;span class="no"&gt;Timeout.timeout(Capybara.default_wait_time)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
        &lt;span class="k"&gt;until&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;block.call&lt;/span&gt;
          &lt;span class="nb"&gt;sleep&lt;/span&gt; &lt;span class="mi"&gt;0.1&lt;/span&gt;
        &lt;span class="k"&gt;end&lt;/span&gt;
        &lt;span class="n"&gt;value&lt;/span&gt;
      &lt;span class="k"&gt;end&lt;/span&gt;
    &lt;span class="k"&gt;rescue&lt;/span&gt; &lt;span class="no"&gt;TimeoutError&lt;/span&gt;
      &lt;span class="kp"&gt;false&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;supports_block_expectations?&lt;/span&gt;
    &lt;span class="kp"&gt;true&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;

This means you can do things like:

1
2


&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span class="n"&gt;expect{page.evaluate_script(&#039;someJSFunction()&#039;)}.to&lt;/span&gt; &lt;span class="n"&gt;become_true&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;

and the above code will wait until the JavaScript function returns true (eg. to indicate page readyness).

6. Troubleshooting non-determinism

If you’re still having trouble with non-deterministic tests:

Try reading the tips at https://github.com/teampoltergeist/poltergeist#troubleshooting
Disable CSS transitions! – this was driving me crazy. My solution was to set the effect duration to 0 in the JS plugin I was using, but you can also try this SO answer

7. The full helper file

This is my spec/rails_helper.rb in full:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span class="c1"&gt;# This file is copied to spec/ when you run &#039;rails generate rspec:install&#039;&lt;/span&gt;
&lt;span class="no"&gt;ENV&#091;"RAILS_ENV"]&lt;/span&gt; &lt;span class="o"&gt;||=&lt;/span&gt; &lt;span class="s1"&gt;&#039;test&#039;&lt;/span&gt;
&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s1"&gt;&#039;spec_helper&#039;&lt;/span&gt;
&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="no"&gt;File.expand_path("../../config/environment",&lt;/span&gt; &lt;span class="bp"&gt;__FILE__)&lt;/span&gt;
&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s1"&gt;&#039;rspec/rails&#039;&lt;/span&gt;

&lt;span class="c1"&gt;# Add additional requires below this line. Rails is not loaded until this point!&lt;/span&gt;
&lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="s1"&gt;&#039;factory_girl_rails&#039;&lt;/span&gt;
&lt;span class="kp"&gt;include&lt;/span&gt; &lt;span class="ss"&gt;Warden::Test::Helpers&lt;/span&gt;
&lt;span class="no"&gt;Warden.test_mode!&lt;/span&gt;

&lt;span class="no"&gt;Dir&#091;Rails.root.join("spec/support/**/*.rb")].each&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|f|&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="ss"&gt;ActiveRecord::Migration.maintain_test_schema!&lt;/span&gt;

&lt;span class="no"&gt;RSpec.configure&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="o"&gt;|config|&lt;/span&gt;
  &lt;span class="n"&gt;config.use_transactional_fixtures&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kp"&gt;false&lt;/span&gt;

  &lt;span class="n"&gt;config.include&lt;/span&gt; &lt;span class="ss"&gt;FactoryGirl::Syntax::Methods&lt;/span&gt;
  &lt;span class="n"&gt;config.infer_spec_type_from_file_location!&lt;/span&gt;

  &lt;span class="c1"&gt;# Fast login for tests that specify &#039;login: true&#039;&lt;/span&gt;
  &lt;span class="n"&gt;config.before(:each,&lt;/span&gt; &lt;span class="ss"&gt;login:&lt;/span&gt; &lt;span class="kp"&gt;true)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="vi"&gt;@user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="no"&gt;FactoryGirl.create(:user)&lt;/span&gt;
    &lt;span class="n"&gt;login_as(@user,&lt;/span&gt; &lt;span class="ss"&gt;scope:&lt;/span&gt; &lt;span class="ss"&gt;:user)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="c1"&gt;# Seed the database first&lt;/span&gt;
  &lt;span class="n"&gt;config.before(:suite)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="no"&gt;Rails.application.load_seed&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;

Hope someone else finds it useful.

Mike

1. Prerequisites#

2. Test authentication#

3. Database cleaner#

4. Poltergeist#

5. Waiting for asynchronous JS events#

6. Troubleshooting non-determinism#

7. The full helper file#