Capybara

Navigation

Visit a path

visit '/blog'

Navigates to a particular path. Pass a string or uses one of Rails path helpers.

Click on

click_on 'Sign in'

Clicks an anchor tag, button, or input with type submit. Pass a string containing the anchor text.

Page Interaction and Scoping

Has CSS?

page.has_css?('nav[data-role=\"primary-navigation\"] li',text: 'FAQ')

Returns a boolean value reporting whether a specific selector is present on this page.

Within

within('footer'){expect(page).to have_content('Copyright')}

Will scope interaction to within a particular selector. Useful if you're looking for content in a particular area.

Has content?

page.has_content?('Sign in')

Returns a boolean value reporting whether specific content is present on the page.

Find

page.find('.todos li:first-child')

Returns a single Capybara::Node::Element instance from the page.

All

page.all('.todos li:nth-of_type(odd)')

Returns an array of Capybara::Node::Element instance from the page.

Page Assertions

Have CSS

expect(page).to have_css('header')
expect(page).to have_css('table#records + .pagination a[rel="next"')

Asserts that a certain selector is present on the page.

Have content

expect(page).to have_content('What are you looking for?')

Asserts that certain text is present on the page.

Current URL path comparison

expect(page).to have_current_path(prefix_path)

Node Interactions

Click

find('article a.title').click

Triggers a click on a Capybara::Element. Works with JavaScript drivers.

Trigger

find('input[name="post[title]"]').trigger('focus')

Allows triggering of custom events. Works with JavaScript drivers.

Visible?

find('.navigation').visible?

Returns a boolean value reporting if the Capybara::Element is visible.

Form Interactions

Fill in

fill_in 'Title', with: 'I love Rails!'
fill_in 'post[title]', with: 'I love Rails!'

Fills in fields for you. Pass the label text or the name of the input.

Choose

choose 'Male'

Chooses a radio button. Pass the label text.

Check

check 'I accept the terms of the site'

Checks a checkbox. Pass the label text.

Uncheck

uncheck 'Admin access?'

Unchecks a checkbox. Pass the label text.

Select

select 'MA', from: 'State'

Selects an option from a select tag.

Attach file

attach_file 'Image', 'path/to/image.jpg'

Attaches a file.

Click button

click_button 'Create My Account'

Will press a button or input[type='submit']

Debugging

Save and open page

save_and_open_page

Will save the current page (typically to Rails.root/tmp) and attemps to open the HTML in the default web browser.

Save and open screenshot

save_and_open_screenshot

Save a screenshot of the current page and open in the default image viewer.

Waiting...

Capybara automatically waits for asynchronous operations to complete. When you try to find an element that isn't on the page, it waits and retries until it is there, or a timeout duration elapses. The wait time is defined at Capybara.default_max_wait_time.

Methods that wait

  • find(selector), find_field, find_link
  • within(selector)(scoping)
  • has_selector?, has_no_selector? & assertions
  • form & link actions
    • click_link, click_button
    • fill_in
    • check/uncheck, select, choose

Methods that don't wait

  • visit
  • current_path
  • all(selector)
  • first(selector)
  • execute_script
  • simple accessors: text, value, title, etc.

Notes