Module: Capybara::Node::Finders

Included in:: Base, Simple

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

Instance Method Summary collapse

#all([kind = Capybara.default_selector], locator = nil, **options) ⇒ Capybara::Result (also: #find_all)

Find all elements on the page matching the given selector and options.
#ancestor(*args, **options, &optional_filter_block) ⇒ Capybara::Node::Element

Find an Element based on the given arguments that is also an ancestor of the element called on.
#find(*args, **options, &optional_filter_block) ⇒ Capybara::Node::Element

Find an Element based on the given arguments.
#find_button([locator], **options) ⇒ Capybara::Node::Element

Find a button on the page.
#find_by_id(id, **options, &optional_filter_block) ⇒ Capybara::Node::Element

Find a element on the page, given its id.
#find_field([locator], **options) ⇒ Capybara::Node::Element

Find a form field on the page.
#find_link([locator], **options) ⇒ Capybara::Node::Element

Find a link on the page.
#first([kind], locator, options) ⇒ Capybara::Node::Element

Find the first element on the page matching the given selector and options.
#sibling(*args, **options, &optional_filter_block) ⇒ Capybara::Node::Element

Find an Element based on the given arguments that is also a sibling of the element called on.

Instance Method Details

#all([kind = Capybara.default_selector], locator = nil, options) ⇒ `Capybara::Result` #all([kind = Capybara.default_selector], locator = nil, options) {|element| ... } ⇒ `Capybara::Result` Also known as: find_all

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)

By default Capybara’s waiting behavior will wait up to ‘Capybara.default_max_wait_time` seconds for matching elements to be available and then return an empty result if none are available. It is possible to set expectations on the number of results located and Capybara will raise an exception if the number of elements located don’t satisfy the specified conditions. The expectations can be set using

page.assert_selector('p#foo', count: 4)
page.assert_selector('p#foo', maximum: 10)
page.assert_selector('p#foo', minimum: 1)
page.assert_selector('p#foo', between: 1..10)

See Helpers#matches_count? for additional information about count matching.

Overloads:

#all([kind = Capybara.default_selector], locator = nil, **options) {|element| ... } ⇒ Capybara::Result
Yield Parameters:
- element (Capybara::Node::Element) —
  
  The element being considered for inclusion in the results
Yield Returns:
- (Boolean) —
  
  Should the element be considered in the results?

Parameters:

kind (Symbol) —

Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
locator (String) (defaults to: nil) —

The locator for the specified selector
options (Hash) —

a customizable set of options

Options Hash (**options):

text (String, Regexp) —

Only find elements which contain this text or match this regexp
exact_text (String, Boolean) — default: Capybara.exact_text —

When String the elements contained text must match exactly, when Boolean controls whether the :text option must match exactly
normalize_ws (Boolean) — default: Capybara.default_normalize_ws —

Whether the ‘text`/`exact_text` options are compared against elment text with whitespace normalized or as returned by the driver
visible (Boolean, Symbol) —
Only find elements with the specified visibility:
- 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.
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
count (Integer) —

Exact number of matches that are expected to be found
maximum (Integer) —

Maximum number of matches that are expected to be found
minimum (Integer) —

Minimum number of matches that are expected to be found
between (Range) —

Number of matches found must be within the given range

Returns:

(Capybara::Result) —

A collection of found elements

Raises:

(Capybara::ExpectationNotMet) —

The number of elements found doesn’t match the specified conditions

# File 'lib/capybara/node/finders.rb', line 250

def all(*args, **options, &optional_filter_block)
  minimum_specified = options_include_minimum?(options)
  options = { minimum: 1 }.merge(options) unless minimum_specified
  options[:session_options] = session_options
  query = Capybara::Queries::SelectorQuery.new(*args, options, &optional_filter_block)
  result = nil
  begin
    synchronize(query.wait) do
      result = query.resolve_for(self)
      raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count?

      result
    end
  rescue Capybara::ExpectationNotMet
    raise if minimum_specified || (result.compare_count == 1)

    Result.new([], nil)
  end
end

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

Find an Element based on the given arguments that is also an ancestor of the element called on. ancestor will raise an error if the element is not found.

ancestor takes the same options as find.

element.ancestor('#foo').find('.bar')
element.ancestor(:xpath, './/div[contains(., "bar")]')
element.ancestor('ul', 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 find will wait is controlled through Capybara.default_max_wait_time and defaults to 2 seconds.

Parameters:

options (Hash) —

a customizable set of options
kind (Symbol) —

Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
locator (String) —

The locator for the specified selector
options (Hash) —

a customizable set of options

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.
match (Symbol) —

The matching strategy to use.

Returns:

(Capybara::Node::Element) —

The found element

Raises:

(Capybara::ElementNotFound) —

If the element can’t be found before time expires

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

def ancestor(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  synced_resolve Capybara::Queries::AncestorQuery.new(*args, options, &optional_filter_block)
end

#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')

Parameters:

options (Hash) —

a customizable set of options
kind (Symbol) —

Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
locator (String) —

The locator for the specified selector
options (Hash) —

a customizable set of options

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.
text (String, Regexp) —

Only find elements which contain this text or match this regexp
exact_text (String, Boolean) — default: Capybara.exact_text —

When String the elements contained text must match exactly, when Boolean controls whether the :text option must match exactly
normalize_ws (Boolean) — default: Capybara.default_normalize_ws —

Whether the ‘text`/`exact_text` options are compared against elment text with whitespace normalized or as returned by the driver
visible (Boolean, Symbol) —
Only find elements with the specified visibility:
- 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.
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
match (Symbol) —

The matching strategy to use.

Returns:

(Capybara::Node::Element) —

The found element

Raises:

(Capybara::ElementNotFound) —

If the element can’t be found before time expires

# File 'lib/capybara/node/finders.rb', line 46

def find(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  synced_resolve Capybara::Queries::SelectorQuery.new(*args, options, &optional_filter_block)
end

#find_button([locator], **options) ⇒ `Capybara::Node::Element`

Find a button on the page. This can be any <input> element of type submit, reset, image, button or it can be a <button> element. All buttons can be found by their id, Capbyara.test_id attribute, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute

Parameters:

locator (String) —

id, Capybara.test_id attribute, value, title, text content, alt of image

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.
disabled (Boolean, Symbol) — default: false —
Match disabled button?
- true - only finds a disabled button
- false - only finds an enabled button
- :all - finds either an enabled or disabled button
id (String, Regexp) —

Match buttons with the id provided
title (String) —

Match buttons with the title provided
value (String) —

Match buttons with the value provided
class (String, Array<String>, Regexp) —

Match buttons that match the class(es) provided

Returns:

(Capybara::Node::Element) —

The found element



177
178
179

# File 'lib/capybara/node/finders.rb', line 177

def find_button(locator = nil, **options, &optional_filter_block)
  find(:button, locator, options, &optional_filter_block)
end

#find_by_id(id, **options, &optional_filter_block) ⇒ `Capybara::Node::Element`

Find a element on the page, given its id.

Parameters:

id (String) —

id of element
options (Hash) —

a customizable set of options

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.

Returns:

(Capybara::Node::Element) —

The found element



191
192
193

# File 'lib/capybara/node/finders.rb', line 191

def find_by_id(id, **options, &optional_filter_block)
  find(:id, id, options, &optional_filter_block)
end

#find_field([locator], **options) ⇒ `Capybara::Node::Element`

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

Parameters:

locator (String) —

name, id, Capybara.test_id attribute, placeholder or text of associated label element

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.
checked (Boolean) —

Match checked field?
unchecked (Boolean) —

Match unchecked field?
disabled (Boolean, Symbol) — default: false —
Match disabled field?
- true - only finds a disabled field
- false - only finds an enabled field
- :all - finds either an enabled or disabled field
readonly (Boolean) —

Match readonly field?
with (String, Regexp) —

Value of field to match on
type (String) —

Type of field to match on
multiple (Boolean) —

Match fields that can have multiple values?
id (String, Regexp) —

Match fields that match the id attribute
name (String) —

Match fields that match the name attribute
placeholder (String) —

Match fields that match the placeholder attribute
class (String, Array<String>, Regexp) —

Match fields that match the class(es) passed

Returns:

(Capybara::Node::Element) —

The found element



129
130
131

# File 'lib/capybara/node/finders.rb', line 129

def find_field(locator = nil, **options, &optional_filter_block)
  find(:field, locator, options, &optional_filter_block)
end

#find_link([locator], **options) ⇒ `Capybara::Node::Element`

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

Parameters:

locator (String) —

id, Capybara.test_id attribute, title, text, or alt of enclosed img element

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.
href (String, Regexp, nil) —

Value to match against the links href, if nil finds link placeholders (<a> elements with no href attribute)
id (String, Regexp) —

Match links with the id provided
title (String) —

Match links with the title provided
alt (String) —

Match links with a contained img element whose alt matches
class (String, Array<String>, Regexp) —

Match links that match the class(es) provided

Returns:

(Capybara::Node::Element) —

The found element



149
150
151

# File 'lib/capybara/node/finders.rb', line 149

def find_link(locator = nil, **options, &optional_filter_block)
  find(:link, locator, options, &optional_filter_block)
end

#first([kind], locator, options) ⇒ `Capybara::Node::Element`

Find the first element on the page matching the given selector and options. By default ‘first` will wait up to `Capybara.default_max_wait_time` seconds for matching elements to appear and then raise an error if no matching element is found, or `nil` if the provided count options allow for empty results.

Parameters:

kind (Symbol) —

The type of selector
locator (String) —

The selector
options (Hash) —

Additional options; see #all

Returns:

(Capybara::Node::Element) —

The found element or nil

Raises:

(Capybara::ElementNotFound) —

If element(s) matching the provided options can’t be found before time expires

# File 'lib/capybara/node/finders.rb', line 285

def first(*args, **options, &optional_filter_block)
  options = { minimum: 1 }.merge(options) unless options_include_minimum?(options)
  all(*args, options, &optional_filter_block).first
end

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

Find an Element based on the given arguments that is also a sibling of the element called on. sibling will raise an error if the element is not found.

sibling takes the same options as find.

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

Parameters:

options (Hash) —

a customizable set of options
kind (Symbol) —

Optional selector type (:css, :xpath, :field, etc.) - Defaults to Capybara.default_selector
locator (String) —

The locator for the specified selector
options (Hash) —

a customizable set of options

Options Hash (**options):

wait (false, Numeric) — default: Capybara.default_max_wait_time —

Maximum time to wait for matching element to appear.
match (Symbol) —

The matching strategy to use.

Returns:

(Capybara::Node::Element) —

The found element

Raises:

(Capybara::ElementNotFound) —

If the element can’t be found before time expires

# File 'lib/capybara/node/finders.rb', line 97

def sibling(*args, **options, &optional_filter_block)
  options[:session_options] = session_options
  synced_resolve Capybara::Queries::SiblingQuery.new(*args, options, &optional_filter_block)
end

Module: Capybara::Node::Finders

Instance Method Summary collapse

Instance Method Details

#all([kind = Capybara.default_selector], locator = nil, **options) ⇒ Capybara::Result #all([kind = Capybara.default_selector], locator = nil, **options) {|element| ... } ⇒ Capybara::Result Also known as: find_all

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

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

#find_button([locator], **options) ⇒ Capybara::Node::Element

#find_by_id(id, **options, &optional_filter_block) ⇒ Capybara::Node::Element

#find_field([locator], **options) ⇒ Capybara::Node::Element

#find_link([locator], **options) ⇒ Capybara::Node::Element

#first([kind], locator, options) ⇒ Capybara::Node::Element

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

#all([kind = Capybara.default_selector], locator = nil, options) ⇒ `Capybara::Result` #all([kind = Capybara.default_selector], locator = nil, options) {|element| ... } ⇒ `Capybara::Result` Also known as: find_all

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

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

#find_button([locator], **options) ⇒ `Capybara::Node::Element`

#find_by_id(id, **options, &optional_filter_block) ⇒ `Capybara::Node::Element`

#find_field([locator], **options) ⇒ `Capybara::Node::Element`

#find_link([locator], **options) ⇒ `Capybara::Node::Element`

#first([kind], locator, options) ⇒ `Capybara::Node::Element`

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