Implementation:Teamcapybara Capybara Selector Button

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

Overview

The :button selector definition registers an XPath-based selector that matches submit, reset, image, and generic button elements by locator string, including support for ARIA roles and label associations.

Description

This selector is registered via Capybara.add_selector(:button) and builds a comprehensive XPath expression that matches four categories of button-like elements:

• Input buttons — <input type="submit|reset|image|button"> elements matched via input_btn_xpath
• Button elements — <button> tags matched via btn_xpath, including text content and descendant <img alt="..."> matching
• ARIA role buttons — any element with role="button" matched via aria_btn_xpath (when ARIA roles are enabled)
• Image buttons — <input type="image"> elements matched by alt and aria-label attributes

The locator can match against id, name, value, title, associated label text (via the for attribute), aria-label (when enabled), and test_id (when configured). The selector includes both expression filters (applied at the XPath level) and node filters (applied after element retrieval) for the disabled and name attributes.

Usage

Use the :button selector whenever you need to find or interact with clickable button elements in Capybara tests. It is invoked implicitly by methods like click_button, find_button, and has_button?, or explicitly via find(:button, 'Submit').

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/selector/definition/button.rb
• Lines: 68

Signature

Capybara.add_selector(:button, locator_type: [String, Symbol]) do
  xpath(:value, :title, :type, :name) do |locator, **options|
    # Returns XPath expression matching button elements
  end

  node_filter(:disabled, :boolean, default: false, skip_if: :all)
  expression_filter(:disabled)
  node_filter(:name)
  expression_filter(:name)
end

Import

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

I/O Contract

Locator

Parameter	Type	Description
locator	String, Symbol, or nil	Matches button by id, name, value, title, associated label text, aria-label, or test_id

XPath Options

Option	Type	Description
:value	String	Filter by the button's value attribute
:title	String	Filter by the button's title attribute
:type	String	Filter by the input type attribute (e.g., "submit", "reset")
:name	String, Regexp	Filter by the button's name attribute; Regexp matching is handled via node filter

Filters

Filter	Type	Default	Description
:disabled	Boolean	false	When true, matches only disabled buttons; when false, excludes disabled buttons; :all skips filtering
:name	String, Regexp	none	Filters by the name attribute; string values use XPath, Regexp values use node filter

Returns

Returns	Type	Description
xpath	XPath::Expression	A union XPath expression matching all qualifying button elements

Usage Examples

Finding a Button by Text

# Find a button with the text "Submit"
page.find(:button, 'Submit')

# Equivalent helper method
page.find_button('Submit')

Clicking a Button by ID

page.click_button('btn-save')

Filtering by Disabled State

# Find only disabled buttons
page.find(:button, 'Send', disabled: true)

# Find all buttons regardless of disabled state
page.find(:button, 'Send', disabled: :all)

Filtering by Type and Name

# Find a submit input with a specific name
page.find(:button, type: 'submit', name: 'commit')

Related Pages

• Implementation:Teamcapybara_Capybara_Selector_CSS - CSS escaping and splitting utilities
• Implementation:Teamcapybara_Capybara_Selector_Label - Label selector definition
• Implementation:Teamcapybara_Capybara_Selector_Link - Link selector definition
• Implementation:Teamcapybara_Capybara_Selector_Select - Select element selector definition