Capybara is a library that can be used with cucumber to write tests that also need javascript support.

From capybara project page on github:

Capybara aims to simplify the process of integration testing Rack applications, such as Rails, Sinatra or Merb. It is inspired by and aims to replace Webrat as a DSL for interacting with a webapplication. It is agnostic about the driver running your tests and currently comes bundled with rack-test, Culerity, Celerity and Selenium support built in.

*Note: most of the information found here comes from capybara project page on github.


After having an existing rails project (How to start a rails project), you just need to install the gem:

sudo gem install capybara

On OSX you may have to install libffi, you can install it via MacPorts with:

sudo port install libffi

After installing the libraries you'll need to run the cucumber generator again with an additional —capybara argument:

ruby script/generate cucumber --capybara

If you find yourself with some failing tests, it might be because capybara searches elements using case-sensitive queries. So searching for an element with content "hello" won't yield the same results as searching for "Hello".


Capybara developers tried to make it so the transition from webrat (which comes with cucumber by default) to capybara would be as soft and easy as possible. This means that most of the default step definitions used can still be used (however some of them will be overwritten by the generator, so be careful if you like to edit default code ;) ).

Running Scenarios with Javascript support

In order to run a scenario that needs support for javascript, you just need to include a special *@javascript* tag before the scenario:

  Scenario: A user goes to the posts page and leaves a comment using the ajax form
    Given I am on the post page
    When I fill in "Comment" with "Hello World"
    And click "Publish comment"
    Then I should see "Comment succesfully published"
    And I should see "Hello World"

Links and Documentation

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License