Module: Capybara::Node::Finders

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

Instance Method Summary (collapse)

Instance Method Details

- (Array[Capybara::Element]) all([kind], locator, options)

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 (: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) —

    Only find elements that are visible on the page. Setting this to false (the default, unless Capybara.ignore_hidden_elements = true), finds invisible and visible elements.

Returns:

  • (Array[Capybara::Element]) —

    The found elements



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

def all(*args)
  resolve(query(*args))
end

- (Capybara::Element) find(*args)

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

Returns:

  • (Capybara::Element) —

    The found element

Raises:



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

def find(*args)
  query = query(*args)
  query.find = true
  synchronize do
    results = resolve(query)
    query.verify!(results)
    results.first
  end
end

- (Capybara::Element) find_button(locator)

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



66
67
68
 
# File 'lib/capybara/node/finders.rb', line 66

def find_button(locator)
  find(:button, locator)
end

- (Capybara::Element) find_by_id(id)

Find a element on the page, given its id.

Parameters:

  • locator (String) —

    Which element to find

Returns:

  • (Capybara::Element) —

    The found element



77
78
79
 
# File 'lib/capybara/node/finders.rb', line 77

def find_by_id(id)
  find(:id, id)
end

- (Capybara::Element) find_field(locator) 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



43
44
45
 
# File 'lib/capybara/node/finders.rb', line 43

def find_field(locator)
  find(:field, locator)
end

- (Capybara::Element) find_link(locator)

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



55
56
57
 
# File 'lib/capybara/node/finders.rb', line 55

def find_link(locator)
  find(:link, locator)
end

- (Capybara::Element) first([kind], locator, options)

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

Parameters:

  • kind (:css, :xpath) —

    The type of selector

  • locator (String) —

    The selector

  • options (Hash) —

    Additional options; see all

Returns:

  • (Capybara::Element) —

    The found element or nil



132
133
134
 
# File 'lib/capybara/node/finders.rb', line 132

def first(*args)
  all(*args).first
end

- (Object) query(*args) 



136
137
138
 
# File 'lib/capybara/node/finders.rb', line 136

def query(*args)
  Capybara::Query.new(self, *args)
end

- (Object) resolve(query) 



140
141
142
143
144
145
146
 
# File 'lib/capybara/node/finders.rb', line 140

def resolve(query)
  synchronize do
    base.find(query.xpath).map do |node|
      Capybara::Node::Element.new(session, node, self, query)
    end.select { |node| query.matches_filters?(node) }
  end
end