Implementation:Teamcapybara Capybara Node Finders Find
| Knowledge Sources | |
|---|---|
| Domains | Testing, DOM_Querying |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Concrete tool for locating DOM elements provided by Capybara::Node::Finders#find and #all.
Description
Node::Finders#find constructs a Capybara::Queries::SelectorQuery from the given arguments and resolves it within a synchronize block for auto-waiting. It returns a single Capybara::Node::Element or raises ElementNotFound/Ambiguous. #all returns a Capybara::Result collection (lazy-evaluated Enumerable).
The first positional argument is the selector type (Symbol like :css, :xpath, :button, :field; defaults to Capybara.default_selector). The second is the locator string. All remaining options are filters.
Usage
Use find when you need one element for interaction. Use all when counting or iterating over elements. Use specialized shortcuts find_field, find_button, find_link for common selectors.
Code Reference
Source Location
- Repository: capybara
- File: lib/capybara/node/finders.rb
- Lines: L51-61 (find), L257-276 (all)
Signature
def find(*args, **options, &optional_filter_block)
# @param args [Symbol, String] Selector type and locator
# @param options [Hash] Filters: text, visible, id, class, style, exact, match, wait
# @return [Capybara::Node::Element]
# @raise [Capybara::ElementNotFound, Capybara::Ambiguous]
end
def all(*args, **options, &optional_filter_block)
# @param args [Symbol, String] Selector type and locator
# @param options [Hash] Filters plus count, minimum, maximum, between
# @return [Capybara::Result]
end
Import
require 'capybara'
# find/all available via Capybara::DSL or on any Node::Base subclass
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| kind | Symbol | No | Selector type (:css, :xpath, :button, :field, etc.; default: Capybara.default_selector) |
| locator | String | Yes | Selector expression or locator text |
| text | String/Regexp | No | Filter by text content |
| visible | Boolean/Symbol | No | Visibility filter (true, false, :all, :hidden, :visible) |
| id | String/Regexp | No | Filter by id attribute |
| class | String/Array/Regexp | No | Filter by CSS class(es) |
| count | Integer | No | Exact number expected (all only) |
| minimum | Integer | No | Minimum expected (all only) |
| maximum | Integer | No | Maximum expected (all only) |
| match | Symbol | No | Strategy: :one, :first, :smart, :prefer_exact |
| wait | Numeric | No | Override default wait time |
Outputs
| Name | Type | Description |
|---|---|---|
| find returns | Capybara::Node::Element | A single matched element |
| all returns | Capybara::Result | A lazy collection of matched elements |
Usage Examples
Finding Elements
# By CSS (default)
find('#login-form')
find('.btn-primary')
# By named selector
find(:button, 'Submit')
find(:field, 'Email')
find(:link, 'Home')
# With filters
find('li', text: 'First item')
find('input', id: /email/, visible: true)
# Find all
all('.item', minimum: 3)
all(:button, class: 'active')
# Chaining
find('#form').find(:field, 'Name')