Enjoy this cheat sheet at its fullest within Dash, the macOS documentation browser.


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('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.


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

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


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


find('article a.title').click

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



Allows triggering of custom events. Works with JavaScript drivers.



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 'Male'

Chooses a radio button. Pass the label text.


check 'I accept the terms of the site'

Checks a checkbox. Pass the label text.


uncheck 'Admin access?'

Unchecks a checkbox. Pass the label text.


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']


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 a screenshot of the current page and open in the default image viewer.


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.