Method: Capybara::Node::Finders#find

Defined in:
lib/capybara/node/finders.rb

#find(*args, **options, &optional_filter_block) ⇒ Capybara::Node::Element

Find an Element based on the given arguments. #find will raise an error if the element is not found.

page.find('#foo').find('.bar')
page.find(:xpath, './/div[contains(., "bar")]')
page.find('li', text: 'Quox').click_link('Delete')

If the driver is capable of executing JavaScript, this method 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 this method will wait is controlled through default_max_wait_time.

Parameters:

  • options (Hash) —

    a customizable set of options

  • kind (Symbol) —

    Optional selector type (:css, :xpath, :field, etc.). Defaults to default_selector.

  • locator (String) —

    The locator for the specified selector

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • wait (false, true, Numeric) —

    Maximum time to wait for matching element to appear. Defaults to default_max_wait_time.

  • text (String, Regexp) —

    Only find elements which contain this text or match this regexp

  • exact_text (String, Regexp, String) —

    When String the elements contained text must match exactly, when Boolean controls whether the text option must match exactly. Defaults to exact_text.

  • normalize_ws (Boolean) —

    Whether the text/exact_text options are compared against element text with whitespace normalized or as returned by the driver. Defaults to default_normalize_ws.

  • visible (Boolean, Symbol) —

    Only find elements with the specified visibility. Defaults to behavior indicated by ignore_hidden_elements.

    • true - only finds visible elements.
    • false - finds invisible and visible elements.
    • :all - same as false; finds visible and invisible elements.
    • :hidden - only finds invisible elements.
    • :visible - same as true; only finds visible elements.
  • obscured (Boolean) —

    Only find elements with the specified obscured state:

    • true - only find elements whose centerpoint is not in the viewport or is obscured by another non-descendant element.
    • false - only find elements whose centerpoint is in the viewport and is not obscured by other non-descendant elements.
  • id (String, Regexp) —

    Only find elements with an id that matches the value passed

  • class (String, Array<String>, Regexp) —

    Only find elements with matching class/classes.

    • Absence of a class can be checked by prefixing the class name with !

    • If you need to check for existence of a class name that starts with ! then prefix with !!

      class:['a', '!b', '!!!c'] # limit to elements with class 'a' and '!c' but not class 'b'

  • style (String, Regexp, Hash) —

    Only find elements with matching style. String and Regexp will be checked against text of the elements style attribute, while a Hash will be compared against the elements full style

  • exact (Boolean) —

    Control whether is expressions in the given XPath match exactly or partially. Defaults to exact.

  • match (Symbol) —

    The matching strategy to use. Defaults to match.

Returns:

Raises:



51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/capybara/node/finders.rb', line 51

def find(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  count_options = options.slice(*Capybara::Queries::BaseQuery::COUNT_KEYS)
  unless count_options.empty?
    Capybara::Helpers.warn(
      "'find' does not support count options (#{count_options}) ignoring. " \
      "Called from: #{Capybara::Helpers.filter_backtrace(caller)}"
    )
  end
  synced_resolve Capybara::Queries::SelectorQuery.new(*args, **options, &optional_filter_block)
end