DOCSEARCHbyAlgolia
Submit Docs

Capybara Documentation

repository·master·Indexed 27 days ago

https://github.com/teamcapybara/capybara

A driver-agnostic web application testing framework for Ruby 3.0.0+ that simulates real user interactions. It provides a high-level DSL for navigating pages, interacting with forms, and querying web content, with out-of-the-box support for Rack::Test and Selenium. Capybara integrates with popular testing frameworks including RSpec, Cucumber, Minitest, and Test::Unit, and offers specialized configurations for Rails applications.

Tokens
10.1K
Snippets
34
Records
68
Agent score
45%

What's inside Capybara

  2. Test against remote servers

    master

    While Capybara typically tests in-process Rack applications, you can test against remote web servers by setting Capybara.app_host.

    Important Notes:

    • The default driver (:rack_test) does not support remote servers.
    • Use drivers like :selenium for remote testing.
    • To prevent Capybara from attempting to boot its own Rack server when testing a remote app, set Capybara.run_server = false.
    Capybara.current_driver = :selenium
Capybara.app_host = 'http://www.google.com'
...
visit('/')

  5. Manage multiple sessions

    master

    Capybara manages named sessions (defaulting to :default). You can use multiple sessions to interact with different browser instances simultaneously.

    • Temporary switch: Use Capybara.using_session("name") to perform actions in a different session and automatically revert to the previous one when the block ends.
    • Permanent switch: Use Capybara.session_name = "name" to change the current session globally for the thread.
    • Manual instantiation: For full control, instantiate Capybara::Session.new(driver, app) directly.
    # Temporary switch
Capybara.using_session("Bob's session") do
   # do something in Bob's browser session
end

# Permanent switch
Capybara.session_name = "some other session"

# Manual instantiation
require 'capybara'
session = Capybara::Session.new(:webkit, my_rack_app)
session.within("form#session") do
  session.fill_in 'Email', with: 'user@example.com'
  session.fill_in 'Password', with: 'password'
end
session.click_button 'Sign in'

  6. Debug tests with snapshots and screenshots

    master

    When debugging, you can inspect the page state using several methods:

    • save_and_open_page: Opens the current page in a browser.
    • page.html: Returns the current DOM as a string.
    • page.save_screenshot('path.png'): Saves a screenshot to the specified path.
    • save_and_open_screenshot: Saves a screenshot and opens it automatically.

    Note: Screenshots are saved to Capybara.save_path. If using capybara/rails, this defaults to tmp/capybara.

  9. Handle Asynchronous Elements Correctly

    master

    When testing for the absence of an element that is being removed via Ajax, do not use negation on a predicate (e.g., !page.has_xpath?('a')). Capybara does not wait for successful predicates, so it will return true immediately if the element is still there, causing the negation to be false incorrectly.

    Instead, use the negative predicate methods which are designed to wait for the element to disappear:

    • Use page.has_no_xpath?('a') instead of !page.has_xpath?('a').
    • In RSpec, expect(page).not_to have_xpath('a') and expect(page).to have_no_xpath('a') are functionally equivalent and both handle waiting correctly.

  10. Use Capybara with Cucumber

    master

    The cucumber-rails gem includes Capybara support. For non-Rails projects, manually load capybara/cucumber and assign your app to Capybara.app.

    You can use the Capybara DSL directly in your steps. To switch to the JavaScript driver (defaulting to :selenium), tag scenarios or features with @javascript. You can also use explicit tags for other registered drivers like @selenium or @rack_test.

    require 'capybara/cucumber'
Capybara.app = MyRackApp

# Example step definition
When /I sign in/ do
  within("#session") do
    fill_in 'Email', with: 'user@example.com'
    fill_in 'Password', with: 'password'
  end
  click_button 'Sign in'
end

  11. Use XPath and CSS selectors

    master

    Capybara uses CSS selectors by default. To use XPath, you must specify the selector type explicitly or change the global default.

    XPath Best Practice: When using XPath within a scoped element (like within or after a find), use the .// prefix instead of //. The // prefix searches the entire document, whereas .// searches only descendants of the current node.

    # Explicit XPath usage
within(:xpath, './/ul/li') { ... }
find(:xpath, './/ul/li').text

# Setting XPath as default
Capybara.default_selector = :xpath
find('.//ul/li').text

# The XPath // trap: use .// for descendants
page.find(:xpath, '//body').all(:xpath, './/script')