Module: Capybara::Node::Finders

Included in:
Base, Simple
Defined in:
lib/capybara/node/finders.rb

Instance Method Summary collapse

Instance Method Details

#all(*args) ⇒ Capybara::Element

Find all elements on the page matching the given selector and options.

Both XPath and CSS expressions are supported, but Capybara does not try to automatically distinguish between them. The following statements are equivalent:

page.all(:css, 'a#person_123')
page.all(:xpath, '//a[@id="person_123"]')

If the type of selector is left out, Capybara uses Capybara.default_selector. It’s set to :css by default.

page.all("a#person_123")

Capybara.default_selector = :xpath
page.all('//a[@id="person_123"]')

The set of found elements can further be restricted by specifying options. It’s possible to select elements by their text or visibility:

page.all('a', :text => 'Home')
page.all('#menu li', :visible => true)

Parameters:

  • kind_or_locator (:css, :xpath, String) —

    Either the kind of selector or the selector itself

  • locator (String) —

    The selector

  • options (Hash{Symbol => Object}) —

    Additional options

Returns:

  • (Capybara::Element) —

    The found elements



120
121
122
123
124
125
126
127
 
# File 'lib/capybara/node/finders.rb', line 120

def all(*args)
  options = extract_normalized_options(args)

  Capybara::Selector.normalize(*args).xpaths.
    map    { |path| find_in_base(path) }.flatten.
    select { |node| matches_options(node, options) }.
    map    { |node| convert_element(node) }
end

#find(*args) ⇒ Capybara::Element

Find an Element based on the given arguments. find will raise an error if the element is not found. The error message can be customized through the :message option.

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.

find takes the same options as all.

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

Parameters:

  • options (Hash) —

    a customizable set of options

  • kind_or_locator (:css, :xpath, String) —

    Either the kind of selector or the selector itself

  • locator (String) —

    The selector

  • options (Hash{Symbol => Object}) —

    Additional options

Returns:

  • (Capybara::Element) —

    The found element

Raises:



26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/capybara/node/finders.rb', line 26

def find(*args)
  begin
    node = wait_conditionally_until { first(*args) }
  rescue TimeoutError
  end
  unless node
    options = extract_normalized_options(args)
    normalized = Capybara::Selector.normalize(*args)
    message = options[:message] || "Unable to find #{normalized.name} #{normalized.locator.inspect}"
    message = normalized.failure_message.call(self, normalized) if normalized.failure_message
    raise Capybara::ElementNotFound, message
  end
  return node
end

#find_button(locator) ⇒ Capybara::Element

Find a button on the page. The link can be found by its id, name or value.

Parameters:

  • locator (String) —

    Which button to find

Returns:

  • (Capybara::Element) —

    The found element



71
72
73
 
# File 'lib/capybara/node/finders.rb', line 71

def find_button(locator)
  find(:xpath, XPath::HTML.button(locator))
end

#find_by_id(id) ⇒ Capybara::Element

Find a element on the page, given its id.

Parameters:

  • locator (String) —

    Which element to find

Returns:

  • (Capybara::Element) —

    The found element



82
83
84
 
# File 'lib/capybara/node/finders.rb', line 82

def find_by_id(id)
  find(:css, "##{id}")
end

#find_field(locator) ⇒ Capybara::Element Also known as: field_labeled

Find a form field on the page. The field can be found by its name, id or label text.

Parameters:

  • locator (String) —

    Which field to find

Returns:

  • (Capybara::Element) —

    The found element



48
49
50
 
# File 'lib/capybara/node/finders.rb', line 48

def find_field(locator)
  find(:xpath, XPath::HTML.field(locator))
end

#find_link(locator) ⇒ Capybara::Element

Find a link on the page. The link can be found by its id or text.

Parameters:

  • locator (String) —

    Which link to find

Returns:

  • (Capybara::Element) —

    The found element



60
61
62
 
# File 'lib/capybara/node/finders.rb', line 60

def find_link(locator)
  find(:xpath, XPath::HTML.link(locator))
end

#first(*args) ⇒ Object

Find the first element on the page matching the given selector and options, or nil if no element matches.

When only the first matching element is needed, this method can be faster than all(*args).first.

Parameters:

  • kind_or_locator (:css, :xpath, String) —

    Either the kind of selector or the selector itself

  • locator (String) —

    The selector

  • options (Hash{Symbol => Object}) —

    Additional options; see #all

Returns:

  • Capybara::Element The found element



142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/capybara/node/finders.rb', line 142

def first(*args)
  options = extract_normalized_options(args)
  found_elements = []

  Capybara::Selector.normalize(*args).xpaths.each do |path|
    find_in_base(path).each do |node|
      if matches_options(node, options)
        found_elements << convert_element(node)
        return found_elements.last if not Capybara.prefer_visible_elements or node.visible?
      end
    end
  end
  found_elements.first
end