Implementation:Teamcapybara Capybara Spec Selector

Knowledge Sources	Teamcapybara_Capybara
Domains	Testing, Test_Specification
Last Updated	2026-02-12 06:00 GMT

Overview

This test suite validates the Capybara selector system, covering custom selector definition, CSS and XPath expression building, built-in selector behavior, filter sets, and special character handling.

Description

The file defines an RSpec.describe Capybara block containing a Selectors describe group that operates on a comprehensive HTML string fixture with diverse elements (divs, inputs, labels, selects, tables, links, fieldsets). Before each test, it registers three custom selectors: custom_selector (CSS-based with a node_filter), custom_css_selector (CSS-based with named expression filters for placeholder, value, and title), and custom_xpath_selector (XPath-based with a match block). The tests then exercise the add_selector and modify_selector APIs, the Capybara::Selector[] lookup and Capybara::Selector.for auto-detection, XPath and CSS expression filter name resolution (explicit names vs. block parameter inference), and the full suite of built-in selectors (:field, :fieldset, :link, :link_or_button, :fillable_field, :radio_button, :checkbox, :select, :option, :file_field, :table, :css, :xpath, :id, :button, :element). It validates :id and :class options with compound CSS selectors, special characters (e.g., #special, 2checkbox, .special), XPath::Expression support, Regexp matching for both XPath and CSS selectors, negated class handling (e.g., !cc), :style option matching, table row/column matching, and the :element selector's wildcard attribute validation with presence/absence checks.

Usage

This spec file is run as part of the Capybara test suite to ensure the selector DSL and all built-in selectors produce correct XPath or CSS expressions and apply node/expression filters correctly. It is critical for verifying that custom selectors defined by users and built-in selectors used throughout the framework work as expected.

Code Reference

Source Location

Repository: Teamcapybara_Capybara
File: spec/selector_spec.rb
Lines: 1-529

Signature

RSpec.describe Capybara do
  include Capybara::RSpecMatchers

  describe 'Selectors' do
    let :string do
      described_class.string <<-STRING
        <html>
          <!-- comprehensive HTML fixture -->
        </html>
      STRING
    end

    before do
      described_class.add_selector :custom_selector do
        css { |css_class| "div.#{css_class}" }
        node_filter(:not_empty, boolean: true, default: true, skip_if: :all) { ... }
      end

      described_class.add_selector :custom_css_selector do
        css(:name, :other_name) { |selector, name: nil, **| ... }
        expression_filter(:placeholder) { ... }
        expression_filter(:value) { ... }
        expression_filter(:title) { ... }
      end

      described_class.add_selector :custom_xpath_selector do
        xpath(:valid1, :valid2) { |selector| selector }
        match { |value| value == 'match_me' }
      end
    end

    describe 'adding a selector' do ... end
    describe 'modify_selector' do ... end
    describe '::[]' do ... end
    describe '::for' do ... end
    describe 'xpath' do ... end
    describe 'css' do ... end
    describe 'builtin selectors' do ... end
  end
end

Import

require 'spec_helper'

Key Test Scenarios

Custom selector definition -- Tests add_selector with CSS and XPath blocks, node_filter, expression_filter, filter alias, and default visibility settings
Selector modification -- Tests modify_selector for changing CSS expressions while preserving existing filters
Selector lookup -- Tests Capybara::Selector[:name] for finding selectors and raising ArgumentError for unknown types
Selector auto-detection -- Tests Capybara::Selector.for matching locators to selectors via match blocks
XPath expression filters -- Validates explicit filter names, block parameter inference, and name precedence over block parameters
CSS expression filters -- Validates named filter support in CSS selectors, explicit expression filters, and block parameter inference
Built-in selectors with nil locator -- Confirms all built-in selectors devolve to correct XPath expressions when no locator is provided
:id option -- Tests compound CSS selector support, special characters (#special, 2checkbox), XPath::Expression, Regexp matching, and error for XPath expressions on CSS selectors
:class option -- Tests compound selectors, negated classes (!cc, !!!mine), special characters, XPath::Expression, Regexp for whole class and individual class names
:style option -- Tests string and Regexp matching of inline style attributes
Field selector -- Tests finding by label, id (string and regexp), name, placeholder, and type (including select)
Option selector -- Tests disabled, selected, and combined filter states
Button selector -- Tests finding by value, title, and non-matching parameter inclusion in failure messages
Element selector -- Tests attribute matching, regexp support, system key compatibility, attribute presence/absence validation, wildcard key descriptions, and XPath::Expression attributes
Link or button selector -- Tests disabled link exclusion and behavior after modification with custom expression filters
Table selector -- Tests finding tables by row content (with_rows) and column content (with_cols)

Related Pages

Environment:Teamcapybara_Capybara_Ruby_And_Gem_Dependencies

Page Connections

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

Principle

Implementation

Heuristic

Environment