Read more

Using Capybara finder methods with arbitrary matching conditions

Henning Koch
May 11, 2023Software engineer at makandra GmbH

Capybara has a variety of finder methods Show snapshot like find_button to help you look up DOM elements. There are also matchers Show snapshot like have_field to make expectations during tests.

Illustration web development

Do you need DevOps-experts?

Your development team has a full backlog? No time for infrastructure architecture? Our DevOps team is ready to support you!

  • We build reliable cloud solutions with Infrastructure as code
  • We are experts in security, Linux and databases
  • We support your dev team to perform
Read more Show snapshot

These methods also have a number of options to influence the lookup. E.g. the :disabled option lets you control whether Capybara will match disabled fields.

If you have a matching condition that cannot be expressed by the existing Capybara option you may pass a block to define additional conditions in Ruby.


The following will expect a field labeled Username, but also requires that this field has a blank [class] attribute:

expect(page).to have_field('Username') { |field| field[:class].blank? }


Using execute_script, evaluate_script or evaluate_async_script within a filter block will crash with a timeout:

*** Selenium::WebDriver::Error::ScriptTimeoutError Exception: script timeout

This is due to Capybara using a zero timeout Show snapshot while calling the filter block.

A workaround is to temporarily set a different timeout while running your script:

expect(page).to have_field('Username') do |field|
  field.session.using_wait_time(0.5 * Capybara.default_max_wait_time) do


Don't reset the wait time to the full Capybara.default_max_wait_time or you will lose Capybara's retry mechanism Show snapshot .

Posted by Henning Koch to makandra dev (2023-05-11 14:46)