Implementation:Teamcapybara Capybara Selector Select

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

Overview

The :select selector definition registers an XPath-based selector that matches <select> elements with comprehensive filters for options, selected state, disabled state, and enabled/disabled option subsets.

Description

This selector is registered via Capybara.add_selector(:select) and uses locate_field to build an XPath expression targeting <select> descendant elements. It incorporates the _field filter set, which provides built-in support for disabled, multiple, name, and placeholder attributes.

The selector provides a rich set of node filters for validating select box state:

• :options — asserts that the select element contains exactly the specified set of option texts (order-independent)
• :enabled_options — asserts that the non-disabled options match exactly the specified texts
• :disabled_options — asserts that the disabled options match exactly the specified texts
• :selected — asserts that the currently selected options match exactly the specified values
• :with_selected — asserts that the currently selected options include at least the specified values

The :with_options expression filter works at the XPath level, requiring that each specified option text exists as a descendant <option> element.

The private helper method options_text extracts option text from the select node, respecting visibility settings and accepting an optional block for filtering (e.g., disabled or selected options).

Usage

Use the :select selector when finding or asserting the state of dropdown/select elements in Capybara tests. It is invoked implicitly by select, has_select?, and find(:select, ...), or when verifying that a select box contains the correct options and selections.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/selector/definition/select.rb
• Lines: 81

Signature

Capybara.add_selector(:select, locator_type: [String, Symbol]) do
  label 'select box'

  xpath do |locator, **options|
    # Returns XPath expression matching select elements
  end

  filter_set(:_field, %i[disabled multiple name placeholder])

  node_filter(:options)
  node_filter(:enabled_options)
  node_filter(:disabled_options)
  expression_filter(:with_options)
  node_filter(:selected)
  node_filter(:with_selected)

  describe_expression_filters
  describe_node_filters
end

Import

require 'capybara/selector/definition/select'
# Typically loaded automatically by Capybara's selector registration

I/O Contract

Locator

Parameter	Type	Description
locator	String, Symbol, or nil	Matches select element via the standard field location logic (id, name, label text, etc.)

Filter Set: _field

Filter	Type	Description
:disabled	Boolean	Matches disabled or enabled select elements
:multiple	Boolean	Matches select elements with or without the multiple attribute
:name	String	Filters by the select element's name attribute
:placeholder	String	Filters by placeholder option text

Node Filters

Filter	Type	Description
:options	Array<String>	Asserts the select contains exactly these option texts (order-independent)
:enabled_options	Array<String>	Asserts that only the non-disabled options match these texts exactly
:disabled_options	Array<String>	Asserts that only the disabled options match these texts exactly
:selected	String, Array<String>	Asserts the selected option(s) match exactly the specified values
:with_selected	String, Array<String>	Asserts the selected options include at least the specified values

Expression Filters

Filter	Type	Description
:with_options	Array<String>	Requires that each specified option text exists as a descendant <option> element (XPath level)

Returns

Returns	Type	Description
xpath	XPath::Expression	An XPath expression matching qualifying <select> elements

Usage Examples

Finding a Select Box by Label

# Find a select box associated with the label "Country"
page.find(:select, 'Country')

# Equivalent helper
page.has_select?('Country')

Asserting Exact Options

# Assert the select contains exactly these options
page.has_select?('Country', options: ['USA', 'Canada', 'Mexico'])

Asserting Selected Values

# Assert that "USA" is currently selected
page.has_select?('Country', selected: 'USA')

# Assert that at least "USA" and "Canada" are selected (multi-select)
page.has_select?('Country', with_selected: ['USA', 'Canada'])

Filtering by Enabled and Disabled Options

# Assert which options are enabled
page.has_select?('Plan', enabled_options: ['Basic', 'Premium'])

# Assert which options are disabled
page.has_select?('Plan', disabled_options: ['Enterprise'])

Using with_options for Partial Matching

# Assert the select contains at least these options (may have more)
page.has_select?('Country', with_options: ['USA', 'Canada'])

Finding a Disabled Select

# Find a select box that is disabled
page.find(:select, 'Locked Field', disabled: true)

Related Pages

• Teamcapybara_Capybara_Selector_CSS - CSS escaping and splitting utilities
• Teamcapybara_Capybara_Selector_Button - Button selector definition
• Teamcapybara_Capybara_Selector_Label - Label selector definition
• Teamcapybara_Capybara_Selector_Link - Link selector definition