Module: Capybara::Node::Finders

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

Instance Method Summary collapse

Instance Method Details

#all([kind], locator, options) ⇒ 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 if no elements are found, an empty array is returned; however, expectations can be set on the number of elements to be found which will trigger Capybara’s waiting behavior for the expectations to match.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.

Parameters:

  • kind (:css, :xpath) —

    The type of selector

  • locator (String) —

    The selector

Options Hash (options):

  • text (String, Regexp) —

    Only find elements which contain this text or match this regexp

  • 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.

  • 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

  • exact (Boolean) —

    Control whether ‘is` expressions in the given XPath match exactly or partially

  • wait (Integer) — default: Capybara.default_max_wait_time —

    The time to wait for element count expectations to become true

Returns:



179
180
181
182
183
184
185
186
 
# File 'lib/capybara/node/finders.rb', line 179

def all(*args)
  query = Capybara::Query.new(*args)
  synchronize(query.wait) do
    result = query.resolve_for(self)
    raise Capybara::ExpectationNotMet, result.failure_message unless result.matches_count?
    result
  end
end

#find(*args) ⇒ Capybara::Node::Element

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_max_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

Returns:

Raises:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/capybara/node/finders.rb', line 30

def find(*args)
  query = Capybara::Query.new(*args)
  synchronize(query.wait) do
    if query.match == :smart or query.match == :prefer_exact
      result = query.resolve_for(self, true)
      result = query.resolve_for(self, false) if result.size == 0 && !query.exact?
    else
      result = query.resolve_for(self)
    end
    if query.match == :one or query.match == :smart and result.size > 1
      raise Capybara::Ambiguous.new("Ambiguous match, found #{result.size} elements matching #{query.description}")
    end
    if result.size == 0
      raise Capybara::ElementNotFound.new("Unable to find #{query.description}")
    end
    result.first
  end.tap(&:allow_reload!)
end

#find_button(locator, options = {}) ⇒ Capybara::Node::Element

If the driver is capable of executing JavaScript, find_button 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:

  • locator (String) —

    Which button to find

  • options (Hash) (defaults to: {}) —

    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.

  • 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

Returns:



103
104
105
 
# File 'lib/capybara/node/finders.rb', line 103

def find_button(locator, options={})
  find(:button, locator, options)
end

#find_by_id(id, options = {}) ⇒ Capybara::Node::Element

Find a element on the page, given its id.

If the driver is capable of executing JavaScript, find_by_id 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:

  • id (String) —

    Which element to find

  • options (Hash) (defaults to: {}) —

    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:



117
118
119
 
# File 'lib/capybara/node/finders.rb', line 117

def find_by_id(id, options={})
  find(:id, id, options)
end

#find_field(locator, options = {}) ⇒ Capybara::Node::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.

If the driver is capable of executing JavaScript, find_field 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:

  • locator (String) —

    Which field to find

  • options (Hash) (defaults to: {}) —

    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.

  • 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) —

    Value of field to match on

  • type (String) —

    Type of field to match on

Returns:



68
69
70
 
# File 'lib/capybara/node/finders.rb', line 68

def find_field(locator, options={})
  find(:field, locator, options)
end

#find_link(locator, options = {}) ⇒ Capybara::Node::Element

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

If the driver is capable of executing JavaScript, find_link 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:

  • locator (String) —

    Which link to find

  • options (Hash) (defaults to: {}) —

    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.

  • href (String, Regexp) —

    Value to match against the links href

Returns:



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

def find_link(locator, options={})
  find(:link, locator, options)
end

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

Find the first element on the page matching the given selector and options, or nil if no element matches. By default no waiting behavior occurs, however if Capybara.wait_on_first_by_default is set to true it will trigger Capybara’s waiting behavior for a minimum of 1 matching element to be found and return the first. Waiting behavior can also be triggered by passing in any of the count expectation options.

Parameters:

  • kind (:css, :xpath) —

    The type of selector

  • locator (String) —

    The selector

  • options (Hash) —

    Additional options; see #all

Returns:



204
205
206
207
208
209
210
211
212
 
# File 'lib/capybara/node/finders.rb', line 204

def first(*args)
  if Capybara.wait_on_first_by_default
    options = if args.last.is_a?(Hash) then args.pop.dup else {} end
    args.push({minimum: 1}.merge(options))
  end
  all(*args).first
rescue Capybara::ExpectationNotMet
  nil
end