Implementation:Teamcapybara Capybara Spec Find

Knowledge Sources	Teamcapybara_Capybara
Domains	Testing, Test_Specification
Last Updated	2026-02-12 06:00 GMT

Overview

Shared RSpec test suite that validates the #find method across all Capybara drivers.

Description

Capybara::SpecHelper provides shared test specifications that driver implementations must pass. This file contains the shared examples for the #find method, exercising CSS selectors, XPath selectors, custom selectors with filters and match blocks, match strategies (:one, :first, :smart, :prefer_exact), wait behavior for asynchronous content, spatial filtering (above, below, left_of, right_of, near), scoped finding, frozen time handling, and error handling for ambiguous or missing elements.

Usage

Include these shared examples in driver-specific test suites to verify compliance with Capybara's expected behavior contract.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/spec/session/find_spec.rb
• Lines: 1-545

Signature

Capybara::SpecHelper.spec '#find' do
  # shared test examples
end

Import

require 'capybara/spec/spec_helper'

I/O Contract

Inputs

Name	Type	Required	Description
session	Capybara::Session	Yes	Active session to test against

Outputs

Name	Type	Description
Test results	RSpec::Core::Example	Pass/fail assertions

Key Test Scenarios

• Basic element lookup -- finding elements by XPath and CSS locator, verifying text and value attributes
• CSS selectors -- pseudo selectors (:disabled), escaped characters, and default selector configuration
• XPath selectors -- direct XPath expressions and XPath::Union instance support
• Custom selectors -- registering selectors via Capybara.add_selector with custom xpath blocks, match blocks, node filters, filter defaults, and alternate filter sets
• Text option -- filtering results by text content, including type coercion of non-string arguments
• Wait behavior (requires: [:js]) -- asynchronous element appearance with configurable wait durations, including :wait => false for no-wait and explicit timeout values
• Frozen time handling (requires: [:js]) -- ensuring timeouts function correctly when Time.now is stubbed, using Process::CLOCK_MONOTONIC when available
• Exact option -- strict vs. loose matching with XPath#is, defaulting to Capybara.exact
• Match strategies -- :one (raises on ambiguity), :first (returns first match), :smart (exact-preference with ambiguity detection), and :prefer_exact (prefers exact, falls back to first inexact)
• Spatial filters (requires: [:spatial]) -- above, below, left_of, right_of, near, and combinations thereof
• Scoped finding -- within blocks limiting element discovery to a subtree
• Error handling -- Capybara::ElementNotFound with descriptive messages, Capybara::Ambiguous for multiple matches, ArgumentError for unknown selector types and invalid match options
• Custom filter block -- passing a block to #find for additional node filtering
• Capybara.test_id -- locating elements by custom data-test-id attributes with configurable attribute names
• Count option warning -- verifying a deprecation warning when count options are passed to #find

Related Pages

• Environment:Teamcapybara_Capybara_Ruby_And_Gem_Dependencies