Implementation:Teamcapybara Capybara Selector Filters Base

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

Overview

Base class for all selector filters provided by Capybara::Selector::Filters::Base, establishing the shared interface for default/skip handling, value validation, format metadata, and option matching.

Description

Capybara::Selector::Filters::Base is the superclass of both NodeFilter and ExpressionFilter. It encapsulates the core filter lifecycle:

initialize(name, matcher, block, **options) stores the filter name (Symbol or Regexp), an optional matcher (Regexp for pattern-based option matching), a transformation/evaluation block, and option flags including :boolean, :valid_values, :default, :skip_if, and :format. When :boolean is set, valid_values is automatically set to [true, false].
default? and default check for and retrieve a default value that is injected when the user does not supply the filter option.
skip?(value) returns true when the provided value matches the :skip_if option, allowing filters to be conditionally bypassed.
format returns the format metadata for the filter.
matcher? indicates whether the filter uses a Regexp matcher rather than an exact name match.
boolean? returns true when the filter was declared as Boolean-typed.
handles_option?(option_name) resolves whether the filter handles a given option name, either by Regexp match or exact Symbol equality.

The private apply method is the internal execution path called by subclasses. It checks skip?, validates the value against valid_values using triple-equals (===) matching, then invokes the block with either 2 arguments (subject, value) or 3 arguments (subject, name, value) depending on block arity. The block is executed in the context of filter_context, which falls back to the block's binding receiver if no explicit context is provided.

Usage

Not used directly. Subclassed by NodeFilter and ExpressionFilter which call apply from their public matches? and apply_filter methods respectively.

Code Reference

Source Location

Repository: capybara
File: lib/capybara/selector/filters/base.rb (77 lines)

Signature

module Capybara
  class Selector
    module Filters
      class Base
        def initialize(name, matcher, block, **options)
          # @param name [Symbol, Regexp] Filter identifier
          # @param matcher [Regexp, nil] Pattern for matching option names
          # @param block [Proc] Transformation or evaluation block
          # @param options [Hash] :boolean, :valid_values, :default, :skip_if, :format
        end

        def default?
          # @return [Boolean] Whether a default value is configured
        end

        def default
          # @return [Object] The configured default value
        end

        def skip?(value)
          # @param value [Object] Value to check against :skip_if
          # @return [Boolean] Whether the filter should be skipped
        end

        def format
          # @return [Object] Format metadata for the filter
        end

        def matcher?
          # @return [Boolean] Whether the filter uses a Regexp matcher
        end

        def boolean?
          # @return [Boolean] Whether the filter is Boolean-typed
        end

        def handles_option?(option_name)
          # @param option_name [Symbol] Option name to check
          # @return [Boolean] Whether this filter handles the given option
        end
      end
    end
  end
end

Import

require 'capybara/selector/filters/base'
# Typically not required directly; loaded via capybara/selector internals

I/O Contract

Inputs

Name	Type	Required	Description
name	Symbol/Regexp	Yes	Filter identifier used for option matching
matcher	Regexp/nil	No	Pattern-based option name matching (nil for exact name match)
block	Proc	Yes	Block invoked with (subject, value) or (subject, name, value)
boolean	Boolean	No	If true, sets valid_values to [true, false]
valid_values	Array	No	Accepted filter values; validated via === matching
default	Object	No	Default value injected when option not supplied by user
skip_if	Object	No	Value that causes the filter to be bypassed
format	Object	No	Format metadata for the filter

Outputs

Name	Type	Description
default?	Boolean	Whether the filter has a configured default
skip?	Boolean	Whether the given value triggers a skip
handles_option?	Boolean	Whether the filter handles the named option
boolean?	Boolean	Whether the filter is Boolean-typed

Internal Details

Private Method: apply

def apply(subject, name, value, skip_value, ctx)
  # 1. Returns skip_value immediately if skip?(value) is true
  # 2. Validates value against valid_values; raises ArgumentError on mismatch
  # 3. Invokes block with 2 or 3 args based on block.arity
  # 4. Executes in filter_context(ctx) via instance_exec
end

Private Method: valid_value?

def valid_value?(value)
  # Returns true if no valid_values configured
  # Otherwise checks Array(valid_values).any? { |valid| valid === value }
end

Related Pages

Implements Principle

Page Connections

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

Principle

Implementation

Heuristic

Environment