Acceptance Testing Using Capybara and PhantomJS

Feb 16, 2016 • packagecloud


Running acceptance tests against a full web stack, like PhantomJS, can decrease overall testing time by reducing the number dependencies (i.e. Xvfb) needed by your CI server. This post will go over how we package and distribute PhantomJS and how to write acceptance tests to catch JavaScript errors before they hit production.

Benefits of Acceptance Testing

Acceptance testing is key to ensuring your browser-facing apps are working as expected. With acceptance testing you can write assertions on what users should expect to see on a page by testing that the required DOM elements are loaded. By loading a full DOM environment in your testing framework, these tests can catch JavaScript errors on your pages before they go out to production.

Acceptance Testing Framework - Capybara/Poltergeist

As useful as these types of tests can be, getting acceptance tests running on a CI server can be tricky and can add significant overhead to testing time. We use Capybara to write acceptance tests because of its intuitive DSL, integration with Rails, and the ability to integrate with different web-drivers. We use Poltergeist as the web-driver for Capybara because it allows us to use PhantomJS on our CI server which doesn’t require an X server to run tests against a browser. Poltergeist is solely dependent on PhantomJS and will require any machine running your acceptance tests to have PhantomJS available.

Providing the PhantomJS Dependency

Before we can start using a headless browser in our acceptance testing framework, we’ll first need to provide the PhantomJS dependency for our system. Since there are no official packages for PhantomJS, we need to build it from source on our target operating system, and then package it into the format we need. While there are no official packages (deb, rpm, etc.) for PhantomJS, there is an official static build available on the PhantomJS website. We also have a packagecloud repository containing PhantomJS packages for different operating systems. We won’t go over the steps on how to build the package from source, but you can take a look at this post and this post to get a better idea on how to build packages.

Once we have the package for PhantomJS, we can push it up to our packagecloud repository.

package_cloud push armando/phantomjs ./phantomjs_2.0.0_amd64.deb

Now all we have to do is install the repository onto our CI server using the bash scripts provided by packagecloud.

curl -s | sudo bash

And install the package during the CI setup process:

sudo apt-get install phantomjs

Push and install your own packages in minutes

Testing for JavaScript errors using Capybara with Poltergeist and Rspec

Capybara uses rack_test as its default driver for running tests, which is fast but doesn’t support JavaScript. To test for JavaScript errors in your Capybara tests you can enable it in the scenario (which is an alias for it in the Capybara DSL):

feature "Some JavaScript Stuff" do
  scenario "load homepage", :js => true do
    visit "/"
    expect(page).to have_content "some content enabled by javascript"


feature "Some JavaScript Stuff" do
  scenario "load homepage" do
    visit "/"
    expect(page).to have_content "some content enabled by javascript"

By default, Capybara uses selenium as its JavaScript driver when defining tests with :js => true or @javascript. This means the test above will use the selenium web-driver without any further configuration. To override the default driver to use Poltergeist, set the following value in your spec helper or wherever you configure your tests:

Capybara.javascript_driver = :poltergeist

With this setting, any tests that are specified to be run with JavaScript enabled will use Poltergeist as the web-driver.


Writing acceptance tests is a crucial part of the development process. Modern web applications often require the loading and manipulation of elements into a DOM, so enabling a full DOM environment when running your acceptance tests is critical to catching potential user facing bugs before they hit production. Using a headless browser like PhantomJS enables us to test end-to-end features without bogging down our testing pipeline with extraneous dependencies.

Never miss an update!

Subscribe to our RSS feed