![](\"http:\/\/secure.travis-ci.org\/jnicklas\/capybara.png\")
\u00a0![](\"http:\/\/codeclimate.com\/github\/jnicklas\/capybara.png\")
<\/p>\n \u00a0<\/p>\n
Capybara helps you test web applications by simulating how a real user would interact with your app. It is agnostic about the driver running your tests and comes with Rack::Test and Selenium support built in. WebKit is supported through an external gem.<\/p>\n
Need help?<\/strong> Ask on the mailing list (please do not open an issue on GitHub): http:\/\/groups.google.com\/group\/ruby-capybara<\/p>\n Capybara requires Ruby 1.9.3 or later. To install, add this line to your If the application that you are testing is a Rails app, add this line to your test helper file:<\/p>\n Note:<\/strong> In Rails 4.0\/4.1 the default test environment ( If the application that you are testing is a Rack app, but not Rails, set Capybara.app to your Rack app:<\/p>\n If you need to test JavaScript, or if your app interacts with (or is located at) a remote URL, you\u2019ll need to use a different driver.<\/p>\n The You can use the Capybara DSL in your steps, like so:<\/p>\n You can switch to the There are also explicit Load RSpec 2.x support by adding the following line (typically to your If you are using Rails, put your Capybara specs in If you are not using Rails, tag all the example groups in which you want to use Capybara with You can now write your specs like so:<\/p>\n Use Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:<\/p>\n Remember to call To switch the driver, set Set up your base class as with Test::Unit. (On Rails, the right base class could be something other than ActionDispatch::IntegrationTest.)<\/p>\n The capybara_minitest_spec gem (GitHub, rubygems.org) provides MiniTest::Spec expectations for Capybara. For example:<\/p>\n Capybara uses the same DSL to drive a variety of browser and headless drivers.<\/p>\n By default, Capybara uses the However, if you are using RSpec or Cucumber, you may instead want to consider leaving the faster You can also change the driver temporarily (typically in the Before\/setup and After\/teardown blocks):<\/p>\n Note<\/strong>: switching the driver creates a new session, so you may not be able to switch in the middle of a test.<\/p>\n RackTest is Capybara\u2019s default driver. It is written in pure Ruby and does not have any support for executing JavaScript. Since the RackTest driver interacts directly with Rack interfaces, it does not require a server to be started. However, this means that if your application is not a Rack application (Rails, Sinatra and most other Ruby frameworks are Rack applications) then you cannot use this driver. Furthermore, you cannot use the RackTest driver to test a remote application, or to access remote URLs (e.g., redirects to external sites, external APIs, or OAuth services) that your application might interact with.<\/p>\n capybara-mechanize provides a similar driver that can access remote servers.<\/p>\n RackTest can be configured with a set of headers like this:<\/p>\n See the section on adding and configuring drivers.<\/p>\n At the moment, Capybara supports Selenium 2.0 (Webdriver), not<\/em> Selenium RC. In order to use Selenium, you\u2019ll need to install the Note<\/strong>: drivers which run the server in a different thread may not share the same transaction as your tests, causing data not to be shared between your test and test server, see \u201cTransactions and database setup\u201d below.<\/p>\n The capybara-webkit driver is for true headless testing. It uses QtWebKit to start a rendering engine process. It can execute JavaScript as well. It is significantly faster than drivers like Selenium since it does not load an entire browser.<\/p>\n You can install it with:<\/p>\n And you can use it by:<\/p>\n Poltergeist is another headless driver which integrates Capybara with PhantomJS. It is truly headless, so doesn\u2019t require Xvfb to run on your CI server. It will also detect and report any Javascript errors that happen within the page.<\/p>\n A complete reference is available at rubydoc.info<\/em>.<\/p>\n Note<\/strong>: All searches in Capybara are case sensitive<\/em>. This is because Capybara heavily uses XPath, which doesn\u2019t support case insensitivity.<\/p>\n You can use the visit method to navigate to other pages:<\/p>\n The visit method only takes a single parameter, the request method is always<\/strong> GET.<\/p>\n You can get the current path of the browsing session for test assertions:<\/p>\n Full reference: Capybara::Node::Actions<\/em><\/p>\n You can interact with the webapp by following links and buttons. Capybara automatically follows any redirects, and submits forms associated with buttons.<\/p>\n Full reference: Capybara::Node::Actions<\/em><\/p>\n There are a number of tools for interacting with form elements:<\/p>\n Full reference: Capybara::Node::Matchers<\/em><\/p>\n Capybara has a rich set of options for querying the page for the existence of certain elements, and working with and manipulating those elements.<\/p>\n Note:<\/strong> The negative forms like You can use these with RSpec\u2019s magic matchers:<\/p>\n Full reference: Capybara::Node::Finders<\/em><\/p>\n You can also find specific elements, in order to manipulate them:<\/p>\n Note<\/strong>: These elements all have all the Capybara DSL methods available, so you can restrict them to specific parts of the page:<\/p>\n Capybara makes it possible to restrict certain actions, such as interacting with forms or clicking links and buttons, to within a specific area of the page. For this purpose you can use the generic within method. Optionally you can specify which kind of selector to use.<\/p>\n There are special methods for restricting the scope to a specific fieldset, identified by either an id or the text of the fieldset\u2019s legend tag, and to a specific table, identified by either id or text of the table\u2019s caption tag.<\/p>\n Capybara provides some methods to ease finding and switching windows:<\/p>\n In drivers which support it, you can easily execute JavaScript:<\/p>\n For simple expressions, you can return the result of the script. Note that this may break with more complicated expressions:<\/p>\n In drivers which support it, you can accept, dismiss and respond to alerts, confirms and prompts.<\/p>\n You can accept or dismiss alert messages by wrapping the code that produces an alert in a block:<\/p>\n You can accept or dismiss a confirmation by wrapping it in a block, as well:<\/p>\n You can accept or dismiss prompts as well, and also provide text to fill in for the response:<\/p>\n All modal methods return the message that was presented. So, you can access the prompt message by assigning the return to a variable:<\/p>\n It can be useful to take a snapshot of the page as it currently is and take a look at it:<\/p>\n You can also retrieve the current state of the DOM as a string using page.html.<\/p>\n This is mostly useful for debugging. You should avoid testing against the contents of Finally, in drivers that support it, you can save a screenshot:<\/p>\n Or have it save and automatically open:<\/p>\n It is possible to customize how Capybara finds elements. At your disposal are two options, For example:<\/p>\n Using The default for Some Capybara drivers need to run against an actual HTTP server. Capybara takes care of this and starts one for you in the same process as your test, but on another thread. Selenium is one of those drivers, whereas RackTest is not.<\/p>\n If you are using a SQL database, it is common to run every test in a transaction, which is rolled back at the end of the test, rspec-rails does this by default out of the box for example. Since transactions are usually not shared across threads, this will cause data you have put into the database in your test code to be invisible to Capybara.<\/p>\n Cucumber handles this by using truncation instead of transactions, i.e. they empty out the entire database after each test. You can get the same behaviour by using a gem such as database_cleaner.<\/p>\n It is also possible to force your ORM to use the same transaction for all threads. This may have thread safety implications and could cause strange failures, so use caution with this approach. It can be implemented in ActiveRecord through the following monkey patch:<\/p>\n When working with asynchronous JavaScript, you might come across situations where you are attempting to interact with an element which is not yet present on the page. Capybara automatically deals with this by waiting for elements to appear on the page.<\/p>\n When issuing instructions to the DSL such as:<\/p>\n If clicking on the foo<\/em> link triggers an asynchronous process, such as an Ajax request, which, when complete will add the bar<\/em> link to the page, clicking on the bar<\/em> link would be expected to fail, since that link doesn\u2019t exist yet. However Capybara is smart enough to retry finding the link for a brief period of time before giving up and throwing an error. The same is true of the next line, which looks for the content baz<\/em> on the page; it will retry looking for that content for a brief time. You can adjust how long this period is (the default is 2 seconds):<\/p>\n Be aware that because of this behaviour, the following two statements are not<\/strong> equivalent, and you should always<\/strong> use the latter!<\/p>\n The former would immediately fail because the content has not yet been removed. Only the latter would wait for the asynchronous process to remove the content from the page.<\/p>\n Capybara\u2019s Rspec matchers, however, are smart enough to handle either form. The two following statements are functionally equivalent:<\/p>\n Capybara\u2019s waiting behaviour is quite advanced, and can deal with situations such as the following line of code:<\/p>\n Even if JavaScript causes You can mix the DSL into any context by including Capybara::DSL:<\/p>\n This enables its use in unsupported testing frameworks, and for general-purpose scripting.<\/p>\n Normally Capybara expects to be testing an in-process Rack application, but you can also use it to talk to a web server running anywhere on the internet, by setting app_host:<\/p>\n Note<\/strong>: the default driver (Table of contents<\/h2>\n
Key benefits<\/h2>\n
\n
Setup<\/h2>\n
Gemfile<\/code> and run bundle install<\/code>:<\/p>\ngem 'capybara'\n<\/code><\/pre>\nrequire 'capybara\/rails'\n<\/code><\/pre>\nconfig\/environments\/test.rb<\/code>) is not threadsafe. If you experience random errors about missing constants, add config.allow_concurrency = false<\/code> to config\/environments\/test.rb<\/code>.<\/p>\nCapybara.app = MyRackApp\n<\/code><\/pre>\nUsing Capybara with Cucumber<\/h2>\n
cucumber-rails<\/code> gem comes with Capybara support built-in. If you are not using Rails, manually load the capybara\/cucumber<\/code> module:<\/p>\nrequire 'capybara\/cucumber'\nCapybara.app = MyRackApp\n<\/code><\/pre>\nWhen \/I sign in\/ do\n within(\"#session\") do\n fill_in 'Email', :with => 'user@example.com'\n fill_in 'Password', :with => 'password'\n end\n click_button 'Sign in'\nend\n<\/code><\/pre>\nCapybara.javascript_driver<\/code> (:selenium<\/code> by default) by tagging scenarios (or features) with @javascript<\/code>:<\/p>\n@javascript\nScenario: do something Ajaxy\n When I click the Ajax link\n ...\n<\/code><\/pre>\n@selenium<\/code> and @rack_test<\/code> tags set up for you.<\/p>\nUsing Capybara with RSpec<\/h2>\n
spec_helper.rb<\/code> file):<\/p>\nrequire 'capybara\/rspec'\n<\/code><\/pre>\nspec\/features<\/code>.<\/p>\n:type => :feature<\/code>.<\/p>\ndescribe \"the signin process\", :type => :feature do\n before :each do\n User.make(:email => 'user@example.com', :password => 'password')\n end\n\n it \"signs me in\" do\n visit '\/sessions\/new'\n within(\"#session\") do\n fill_in 'Email', :with => 'user@example.com'\n fill_in 'Password', :with => 'password'\n end\n click_button 'Sign in'\n expect(page).to have_content 'Success'\n end\nend\n<\/code><\/pre>\n:js => true<\/code> to switch to the Capybara.javascript_driver<\/code> (:selenium<\/code> by default), or provide a :driver<\/code> option to switch to one specific driver. For example:<\/p>\ndescribe 'some stuff which requires js', :js => true do\n it 'will use the default js driver'\n it 'will switch to one specific driver', :driver => :webkit\nend\n<\/code><\/pre>\nfeature \"Signing in\" do\n background do\n User.make(:email => 'user@example.com', :password => 'caplin')\n end\n\n scenario \"Signing in with correct credentials\" do\n visit '\/sessions\/new'\n within(\"#session\") do\n fill_in 'Email', :with => 'user@example.com'\n fill_in 'Password', :with => 'caplin'\n end\n click_button 'Sign in'\n expect(page).to have_content 'Success'\n end\n\n given(:other_user) { User.make(:email => 'other@example.com', :password => 'rous') }\n\n scenario \"Signing in as another user\" do\n visit '\/sessions\/new'\n within(\"#session\") do\n fill_in 'Email', :with => other_user.email\n fill_in 'Password', :with => other_user.password\n end\n click_button 'Sign in'\n expect(page).to have_content 'Invalid email or password'\n end\nend\n<\/code><\/pre>\nfeature<\/code> is in fact just an alias for describe ..., :type => :feature<\/code>, background<\/code> is an alias for before<\/code>, scenario<\/code> for it<\/code>, and given<\/code>\/given!<\/code> aliases for let<\/code>\/let!<\/code>, respectively.<\/p>\nUsing Capybara with Test::Unit<\/h2>\n
\n
test_helper.rb<\/code> file to make Capybara available in all test cases deriving from ActionDispatch::IntegrationTest<\/code>:\nclass ActionDispatch::IntegrationTest\n # Make the Capybara DSL available in all integration tests\n include Capybara::DSL\nend\n<\/code><\/pre>\n<\/li>\nclass CapybaraTestCase < Test::Unit::TestCase\n include Capybara::DSL\n\n def teardown\n Capybara.reset_sessions!\n Capybara.use_default_driver\n end\nend\n<\/code><\/pre>\nsuper<\/code> in any subclasses that override teardown<\/code>.<\/li>\n<\/ul>\nCapybara.current_driver<\/code>. For instance,<\/p>\nclass BlogTest < ActionDispatch::IntegrationTest\n setup do\n Capybara.current_driver = Capybara.javascript_driver # :selenium by default\n end\n\n test 'shows blog posts' do\n # ... this test is run with Selenium ...\n end\nend\n<\/code><\/pre>\nUsing Capybara with MiniTest::Spec<\/h2>\n
page.must_have_content('Important!')\n<\/code><\/pre>\nDrivers<\/h2>\n
Selecting the Driver<\/h3>\n
:rack_test<\/code> driver, which is fast but limited: it does not support JavaScript, nor is it able to access HTTP resources outside of your Rack application, such as remote APIs and OAuth services. To get around these limitations, you can set up a different default driver for your features. For example if you\u2019d prefer to run everything in Selenium, you could do:<\/p>\nCapybara.default_driver = :selenium\n<\/code><\/pre>\n:rack_test<\/code> as the default_driver<\/strong>, and marking only those tests that require a JavaScript-capable driver using :js => true<\/code> or @javascript<\/code>, respectively. By default, JavaScript tests are run using the :selenium<\/code> driver. You can change this by setting Capybara.javascript_driver<\/code>.<\/p>\nCapybara.current_driver = :webkit # temporarily select different driver\n... tests ...\nCapybara.use_default_driver # switch back to default driver\n<\/code><\/pre>\nRackTest<\/h3>\n
Capybara.register_driver :rack_test do |app|\n Capybara::RackTest::Driver.new(app, :headers => { 'HTTP_USER_AGENT' => 'Capybara' })\nend\n<\/code><\/pre>\nSelenium<\/h3>\n
selenium-webdriver<\/code> gem, and add it to your Gemfile if you\u2019re using bundler. Provided Firefox is installed, everything is set up for you, and you should be able to start using Selenium right away.<\/p>\nCapybara-webkit<\/h3>\n
gem install capybara-webkit\n<\/code><\/pre>\nCapybara.javascript_driver = :webkit\n<\/code><\/pre>\nPoltergeist<\/h3>\n
The DSL<\/h2>\n
Navigating<\/h3>\n
visit('\/projects')\nvisit(post_comments_path(post))\n<\/code><\/pre>\nexpect(current_path).to eq(post_comments_path(post))\n<\/code><\/pre>\nClicking links and buttons<\/h3>\n
click_link('id-of-link')\nclick_link('Link Text')\nclick_button('Save')\nclick_on('Link Text') # clicks on either links or buttons\nclick_on('Button Value')\n<\/code><\/pre>\nInteracting with forms<\/h3>\n
fill_in('First Name', :with => 'John')\nfill_in('Password', :with => 'Seekrit')\nfill_in('Description', :with => 'Really Long Text...')\nchoose('A Radio Button')\ncheck('A Checkbox')\nuncheck('A Checkbox')\nattach_file('Image', '\/path\/to\/image.jpg')\nselect('Option', :from => 'Select Box')\n<\/code><\/pre>\nQuerying<\/h3>\n
page.has_selector?('table tr')\npage.has_selector?(:xpath, '\/\/table\/tr')\n\npage.has_xpath?('\/\/table\/tr')\npage.has_css?('table tr.foo')\npage.has_content?('foo')\n<\/code><\/pre>\nhas_no_selector?<\/code> are different from not has_selector?<\/code>. Read the section on asynchronous JavaScript for an explanation.<\/p>\nexpect(page).to have_selector('table tr')\nexpect(page).to have_selector(:xpath, '\/\/table\/tr')\n\nexpect(page).to have_xpath('\/\/table\/tr')\nexpect(page).to have_css('table tr.foo')\nexpect(page).to have_content('foo')\n<\/code><\/pre>\nFinding<\/h3>\n
find_field('First Name').value\nfind_link('Hello').visible?\nfind_button('Send').click\n\nfind(:xpath, \"\/\/table\/tr\").click\nfind(\"#overlay\").find(\"h1\").click\nall('a').each { |a| a[:href] }\n<\/code><\/pre>\nfind<\/code> will wait for an element to appear on the page, as explained in the Ajax section. If the element does not appear it will raise an error.<\/p>\nfind('#navigation').click_link('Home')\nexpect(find('#navigation')).to have_button('Sign out')\n<\/code><\/pre>\nScoping<\/h3>\n
within(\"li#employee\") do\n fill_in 'Name', :with => 'Jimmy'\nend\n\nwithin(:xpath, \"\/\/li[@id='employee']\") do\n fill_in 'Name', :with => 'Jimmy'\nend\n<\/code><\/pre>\nwithin_fieldset('Employee') do\n fill_in 'Name', :with => 'Jimmy'\nend\n\nwithin_table('Employee') do\n fill_in 'Name', :with => 'Jimmy'\nend\n<\/code><\/pre>\nWorking with windows<\/h3>\n
facebook_window = window_opened_by do\n click_button 'Like'\nend\nwithin_window facebook_window do\n find('#login_email').set('a@example.com')\n find('#login_password').set('qwerty')\n click_button 'Submit'\nend\n<\/code><\/pre>\nScripting<\/h3>\n
page.execute_script(\"$('body').empty()\")\n<\/code><\/pre>\nresult = page.evaluate_script('4 + 4');\n<\/code><\/pre>\nModals<\/h3>\n
accept_alert do\n click_link('Show Alert')\nend\n<\/code><\/pre>\ndismiss_confirm do\n click_link('Show Confirm')\nend\n<\/code><\/pre>\naccept_prompt(with: 'Linus Torvalds') do\n click_link('Show Prompt About Linux')\nend\n<\/code><\/pre>\nmessage = accept_prompt(with: 'Linus Torvalds') do\n click_link('Show Prompt About Linux')\nend\nexpect(message).to eq('Who is the chief architect of Linux?')\n<\/code><\/pre>\nDebugging<\/h3>\n
save_and_open_page\n<\/code><\/pre>\nprint page.html\n<\/code><\/pre>\npage.html<\/code> and use the more expressive finder methods instead.<\/p>\npage.save_screenshot('screenshot.png')\n<\/code><\/pre>\nsave_and_open_screenshot\n<\/code><\/pre>\nMatching<\/h2>\n
Capybara.exact<\/code> and Capybara.match<\/code>.<\/p>\nExactness<\/h3>\n
Capybara.exact<\/code> and the exact<\/code> option work together with the is<\/code> expression inside the XPath gem. When exact<\/code> is true, all is<\/code> expressions match exactly, when it is false, they allow substring matches. Many of the selectors built into Capybara use the is<\/code> expression. This way you can specify whether you want to allow substring matches or not. Capybara.exact<\/code> is false by default.<\/p>\nclick_link(\"Password\") # also matches \"Password confirmation\"\nCapybara.exact = true\nclick_link(\"Password\") # does not match \"Password confirmation\"\nclick_link(\"Password\", exact: false) # can be overridden\n<\/code><\/pre>\nStrategy<\/h3>\n
Capybara.match<\/code> and the equivalent match<\/code> option, you can control how Capybara behaves when multiple elements all match a query. There are currently four different strategies built into Capybara:<\/p>\n\n
exact<\/code> is true<\/code>, raises an error if more than one element matches, just like one<\/code>. If exact<\/code> is false<\/code>, it will first try to find an exact match. An error is raised if more than one element is found. If no element is found, a new search is performed which allows partial matches. If that search returns multiple matches, an error is raised.<\/li>\nCapybara.match<\/code> is :smart<\/code>. To emulate the behaviour in Capybara 2.0.x, set Capybara.match<\/code> to :one<\/code>. To emulate the behaviour in Capybara 1.x, set Capybara.match<\/code> to :prefer_exact<\/code>.<\/p>\nTransactions and database setup<\/h2>\n
class ActiveRecord::Base\n mattr_accessor :shared_connection\n @@shared_connection = nil\n\n def self.connection\n @@shared_connection || retrieve_connection\n end\nend\nActiveRecord::Base.shared_connection = ActiveRecord::Base.connection\n<\/code><\/pre>\nAsynchronous JavaScript (Ajax and friends)<\/h2>\n
click_link('foo')\nclick_link('bar')\nexpect(page).to have_content('baz')\n<\/code><\/pre>\nCapybara.default_max_wait_time = 5\n<\/code><\/pre>\n!page.has_xpath?('a')\npage.has_no_xpath?('a')\n<\/code><\/pre>\nexpect(page).not_to have_xpath('a')\nexpect(page).to have_no_xpath('a')\n<\/code><\/pre>\nexpect(find('#sidebar').find('h1')).to have_content('Something')\n<\/code><\/pre>\n#sidebar<\/code> to disappear off the page, Capybara will automatically reload it and any elements it contains. So if an AJAX request causes the contents of #sidebar<\/code> to change, which would update the text of the h1<\/code> to \u201cSomething\u201d, and this happened, this test would pass. If you do not want this behaviour, you can set Capybara.automatic_reload<\/code> to false<\/code>.<\/p>\nUsing the DSL elsewhere<\/h2>\n
require 'capybara'\nrequire 'capybara\/dsl'\n\nCapybara.default_driver = :webkit\n\nmodule MyModule\n include Capybara::DSL\n\n def login!\n within(\"\/\/form[@id='session']\") do\n fill_in 'Email', :with => 'user@example.com'\n fill_in 'Password', :with => 'password'\n end\n click_button 'Sign in'\n end\nend\n<\/code><\/pre>\nCalling remote servers<\/h2>\n
Capybara.current_driver = :selenium\nCapybara.app_host = 'http:\/\/www.google.com'\n...\nvisit('\/')\n<\/code><\/pre>\n:rack_test<\/code>) does not support running against a remote server. With drivers that support it, you can also visit any URL directly:<\/p>\n