Principle:Teamcapybara Capybara Selector Definition

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

Overview

A registration pattern for defining named selectors that generate CSS or XPath expressions from semantic locators.

Description

Selector Definition is the mechanism for creating custom, reusable selectors in Capybara. Instead of writing raw CSS or XPath in every test, selectors encapsulate the query logic behind a symbolic name. A selector definition specifies:

• Expression generation — A css or xpath block that converts a locator string into a CSS/XPath expression
• Expression filters — Pre-query filters that modify the generated expression (narrowing the DOM search)
• Node filters — Post-query filters that validate matched elements against criteria
• Label and error messages — Human-readable descriptions for error messages

Capybara ships with ~20 built-in selectors (:button, :field, :link, :checkbox, :select, etc.) that understand HTML semantics. Custom selectors extend this system for domain-specific elements.

Usage

Use Capybara.add_selector when the built-in selectors don't cover your domain's elements. This is common for custom web components, data grid cells, or application-specific widgets.

Theoretical Basis

# Abstract selector definition (not actual code)
add_selector(:my_widget) do
  css { |locator| ".widget[data-name='#{locator}']" }
  expression_filter(:color) { |expr, value| "#{expr}.widget--#{value}" }
  node_filter(:active) { |node, value| node['aria-active'] == value.to_s }
end

# Usage: find(:my_widget, 'dashboard', color: 'blue', active: true)

Related Pages

Implemented By

• Implementation:Teamcapybara_Capybara_Capybara_Add_Selector