View source for Capybara (software)

{{Short description|Ruby library for software testing}}
{{other uses|Capybara (disambiguation)}}
{{Infobox software
|  name = Capybara
|  logo = 
|  screenshot = 
|  caption = 
|  developer =Thomas Walpole
|  programming language = [[Ruby (programming language)|Ruby]]
|  genre = [[Behavior driven development]] [[framework (computer science)|framework]] / [[Test tool]]
|  license = [[MIT License]]
|  website = {{URL|https://teamcapybara.github.io/capybara/}}
| latest release version = {{wikidata|property|edit|reference|P348}}
| latest release date    = {{start date and age|{{wikidata|qualifier|P348|P577}}}}
|  operating_system = [[Cross-platform]]
}}
'''Capybara''' is a web-based [[test automation]] software that simulates scenarios for [[user stories]] and automates [[web application]] testing for [[Behavior-driven development|behavior-driven]] software development.  It is written in the [[Ruby (programming language)|Ruby programming language]].

Capybara can mimic actions of real users interacting with web-based applications. It can receive pages, parse the [[HTML]] and submit [[Form (HTML)|forms]].<ref name=":1">{{Cite book|title = Engineering Software as a Service: An Agile Approach Using Cloud Computing|isbn = 9780984881246 | last1=Fox | first1=Armando | last2=Patterson | first2=David A. | date=2013 | publisher=Strawberry Canyon LLC }}</ref>

== Background and motivation ==
During the software development process (especially in the [[Agile software development|Agile]] and [[Test-driven development|Test-driven Development]] environments), as the size of the tests increase, it becomes difficult to manage tests which are complex and not modular.<ref name=":1" />

By extending the human-readable [[behavior-driven development]] style of frameworks such as [[Cucumber (software)|Cucumber]]  and [[RSpec]] into the automation code itself, Capybara aims to develop simple web-based automated tests.<ref>{{Cite book|title = Application Testing with Capybara|isbn = 9781783281268}}</ref>

== Anatomy of Capybara ==
Capybara is a Ruby library (also referred to as a [[RubyGems|gem]]) that is used with an underlying web-based driver. It consists of a user-friendly [[Domain-specific language|DSL]] (Domain Specific Language) which describe actions that are executed by the underlying web driver.<ref name=":2">{{Cite web|title = The Basics of Capybara and Improving Your Tests|url = http://www.sitepoint.com/basics-capybara-improving-tests/|website = SitePoint| date=18 August 2014 |access-date = 2016-02-08|language = en-US}}</ref>

When the page is loaded using the DSL (and underlying web driver), Capybara will attempt to locate the relevant element in the [[Document Object Model|DOM]] (Document Object Model) and execute an action such as click button, link, etc.

=== Drivers ===
By default, Capybara uses the <code>:rack_test</code> driver which does not have any support for executing [[JavaScript]]. Drivers can be switched in Before and After blocks. Some of the web drivers supported by Capybara are mentioned below.

==== RackTest ====
Written in Ruby, Capybara's default driver RackTest does not require a server to be started since it directly interacts with [[Rack (web server interface)|Rack]] interfaces. Consequently, it can only be used for Rack applications.

==== Selenium ====
[[Selenium (software)|Selenium]]-webdriver, which is mostly used in web-based automation frameworks, is supported by Capybara. Unlike Capybara's default driver, it supports JavaScript, can access HTTP resources outside of application and can also be set up for testing in headless mode which is especially useful for CI scenarios.<ref name=":2" />

==== Capybara-webkit ====
Capybara-webkit driver (a gem) is used for true [[headless browser]] testing with JavaScript support. It uses [[QtWebKit]] and it is significantly faster than Selenium as it does not load the entire browser.

== Matchers  ==
Capybara locates an element either using [[Domain-specific language]] or [[XPath]]/[[Cascading Style Sheets|CSS Selectors]]. Partial matches can lead to unexpected results. Two or more matches can even result in a failure with an Ambiguous match error. The following are the matching strategies supported by Capybara:<ref name=":2" />

'''first:''' Pick the first element which matches. Not advisable to use.

'''one:''' Allow only one element match. Error raised if more than one match.

'''smart:''' If Capybara.exact is true, it behaves like the above option ('''one'''). If Capybara.exact is false, it will first try to find an exact match. Ambiguous exception is raised if more than one match is found. If no element is found, a new search for inexact matches is commenced. Again, an ambiguous exception is raised if more than one match is found.

'''prefer_exact:''' Finds all matching (exact and which are not exact) elements. If multiple matches are found then the first exactly matching element is returned discarding other matches.

== Usage ==

=== User-registration process ===
Here is an example of how user registration test is done using Capybara. There is a test to see if the user can continue with the registration process or if there are any holds on him. If he has the requisite credentials, he will be registered and then redirected to the 'Welcome' page.<ref>{{Cite web|title = Integration testing Devise with RSpec and Capybara|url = http://garyrafferty.com/2011/09/29/Testing-devise-with-rspec-and-capybara.html|website = garyrafferty.com|access-date = 2016-02-16|archive-url = https://web.archive.org/web/20160121204404/http://garyrafferty.com/2011/09/29/Testing-devise-with-rspec-and-capybara.html|archive-date = 2016-01-21|url-status = dead}}</ref><syntaxhighlight lang="ruby">
  describe 'UserRegistration' do
    it 'allows a user to register' do
      visit new_user_registration_path
      fill_in 'First name', :with => 'New'
      fill_in 'Last name', :with => 'User'
      fill_in 'Email', :with => 'newuser@example.com'
      fill_in 'Password', :with => 'userpassword'
      fill_in 'Password Confirmation', :with => 'userpassword'
      click_button 'Register'
      page.should have_content 'Welcome'
    end
  end
</syntaxhighlight>

=== Capybara with Cucumber ===
An example of a Capybara feature used with Cucumber:<syntaxhighlight lang="ruby">
When /^I want to add/ do
    fill_in 'a', :with => 100
    fill_in 'b', :with => 100
    click_button 'Add'
end
</syntaxhighlight>

===Capybara with RSpec===

Some minute integration is required in order to use Capybara with [[RSpec]]<ref name=":2" /><ref>{{Cite web|title = Capybara (and Selenium) with RSpec & Rails 3: quick tutorial|url = http://www.opinionatedprogrammer.com/2011/02/capybara-and-selenium-with-rspec-and-rails-3/|website = www.opinionatedprogrammer.com|access-date = 2016-02-08|first = Jo|last = Liss}}</ref>

<syntaxhighlight lang="ruby">
describe 'go to home page' do
  it 'opens the home page' do
    visit (get_homepage)
    expect(page).to have_content('Welcome')
  end
end
</syntaxhighlight>

== Similar tools ==
* [[Watir]]
* [[Selenium (software)]]

==See also==
{{Portal|Free and open-source software}}
* [[Acceptance testing]]
* [[Acceptance test-driven development]]
* [[Behavior-driven development]]
* [[Test automation]]
* [[HtmlUnit]]
* [[List of web testing tools]]
* [[Regression testing]]
* [[Given-When-Then]]

== References ==
<references />

[[Category:Software testing tools]]
[[Category:Software using the MIT license]]
[[Category:Graphical user interface testing]]
[[Category:Load testing tools]]
[[Category:Unit testing frameworks]]
[[Category:Web development software]]
[[Category:Web scraping]]
[[Category:Free software programmed in Ruby]]