Implementation:Teamcapybara Capybara Capybara Add Selector

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

Overview

Concrete tool for defining custom named selectors provided by Capybara.add_selector and Capybara::Selector::Definition.

Description

Capybara.add_selector(name, **options, &block) delegates to Capybara::Selector.add which creates a new Selector::Definition instance. The block is evaluated via instance_eval on the Definition, giving access to DSL methods: css, xpath, expression_filter, node_filter, label, match, and locator_filter.

The css and xpath methods accept a block that receives (locator, **options) and returns an expression string. Any keyword parameters in the block are automatically registered as expression filters.

Usage

Call Capybara.add_selector in test configuration to define domain-specific selectors.

Code Reference

Source Location

• Repository: capybara
• File: lib/capybara.rb (L182-184), lib/capybara/selector/definition.rb (L16-30 for initialize, L59-61 for xpath, L77-79 for css)

Signature

# Top-level API
def add_selector(name, **options, &block)
  # @param name [Symbol] Selector name
  # @param options [Hash] locator_type:, raw_locator:, supports_exact:
  # @yield Block evaluated in context of Selector::Definition
  # @return [Selector::Definition]
  Capybara::Selector.add(name, **options, &block)
end

# Definition DSL methods (available inside the block)
class Selector::Definition
  def css(*allowed_filters, &block)
    # Define CSS expression generator
  end

  def xpath(*allowed_filters, &block)
    # Define XPath expression generator
  end

  def expression_filter(name, *types, **options, &block)
    # Add pre-query expression filter
  end

  def node_filter(name, *types, **options, &block)
    # Add post-query node filter
  end

  def label(label = nil)
    # Set/get descriptive label
  end

  def match(&block)
    # Define auto-detection block
  end
end

Import

require 'capybara'

I/O Contract

Inputs

Name	Type	Required	Description
name	Symbol	Yes	Unique selector name (e.g., :my_widget)
block	Block	Yes	Definition DSL block
locator_type	Symbol/Array	No	Expected locator type(s)
raw_locator	Boolean	No	Skip locator validation

Outputs

Name	Type	Description
definition	Selector::Definition	Stored in Capybara::Selector.all[name]

Usage Examples

CSS-Based Selector

Capybara.add_selector(:card) do
  css { |locator| ".card[data-title='#{locator}']" }

  node_filter(:status) do |node, value|
    node[:class].include?("card--#{value}")
  end
end

# Usage
find(:card, 'Dashboard', status: 'active')

XPath-Based Selector

Capybara.add_selector(:row) do
  xpath { |num| ".//tbody/tr[#{num}]" }
end

# Usage
find(:row, 3)
within(:row, 1) { expect(page).to have_content('First') }

With Expression Filters

Capybara.add_selector(:data_cell) do
  css do |locator, column: nil|
    base = "td[data-value='#{locator}']"
    base += "[data-column='#{column}']" if column
    base
  end
end

# Usage
find(:data_cell, '42', column: 'revenue')

Related Pages

Implements Principle

• Principle:Teamcapybara_Capybara_Selector_Definition

Requires Environment

• Environment:Teamcapybara_Capybara_Ruby_And_Gem_Dependencies