Implementation:Teamcapybara Capybara Selector Expression Filter

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

Overview

Concrete tool for defining pre-query expression filters provided by Selector::Definition#expression_filter and ExpressionFilter#apply_filter.

Description

Definition#expression_filter delegates to FilterSet#expression_filter (L25-27) which creates an ExpressionFilter instance. The filter stores the name, type flags, valid values, default, skip conditions, and a transformation block. During query resolution, ExpressionFilter#apply_filter calls the block with the current expression and filter value, returning the modified expression.

Keyword parameters in the css or xpath block are automatically registered as expression filters.

Usage

Define inside an add_selector block. The block receives (current_expression, filter_value) and returns a modified expression string.

Code Reference

Source Location

• Repository: capybara
• File: lib/capybara/selector/filter_set.rb (L25-27), lib/capybara/selector/filters/expression_filter.rb (L8-11)

Signature

# Inside a selector definition block:
expression_filter(name, *types, **options, &block)
  # @param name [Symbol, Regexp] Filter name
  # @param types [Symbol] Type flags (e.g., :boolean)
  # @param options [Hash] valid_values:, default:, skip_if:, matcher:
  # @yield [expression, value] Block that transforms the expression
  # @yieldparam expression The current CSS/XPath expression
  # @yieldparam value The filter value provided by the user
  # @yieldreturn Modified expression

# ExpressionFilter#apply_filter (internal)
def apply_filter(expr, name, value, selector)
  # Calls the block: @block.call(expr, value)
  # Returns: Modified expression
end

Import

require 'capybara'
# Used within Capybara.add_selector blocks

I/O Contract

Inputs

Name	Type	Required	Description
name	Symbol/Regexp	Yes	Filter option name
types	Symbol	No	Type flags (:boolean for automatic error messages)
valid_values	Array	No	Accepted filter values
default	Object	No	Default value when not provided
skip_if	Object	No	Value that skips the filter
block	Block	Yes	Receives (expression, value), returns modified expression

Outputs

Name	Type	Description
modified expression	String	The CSS/XPath expression with filter applied

Usage Examples

Boolean Expression Filter

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

  expression_filter(:active, :boolean) do |expr, value|
    value ? "#{expr}.widget--active" : "#{expr}:not(.widget--active)"
  end
end

find(:widget, 'chart', active: true)
# Generates: .widget[data-name='chart'].widget--active

Value-Based Expression Filter

Capybara.add_selector(:alert) do
  css { |locator| ".alert" }

  expression_filter(:severity, valid_values: %w[info warning error]) do |expr, value|
    "#{expr}.alert-#{value}"
  end
end

find(:alert, severity: 'error')

Related Pages

Implements Principle

• Principle:Teamcapybara_Capybara_Expression_Filtering