Principle:Teamcapybara Capybara Element Finding

Knowledge Sources	Capybara README
Domains	Testing, DOM_Querying
Last Updated	2026-02-12 00:00 GMT

Overview

A query pattern that locates DOM elements using named selectors with automatic waiting, text filtering, and ambiguity detection.

Description

Element Finding is the core mechanism for locating elements on a web page during acceptance testing. Unlike raw CSS/XPath queries, it adds several layers of intelligence:

• Named selectors — Instead of raw CSS, queries use semantic selector types (:button, :field, :link) that understand HTML semantics
• Auto-waiting — Queries automatically retry for up to default_max_wait_time seconds, handling asynchronous page updates
• Ambiguity detection — find raises Capybara::Ambiguous if multiple elements match (configurable via match strategy)
• System filters — Text, visibility, id, class, and style filters applied after DOM query

The query pipeline flows: Selector resolution → Expression building (CSS/XPath) → Expression filter application → DOM query → Node filter application → System filter application → Count validation.

Usage

Use find when you need exactly one element (raises on ambiguity). Use all when you need a collection. Both support the same selector types and filter options.

Theoretical Basis

# Abstract query pipeline (not actual code)
selector = resolve_selector(kind)  # :css, :button, :field, etc.
expression = selector.call(locator, **options)
expression = apply_expression_filters(expression, options)
raw_elements = driver.find_css(expression)  # or find_xpath
filtered = apply_node_filters(raw_elements, options)
filtered = apply_system_filters(filtered, text:, visible:, id:, class:)
validate_count(filtered, count:, minimum:, maximum:, between:)

Related Pages

Implemented By

• Implementation:Teamcapybara_Capybara_Node_Finders_Find