Module: Capybara::Node::Finders
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.
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 |
# File 'lib/capybara/node/finders.rb', line 244 def all(*args, **, &optional_filter_block) minimum_specified = () = { minimum: 1 }.merge() unless minimum_specified [:session_options] = query = Capybara::Queries::SelectorQuery.new(*args, , &optional_filter_block) result = nil begin synchronize(query.wait) do result = query.resolve_for(self) raise Capybara::ExpectationNotMet, result. 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, ancestor
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.
56 57 58 59 |
# File 'lib/capybara/node/finders.rb', line 56 def ancestor(*args, **, &optional_filter_block) [:session_options] = synced_resolve Capybara::Queries::AncestorQuery.new(*args, , &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.
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')
31 32 33 34 |
# File 'lib/capybara/node/finders.rb', line 31 def find(*args, **, &optional_filter_block) [:session_options] = synced_resolve Capybara::Queries::SelectorQuery.new(*args, , &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, value, or title. <button> elements can also be found by their text content, and image <input> elements by their alt attribute
162 163 164 |
# File 'lib/capybara/node/finders.rb', line 162 def (locator = nil, **, &optional_filter_block) find(:button, locator, , &optional_filter_block) end |
#find_by_id(id, **options, &optional_filter_block) ⇒ 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.
176 177 178 |
# File 'lib/capybara/node/finders.rb', line 176 def find_by_id(id, **, &optional_filter_block) find(:id, id, , &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.
114 115 116 |
# File 'lib/capybara/node/finders.rb', line 114 def find_field(locator = nil, **, &optional_filter_block) find(:field, locator, , &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.
134 135 136 |
# File 'lib/capybara/node/finders.rb', line 134 def find_link(locator = nil, **, &optional_filter_block) find(:link, locator, , &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.
277 278 279 280 |
# File 'lib/capybara/node/finders.rb', line 277 def first(*args, **, &optional_filter_block) = { minimum: 1 }.merge() unless () all(*args, , &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')
If the driver is capable of executing JavaScript, sibling
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.
82 83 84 85 |
# File 'lib/capybara/node/finders.rb', line 82 def sibling(*args, **, &optional_filter_block) [:session_options] = synced_resolve Capybara::Queries::SiblingQuery.new(*args, , &optional_filter_block) end |