Integration Testing with Capybara
JavaScript Testing with Selenium & Capybara-Webkit
By default Capybara uses Rack::Test
which is a headless browser emulator. It gives us great speed, but we sacrifice the ability to run JavaScript. If you need to test JS as part of your integration suite, then you need to use another driver.
Linux Note
If you’re using Linux, you’ll need to set up xvfb in order to use either Selenium or Capybara-Webkit. Here are the Ubuntu commands to install xvfb and additional fonts to get rid of some warnings.
1 2 3 |
|
In order to use xvfb with your specs, you will need to run xvfb-run bundle exec rake
(an alias may be in order).
Now selunium and capybara-webkit will use xvfb when launching a browser.
There are alternative x-servers and alternative ways to use the x-server from the specs (headless gem) but they are not covered here.
Using Selenium
The most popular driver is Selenium. It uses an actual browser window and you can watch the test happen. It uses the browser’s actual JavaScript engine, so it’s identical to having a human Q/A department interacting with your application.
Setup?
If you have Firefox 4 installed then there are no extra setup steps. It’s possible to use Chrome or another WebKit-based browser, but it is more work.
Modifying Your Examples
If you want to only use the browser for a few specific tests, you can add js: true
into the it
line like this:
1 2 3 4 5 |
|
More commonly you’ll have a group of tests that you want to run in the browser. Rather than litter js: true
all over the place, do this:
- Create a
describe
block that contains the examples that need JavaScript - Add a before-all block like this:
1 2 3 |
|
- Put your examples after the
before
block - Add an after-all block like this:
1 2 3 |
|
Now any example added inside that describe
will use Selenium. If you forget the after(:all)
block, all subsequent tests will continue using the :selenium
driver, which will work, albeit more slowly than with the default, headless driver.
Selenium Methods
If you’re just triggering AJAX actions via JavaScript you can probably get by with the normal Capybara actions. But Selenium itself has many actions that are not directly supported by Capybara.
But that’s ok! If you ask Capybara for page.driver.browser
while in a Selenium-powered test, it’ll give you the Selenium::WebDriver::Driver
object. You can then access any Selenium method according to the API here: http://selenium.googlecode.com/svn/trunk/docs/api/rb/Selenium/WebDriver/Driver.html
Checking for an Alert
Here’s a complete example of how you could use Selenium to check that an alert pops up when we attempt to delete an article:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
You could also use dialog.accept
to click the OK
button where dialog.dismiss
clicks CANCEL
.
Selenium Alternatives
Selenium, for one reason or another, makes developers a little uneasy. It sometimes has issues in the development versions but, most importantly, it’s slow. It would be awesome if we could run JavaScript without actually waiting for the slow rendering of a GUI window.
There are some attempts to make this work, libraries such as HTML::Unit and Akephalos. They do a good job, but their JavaScript engines aren’t a perfect match for a real browser. If only there were a real browser that we could run without the GUI!
Using WebKit
The WebKit framework powers Chrome, Safari, and most mobile phone browsers. It’s a popular open source project and is really at the vanguard of web browsers.
The team at ThoughtBot, a Rails consultancy in Boston, put together the capybara-webkit
gem: https://github.com/thoughtbot/capybara-webkit
It uses the WebKit framework as a headless browser. We get almost all the speed of being headless with Rack::Test
, but the power of a full, real-world JavaScript interpreter.
Setup Qt
capybara-webkit
uses the QtWebKit port, which depends on the Qt windowing framework. Even though the whole point is to run WebKit without windows, the compilation process has dependencies on Qt.
Because Qt is not available for Windows, it’s not possible to build WebKit for use with Capybara-Webkit on Windows. You’ll need OS X or Linux.
OS X users can download and install the non-debug Qt from Nokia here: http://qt.nokia.com/downloads/qt-for-open-source-cpp-development-on-mac-os-x
Ubuntu users can sudo apt-get install libqt4-dev
, while other Linux distributions can build it from Nokia’s source code: http://qt.nokia.com/downloads/linux-x11-cpp
Add the Gem
Open your Gemfile
and add the following in your development dependencies:
1
|
|
At the time of this writing, it was necessary to use the 1.0 branch of capybara-webkit like this:
1
|
|
Tell Capybara about Capybara-Webkit
Then you’d hop into your spec/spec_helper.rb
and add this line inside the RSpec.configure
block:
1
|
|
Run Your Examples
Now all you do is run your examples! We just swapped the driver, but the way we tell Capybara to use it is exactly the same as Selenium. If you want to run a single test with WebKit, add js: true
to the it
line.
If you have a set of examples to run with JavaScript, wrap them in a describe
block with a before-all and after-all like this:
1 2 3 4 5 6 7 8 9 10 11 |
|
You’ll practice using the JavaScript-enabled drivers in the exercises in the next section.