Implementation:Teamcapybara Capybara Selector Label

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

Overview

The :label selector definition registers an XPath-based selector that matches HTML <label> elements by their text content, ID, or associated form control.

Description

This selector is registered via Capybara.add_selector(:label) and constructs an XPath expression targeting <label> elements. The locator can match against the label's text content (via normalized string comparison), id attribute, or test_id attribute (when configured).

The key feature is the :for filter, which supports three modes of label-to-field association:

• String/XPath value — resolved at the expression level by matching either a for attribute on the label or by finding a labelable descendant element with the matching id
• Capybara::Node::Element — resolved at the node filter level by checking if the element's id matches the label's for attribute, or if the element is a descendant of the label
• Regexp — resolved at the node filter level by testing the for attribute value or descendant labelable element IDs against the pattern

The helper method labelable_elements returns the standard HTML5 labelable elements: button, input, keygen, meter, output, progress, select, and textarea.

Usage

Use the :label selector when you need to locate label elements in tests, particularly when verifying form field associations. It is used implicitly by find(:label, 'Email') or when asserting label presence with has_selector?(:label, 'Username').

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/selector/definition/label.rb
• Lines: 62

Signature

Capybara.add_selector(:label, locator_type: [String, Symbol]) do
  label 'label'
  xpath(:for) do |locator, **options|
    # Returns XPath expression matching label elements
  end

  node_filter(:for)
  describe_expression_filters
  describe_node_filters
end

Import

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

I/O Contract

Locator

Parameter	Type	Description
locator	String, Symbol, or nil	Matches label by text content, id attribute, or test_id

Filters

Filter	Type	Level	Description
:for	String	Expression	Matches label with for attribute equal to value, or label wrapping a labelable element with matching id
:for	Capybara::Node::Element	Node	Matches label associated with the given element (via for attribute or ancestor relationship)
:for	Regexp	Node	Matches label whose for attribute or descendant labelable element id matches the pattern

Returns

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

Labelable Elements

Elements
button, input, keygen, meter, output, progress, select, textarea

Usage Examples

Finding a Label by Text

# Find a label element containing the text "Email"
page.find(:label, 'Email')

Finding a Label for a Specific Field ID

# Find the label associated with the field having id "user_email"
page.find(:label, for: 'user_email')

Finding a Label for a Capybara Element

# Find the label associated with a specific input element
email_input = page.find(:field, 'email')
page.find(:label, for: email_input)

Finding a Label with Regexp Matching

# Find labels whose associated field id matches a pattern
page.find(:label, for: /user_.*/)

Related Pages

• Teamcapybara_Capybara_Selector_CSS - CSS escaping and splitting utilities
• Teamcapybara_Capybara_Selector_Button - Button selector definition
• Teamcapybara_Capybara_Selector_Link - Link selector definition
• Teamcapybara_Capybara_Selector_Select - Select element selector definition