Capybara cheatsheet

Form Navigation/Interaction

  • Navigating
  • Clicking links and buttons
    click_link('Link Text')
    # Click either a link or a button
    click('Link Text')
    click('Button Value')
  • Click the first link with the name of ‘Show’
    click_link('Show', match: :first) # or
    first(:link, 'Show')
  • Click the first button with the name of ‘Update’
    click_button('Update', match: :first) # or
    first(:button, 'Update')
  • Interacting with forms
    fill_in('First Name', :with => 'John')
    fill_in('Password', :with => 'Seekrit')
    fill_in('Description', :with => 'Really Long Text…')
    choose('A Radio Button')
    check('A Checkbox')
    uncheck('A Checkbox')
    attach_file('Image', '/path/to/image.jpg')
    select('Option', :from => 'Select Box')
    # Find disabled fields with
    find_field 'This is disabled', disabled: true
  • Scripting
    result = page.evaluate_script('4 + 4');
  • Debugging

Capybara Finders




find_field('First Name').value




page.all(:xpath, '//a')

page.first(:xpath, '//a')


page.find(:xpath, "//input[@id='form_pets_dog']")['checked']
# => true

page.find(:css, '#with_focus_event').trigger(:focus)


# => 'blah'

# => 'a'

# finds invisible elements when false
page.find_by_id("hidden_via_ancestor", visible: false)

page.find_button('What an Awesome')[:value]
# => 'awesome'

# => 'labore'

# => '/some_uri'

Note: find 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.

Note: In XPath the expression // means something very specific, and it might not be what you think. Contrary to common belief, // means “anywhere in the document” not “anywhere in the current context”.

Attributes for find or All

Options Hash (options):

text (String, Regexp)  Only find elements which contain this text or match this regexp

:all - same as false; finds visible and invisible elements.
:hidden - only finds invisible elements.
:visible - same as true; only finds visible elements.

function visible (Boolean, Symbol)  Only find elements with the specified visibility:
          true - only finds visible elements.
          false - finds invisible and visible elements.

count (Integer)  Exact number of matches that are expected to be found
maximum (Integer)  Maximum number of matches that are expected to be found
minimum (Integer)  Minimum number of matches that are expected to be found
between (Range)  Number of matches found must be within the given range
exact (Boolean)  Control whether `is` expressions in the given XPath match exactly or partially
wait (Integer)  default: Capybara.default_max_wait_time  The time to wait for element count expectations to become true

find("#btn_login", :visible => true).click # search only the visible element.
find("#btn_login", :visible => false).click # Search only the invisible element.
find("#btn_login", :hidden => true).click # Serch for the hidden element.
find("#btn_login", :all => true).click # Search for both visible or hidden elements.
find("#btn_login", :wait => 10).click # Changes the internal timeout - in seconds.

Capybara Scoped Finder within

within('.search_form') do
  fill_in 'Name', with: 'iOS 7'
  click_button 'Search'
within("//li[@id='employee']") do
   fill_in 'Name', :with => 'Jimmy'
within(:css, "li#employee") do
  fill_in 'Name', :with => 'Jimmy'
within_fieldset('Employee') do
  fill_in 'Name', :with => 'Jimmy'
within_table('Employee') do
  fill_in 'Name', :with => 'Jimmy'
# Execute the given block within the given iframe using given frame name or index.
within_frame('some_frame') do

Capybara Matchers

expect(page).to have_content("Some Content")
expect(page).to have_no_content("Some Content")

# True if the current path matches the browsing session
expect(page).to have_current_path( "Some path" )

# True if there is a anchor tag with text matching regex
expect(page).to have_xpath("//a")
expect(page).to have_xpath("//a",:href => "")
expect(page).to have_xpath("//a[@href => '']")
expect(page).to have_xpath("//a[contains(.,'some string')]")
expect(page).to have_xpath("//p//a", :text => /re[dab]i/i, :count => 1)

 # can take both xpath and css as input and can take arguments similar to both have_css and have_xpath
 expect(page).to have_selector(:xpath, "//p/h1")
 expect(page).to have_selector(:css, "p a#post_edit_path")

 expect(page).to have_css("input#post_title")
 expect(page).to have_css("input#post_title", :value => "Capybara cheatsheet")

 # True if there are 3 input tags in response
 expect(page).to have_css("input", :count => 3)

 # True if there or fewer or equal to 3 input tags
 expect(page).to have_css("input", :maximum => 3)

 # True if there are minimum of 3 input tags
 expect(page).to have_css("input", :minimum => 3)

 # True if there 1 to 3 input tags
 expect(page).to have_css("input", :between => 1..3)

 # True if there is a anchor tag with text hello
 expect(page).to have_css("p a", :text => "hello")
 expect(page).to have_css("p a", :text => /[hH]ello(.+)/i)

# For making capybara to take css as default selector
Capybara.default_selector = :css

# checks for the presence of the input tag
expect(page).to have_selector("input")

# checks for input tag with value
expect(page).to have_selector("input", :value =>"Post Title")

expect(page).to have_no_selector("input")

# For making capybara to take css as default selector
Capybara.default_selector = :xpath
# checks for the presence of the input tag
expect(page).to have_selector("//input")

# checks for input tag with value
expect(page).to have_selector("//input", :value =>"Post Title")

# checks for presence of a input field named FirstName in a form
expect(page).to have_field("FirstName")

expect(page).to have_field("FirstName", :value => "Rambo")
expect(page).to have_field("FirstName", :with => "Rambo")

expect(page).to have_link("Foo")
expect(page).to have_link("Foo", :href=>"")
expect(page).to have_no_link("Foo", :href=>"")

Asynchronous JavaScript

page.should have_content('baz')
page.should_not have_xpath('//a')
page.should have_no_xpath('//a')
  • =XPath and CSS=
    within(:css, 'ul li') {  }
    find(:css, 'ul li').text
    locate(:css, 'input#name').value
    Capybara.default_selector = :css
    within('ul li') {  }
    find('ul li').text
  • Accept alert
  • Find meta tag
    page.find("meta[name='keywords']", visible: false)
    page.find("meta[name='description']", visible: false)
  • Close previous opened window
    within_window(page.driver.browser.window_handles.first) do
  • Set hidden input value