Implementation:Teamcapybara Capybara Selenium Find

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

Overview

Concrete tool for optimized element finding with XPath and CSS selectors, including text filtering and visibility/position/style hints via JavaScript, provided by Capybara::Selenium::Find.

Description

Capybara::Selenium::Find is a module mixed into the Selenium driver to accelerate element lookup. The public methods find_xpath and find_css delegate to a private find_by method that first calls the standard Selenium find_elements and then, when more than two elements are returned and the DISABLE_CAPYBARA_SELENIUM_OPTIMIZATIONS environment variable is not set, applies JavaScript-based optimizations.

filter_by_text runs an inline JavaScript snippet that filters the element array by checking each element's textContent against the requested text fragments. gather_hints builds a dynamic JavaScript function from the requested hint types (visibility via the isDisplayed atom, bounding rectangle position via getBoundingClientRect, and computed styles via getComputedStyle) and executes it in a single round-trip. The results are attached to each built node as a hints hash (:visible, :position, :style) so that downstream Capybara filters can use cached values rather than making additional WebDriver calls.

The is_displayed_atom method reads the Selenium isDisplayed atom from the bridge, caching it in a class variable. If the atom cannot be loaded, it returns an empty string and the visibility optimization is silently skipped.

Usage

Automatic when using the Selenium driver. The optimization engages transparently for queries returning more than two elements. Disable by setting ENV['DISABLE_CAPYBARA_SELENIUM_OPTIMIZATIONS'].

Code Reference

Source Location

Repository: capybara
File: lib/capybara/selenium/extensions/find.rb
Lines: 115

Signature

module Capybara::Selenium::Find
  def find_xpath(selector, uses_visibility: false, styles: nil, position: false, **_options)
    # @param selector [String] XPath expression
    # @param uses_visibility [Boolean] Whether to gather visibility hints
    # @param styles [Hash, nil] CSS property names to gather computed styles for
    # @param position [Boolean] Whether to gather bounding rect position hints
    # @return [Array<Capybara::Selenium::Node>]
  end

  def find_css(selector, uses_visibility: false, texts: [], styles: nil, position: false, **_options)
    # @param selector [String] CSS selector
    # @param uses_visibility [Boolean] Whether to gather visibility hints
    # @param texts [Array<String>] Text fragments to filter by
    # @param styles [Hash, nil] CSS property names to gather computed styles for
    # @param position [Boolean] Whether to gather bounding rect position hints
    # @return [Array<Capybara::Selenium::Node>]
  end
end

Import

require 'capybara/selenium/extensions/find'
# Automatically mixed into Capybara::Selenium::Driver

I/O Contract

Inputs

Name	Type	Required	Description
selector	String	Yes	XPath or CSS selector expression
uses_visibility	Boolean	No	Gather visibility hints via isDisplayed atom (default: false)
texts	Array<String>	No	Text fragments for client-side filtering (find_css only; default: [])
styles	Hash/nil	No	Map of CSS property names whose computed values should be gathered (default: nil)
position	Boolean	No	Gather bounding rectangle via getBoundingClientRect (default: false)

Outputs

Name	Type	Description
nodes	Array<Capybara::Selenium::Node>	Built node objects, each optionally carrying a hints hash with :visible, :position, and :style keys

Usage Examples

Internal Driver Usage

# Called internally by the Selenium driver during element queries
# find_css is invoked with hints when optimization is active
driver.find_css('.item', uses_visibility: true, texts: ['hello'], styles: { display: '' }, position: true)

# find_xpath used for XPath-based selectors
driver.find_xpath('//div[@class="content"]', uses_visibility: true, position: true)

Optimization Bypass

# Disable all Selenium optimizations
ENV['DISABLE_CAPYBARA_SELENIUM_OPTIMIZATIONS'] = '1'

# With the env var set, find_by skips text filtering and hint gathering,
# returning nodes without cached hints

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment