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
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
