Implementation:Teamcapybara Capybara CSSBuilder

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

Overview

Builds CSS selector expressions by appending attribute conditions, handling special cases for classes, regular expressions, booleans, and IDs.

Description

CSSBuilder takes an initial CSS expression string and provides add_attribute_conditions to append attribute-based filters. For the :class attribute, it generates .classname dot notation for positive classes and :not(.classname) for negated classes (prefixed with !), with double-bang (!!) escaping supported. For Regexp values, it uses RegexpDisassembler to extract alternated substrings and generates [attr*='substring'] conditions with optional case-insensitive (i) flag. For boolean values, it produces [attr] for true and :not([attribute]) for false. ID attributes are converted to #escaped_id shorthand. The builder handles comma-separated CSS selectors by splitting with CSS.split and applying conditions to each part independently, then re-joining.

Usage

Use CSSBuilder internally when defining CSS-based selectors in Capybara to translate high-level attribute filters into valid CSS selector strings. It is used by Capybara's selector infrastructure to convert query options into browser-executable CSS.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/selector/builders/css_builder.rb

Signature

class Capybara::Selector::CSSBuilder
  def initialize(expression)
  attr_reader :expression
  def add_attribute_conditions(**attributes)
end

Import

require 'capybara/selector/builders/css_builder'

I/O Contract

CSSBuilder#initialize

Parameter	Type	Description
expression	String or nil	The initial CSS selector expression; nil defaults to an empty string

Returns	Type	Description
Instance	CSSBuilder	A new builder initialized with the given CSS expression

CSSBuilder#add_attribute_conditions

Parameter	Type	Description
**attributes	Hash{Symbol => String, Regexp, Boolean, XPath::Expression}	Attribute name-value pairs to append as CSS conditions

Returns	Type	Description
expression	String	The updated CSS selector expression with all conditions appended

Special attribute handling:

Attribute	Value Type	Generated CSS
:class	String	.classname (positive) or :not(.classname) (negated with ! prefix)
:class	Regexp	[class*='substring'] with optional i flag
:class	XPath::Expression	Raises ArgumentError
:id	String	#escaped_id
any	Regexp	[attr*='substring'] with optional i flag
any	true	[attr]
any	false	:not([attribute])
any	String	[attr='value']
any	XPath::Expression	Raises ArgumentError

Usage Examples

Basic attribute conditions

builder = Capybara::Selector::CSSBuilder.new('div')
builder.add_attribute_conditions(id: 'main', disabled: true)
builder.expression
# => "div#main[disabled]"

Class conditions with negation

builder = Capybara::Selector::CSSBuilder.new('span')
builder.add_attribute_conditions(class: ['active', '!hidden'])
builder.expression
# => "span.active:not(.hidden)"

Regexp attribute matching

builder = Capybara::Selector::CSSBuilder.new('input')
builder.add_attribute_conditions(name: /user.*name/i)
builder.expression
# => "input[name*='user' i][name*='name' i]"

Comma-separated selectors

builder = Capybara::Selector::CSSBuilder.new('h1, h2, h3')
builder.add_attribute_conditions(class: 'title')
builder.expression
# => "h1.title, h2.title, h3.title"

Related Pages

• Teamcapybara_Capybara_XPathBuilder - Equivalent builder for XPath expressions
• Teamcapybara_Capybara_RSpec_Matchers_HaveSelector - Matchers that rely on selector builders for query construction