Module: Capybara::Node::Finders

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

Instance Method Summary (collapse)

Instance Method Details

- (Capybara::Result) 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)

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

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 finds invisible and 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



144
145
146
147
148
149
150
151
# File 'lib/capybara/node/finders.rb', line 144

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

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

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

Raises:



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

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

- (Capybara::Element) find_button(locator, options = {})

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



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

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

- (Capybara::Element) find_by_id(id, options = {})

Find a element on the page, given its id.



88
89
90
# File 'lib/capybara/node/finders.rb', line 88

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

- (Capybara::Element) find_field(locator, options = {}) Also known as: field_labeled

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



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

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

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



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

def find_link(locator, options={})
  find(:link, locator, options)
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.



164
165
166
# File 'lib/capybara/node/finders.rb', line 164

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