Implementation:Teamcapybara Capybara Spec Click Button

Overview

Capybara::SpecHelper.spec '#click_button' is a comprehensive RSpec shared example group that serves as Capybara's internal test suite for the #click_button session method. It validates button clicking behavior across all supported drivers by testing form submission, field serialization, button finding strategies, redirect handling, HTML5 fields, ARIA roles, form attributes, and edge cases such as disabled buttons and popover interactions.

Source File

Property	Value
File	`lib/capybara/spec/session/click_button_spec.rb`
Lines	526
Language	Ruby
Type	Internal test specification (RSpec shared examples)
Entry Point	`Capybara::SpecHelper.spec '#click_button'`

Test Structure

The test suite visits the /form path before each test and is organized into the following major sections:

Asynchronous Loading

Verifies that click_button waits for asynchronous content to load before interacting, using the requires: [:js] metadata to run only with JavaScript-capable drivers.

it 'should wait for asynchronous load', requires: [:js] do
  @session.visit('/with_js')
  @session.using_wait_time(1.5) do
    @session.click_link('Click me')
    @session.click_button('New Here')
  end
end

Symbol-to-String Casting

Confirms that button locators are cast to strings, allowing symbols to be passed as arguments.

Form Submission with Values

HTML5 Fields

Tests serialization and submission of HTML5 input types:

Search fields
Email fields
URL fields
Telephone fields
Color fields

HTML4 Fields

Tests serialization and submission of standard form elements:

Text fields, password fields, hidden fields
Radio buttons (including default 'on' value)
Check boxes (including default 'on' value)
Text areas (including line ending conversion from LF to CR/LF)
Select tags (with values, without values, with no selection, without options)
Disabled fields (text, textarea, checkbox, radio, select, file) -- verifies they are not submitted
Button inclusion/exclusion -- only the clicked button's value is submitted

Button Finding Strategies

Input Type Submit

Tests finding <input type="submit"> buttons by:

Button value (locator string)
Button id (both as locator and with id: option)
Button title (full and partial match)
Button name (as locator, with name: option, and with regex)

ARIA Roles

Tests clicking elements with role="button" when Capybara.enable_aria_role = true, requiring JavaScript support.

Form Attribute Association

Tests for the HTML5 form attribute (marked with requires: [:form_attribute]):

Fields outside the form element associated via form attribute (text inputs, textareas, selects)
Fields associated with a different form are not serialized
Submit buttons outside the form defined by <button> tag
Submit buttons outside the form defined by <input type="submit"> tag
Submit buttons inside one form but associated with another via form attribute
Submit buttons not associated with any form (should not error)

Image Buttons

Tests finding and clicking <input type="image"> buttons by:

Alt text (full and partial match)
Value attribute (full and partial match)
Id attribute
Title attribute (full and partial match)

Verifies that image buttons not clicked are not included in form submission results.

Button Tag (`<button>`)

Tests finding and clicking <button> elements by:

Text content (full and partial match)
Id attribute
Name attribute (as locator and with name: option)
Value attribute (full and partial match)
Title attribute (full and partial match)
Descendant image alt text (full and partial match)

Verifies GET form serialization when clicking button-tag buttons.

Redirects

Tests that click_button follows:

Standard redirects (verifies landing page content and URL)
307 temporary redirects (method-preserving)
308 permanent redirects (method-preserving)

Postback Behavior

Tests form submission back to the same URL:

When no action attribute is specified
When the action attribute is blank

Formaction and Formmethod Attributes

Tests the HTML5 formaction and formmethod attributes on buttons:

formaction overrides the form's action URL
formmethod overrides the form's method (e.g., GET instead of POST)

Edge Cases

Disabled buttons -- Verifies that click_button raises Capybara::ElementNotFound for disabled buttons
Nonexistent buttons -- Verifies appropriate error message when button is not found
Valueless buttons -- Verifies buttons without explicit values are still serialized and sent
Button ordering -- Verifies buttons are sent in document order
Complex field names -- Tests encoding of array-style field names like address[][city]
Exact matching -- Tests the :exact option for partial vs. exact button matching
Popovers -- Tests interaction with buttons inside popover elements, verifying visibility and clickability
Multiple values with same name -- Verifies the latest given value is used

Test Helper Methods

The tests rely on the extract_results(@session) helper method to parse submitted form data from the response page, enabling assertions on individual field values.

Driver Requirements

Tests are tagged with metadata indicating driver capabilities:

requires: [:js] -- Tests requiring JavaScript execution (asynchronous load, ARIA roles)
requires: [:form_attribute] -- Tests requiring HTML5 form attribute support
:exact_false -- Tests using partial matching (run only when exact matching is not enforced)

Key Design Decisions

Shared examples pattern -- The tests are defined as shared examples via Capybara::SpecHelper.spec, allowing every driver implementation to run the same comprehensive suite and verify compliance with the Capybara API contract.
Capability-gated tests -- The requires: metadata allows tests to be skipped for drivers that do not support specific features (e.g., JavaScript, form attributes), preventing false failures.
Form result extraction -- All assertions are based on parsed form submission results rather than DOM inspection, testing the full round-trip behavior of clicking a button and submitting a form.

Page Connections

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

Principle

Implementation

Heuristic

Environment