Updated

A comprenhesive cheat sheet for our lovely capybara!

Navigating

visit(books_path)
visit('/books')
visit('http://google.com')
# Navigate to the given URL. The URL can either be a relative URL or an absolute URL 
# The behaviour of either depends on the driver.

Links & Buttons

click_link_or_button
click_on
# Finds a button or link by id, text or value and clicks it. Also looks at image alt text inside the link.

click_button
# Finds a button by id, text or value and clicks it.

click_link
# Finds a link by id or text and clicks it. Also looks at image alt text inside the link.

find_button
find_link 
has_link? 
has_no_link?
has_button?

Forms

page.attach_file(locator, '/path/to/file.png')
# Find a file field on the page and attach a file given its path. The file field can be found via 
# its name, id or label text.

page.choose('Male')
# Find a radio button and mark it as checked. The radio button can be found via name, id or label text.

field_labeled

page.fill_in 'Name', :with => 'Bob' 
# Locate a text field or text area and fill it in with the given text The field can be found via its name,
# id or label text.

page.select 'March', :from => 'Month'
# Find a select box on the page and select a particular option from it. 
# If the select box is a multiple select, select can be called multiple times 
# to select more than one option. The select box can be found via its name, id or label text.

page.unselect 'March', :from => 'Month' 
# Find a select box on the page and unselect a particular option from it. 
# If the select box is a multiple select, unselect can be called multiple times 
# to unselect more than one option. The select box can be found via its name, id or label text.

page.check('Greek')
# Find a check box and mark it as checked. The check box can be found via name, id or label text.

page.uncheck('Greek') 
# Find a check box and mark uncheck it. The check box can be found via name, id or label text.

Scoping

# within* http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session:within
within(:xpath, '//div[@id="delivery-address"]') do
  fill_in('Street', :with => '12 Main Street')
end
within('div#delivery-address') do
  fill_in('Street', :with => '12 Main Street')
end
# Executes the given block within the context of a node.

within_fieldset(locator)
# Execute the given block within the a specific fieldset given the id or legend of that fieldset.

within_frame(frame_handle)
# Execute the given block within the given iframe using given frame name or index. 
# May be supported by not all drivers. Drivers that support it, may provide additional options.

within_table(locator)
# Execute the given block within the a specific table given the id or caption of that table.

within_window(handle, &blk)
# Execute the given block within the given window.
Execute the given block within the given window. Only works on some drivers (e.g. Selenium)

Querying

# lib/capybara/session.rb http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Finders
page.all(:css, 'a#person_123')
page.all(:xpath, '//a[@id="person_123"]')
# Find all elements on the page matching the given selector and options.
# If the type of selector is left out, Capybara uses Capybara.default_selector. It's set to :css 
# by default.

page.find('#foo').find('.bar')
page.find(:xpath, '//div[contains(., "bar")]')
page.find('li', :text => 'Quox').click_link('Delete')
# Find an Element based on the given arguments. find will raise an error if the element is not found.
# If the driver is capable of executing JavaScript, find will wait for a set amount of time and 
# continuously retry finding the element until either the element is found or the time expires. 
# The length of time find will wait is controlled through Capybara.default_wait_time and defaults to 2
# seconds.

page.find_button()
# Find a button on the page.

page.find_by_id()
# Find a element on the page, given its id.

page.find_field()
# Find a form field on the page.

page.find_link()
# Find a link on the page.

page.first('my button') 
# Find the first element on the page matching the given selector and options, or nil if no element matches.

has_content?
has_css?
has_no_content?
has_no_css?
has_no_xpath?
has_xpath?
has_link?
has_no_link?
has_button?
has_no_button? 
has_field?
has_no_field?
has_checked_field?
has_unchecked_field?
has_no_table?
has_table?
has_select?
has_no_select?
has_selector?
has_no_selector?

Scripting

# http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Session:evaluate_script
evaluate_script(script) 
# Evaluate the given JavaScript and return the result. Be careful when using this with scripts 
# that return complex objects, such as jQuery statements. execute_script might be a better alternative.

execute_script(script)
# Execute the given script, not returning a result. This is useful for scripts that return 
# complex objects, such as jQuery statements. execute_script should be used over evaluate_script 
# whenever possible.

Debugging

save_page
save_and_open_page 
save_screenshot
print page.html

For Your Info

https://speakerdeck.com/timmoore/embracing-capybara

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_wait_time

Here are the methods that waits:

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

Here are the methods that doesn’t wait:

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

References

[1] Capybara DSL