What Is Capybara?
Note: if you are from the far future (meaning about 17 minutes after this post was published) the information in this post may be out of date since it is about bleeding edge versions of Capybara and Rails 3 (Capybara 0.3.7 and Rails 3.0.0.beta3).
Installing Capybara in Rails 3
Add the capybara and launchy gems to the test section of your Gemfile:
group :test do gem "capybara" gem "launchy" end
You need the launchy gem or Capybara’s
save_and_open_page method won’t work. Don’t forget to run
bundle install to install these gems.
Next, create the file
test/integration_test_helper.rb containing this:
require "test_helper" require "capybara/rails" module ActionController class IntegrationTest include Capybara::DSL end end
For old versions of Capybara (before 1.0), replace
include Capybara::DSL with
It’s not strictly necessary to have a separate
integration_test_helper.rb file, but it helps to organize your code. This is where I keep code that I want loaded by all of my integration tests but not other types of tests. The
require "capybara/rails" line loads Capybara and automatically hooks it up to Rails. After this, I explicitly mix the Capybara module into Rails’ IntegrationTest class. Otherwise, you would get errors like this:
NoMethodError: undefined method `visit' for #<YourIntegrationTest:0x2ce93c8>
Now you’re ready to create an integration test. Note that you need to
require 'integration_test_helper' at the beginning of all of your integration tests.
require 'integration_test_helper' class ClubTest < ActionController::IntegrationTest test "viewing clubs" do visit '/clubs' assert page.has_content?('Listing clubs') end end
You should be all set!
rake test:integration will run your integration tests.
Capybara has a clear DSL that should be very familiar to Webrat users. Here is an example of a basic integration test written using Capybara:
require 'integration_test_helper' class ClubTest < ActionController::IntegrationTest test "viewing clubs" do visit '/clubs' assert page.has_content?('Listing clubs') end test "adding a club" do visit '/clubs' click_link "New Club" assert page.has_content?('Create a new club') fill_in 'Name', :with => 'Capybara' check 'Exclusive' click_button 'Create Club' assert page.has_content?('Club was successfully created.') click_link "Back" assert page.has_content?('Listing clubs') assert page.has_content?('Capybara true') assert page.has_no_content?('Capybara false') end end
As you can see, we can easily navigate to a page, click links, fill out forms, submit forms, and check the contents of web pages for items. Some tips:
- Be careful; the text is case-sensitive.
assert page.has_content?('Listing clubs')will not match Listing Clubs.
- If you are an RSpec fan, Capybara allows you to write
save_and_open_pageis a nifty way to see exactly what your web page looks like at a certain point. Just insert it anywhere in the test. It’s great for debugging:
require 'integration_test_helper' class ClubTest < ActionController::IntegrationTest test "viewing clubs" do visit '/clubs' save_and_open_page assert page.has_content?('Listing clubs') end end
- If you use
save_and_open_page, you might want to stick
.gitignorefile since this method generates html files.
For more details, see the official Capybara documentation.