Implementation:Teamcapybara Capybara Selector Link

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

Overview

The :link selector definition registers an XPath-based selector that matches anchor (<a>) elements and ARIA role="link" elements with support for href, download, alt, title, and target filters.

Description

This selector is registered via Capybara.add_selector(:link) and builds an XPath expression that targets two categories of link elements:

• Anchor elements — <a> tags, optionally filtered by href attribute presence or value
• ARIA role links — any element with role="link", included when enable_aria_role is active

The href parameter has three modes: when true (default), it requires the href attribute to exist; when false, it matches anchors without href; when a String or Regexp, it filters by the href value. String href matching is handled at the XPath expression level, while Regexp matching is performed via a node filter that also generates descriptive error messages.

The locator matches against id, normalized text content, title, descendant img alt attributes, aria-label (when enabled), and test_id (when configured). Additional attribute filters are available for title, alt (on descendant images), and target.

The download expression filter accepts true (has attribute), false (no attribute), or a String (specific value).

Usage

Use the :link selector when finding or interacting with link elements in Capybara tests. It is invoked implicitly by click_link, find_link, and has_link?, or explicitly via find(:link, 'Home').

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/selector/definition/link.rb
• Lines: 55

Signature

Capybara.add_selector(:link, locator_type: [String, Symbol]) do
  xpath do |locator, href: true, alt: nil, title: nil, target: nil, **|
    # Returns XPath expression matching link elements
  end

  node_filter(:href)
  expression_filter(:download, valid_values: [true, false, String])
  describe_expression_filters
end

Import

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

I/O Contract

Locator

Parameter	Type	Description
locator	String, Symbol, or nil	Matches link by id, text content, title, descendant img alt, aria-label, or test_id

XPath Options

Option	Type	Default	Description
:href	true, false, String, Regexp	true	true requires href to exist; false allows missing href; String/Regexp filters by href value
:alt	String	nil	Matches a descendant <img> element's alt attribute
:title	String	nil	Filters by the link's title attribute
:target	String	nil	Filters by the link's target attribute

Filters

Filter	Type	Level	Description
:href	Regexp	Node	Matches the node's href attribute against the regular expression (String values are handled at XPath level)
:download	true, false, String	Expression	true requires download attribute; false excludes it; String matches specific download value

Returns

Returns	Type	Description
xpath	XPath::Expression	An XPath expression matching qualifying link elements

Usage Examples

Finding a Link by Text

# Find a link with the text "Home"
page.find(:link, 'Home')

# Equivalent helper method
page.find_link('Home')

Clicking a Link with Specific Href

# Click a link with a specific href value
page.click_link('Profile', href: '/users/profile')

Matching Href with a Regular Expression

# Find a link whose href matches a pattern
page.find(:link, href: %r{/users/\d+})

Filtering by Download Attribute

# Find a link with a download attribute
page.find(:link, 'Report', download: true)

# Find a link with a specific download filename
page.find(:link, 'Report', download: 'report.pdf')

Finding Links by Image Alt Text

# Find a link that wraps an image with specific alt text
page.find(:link, alt: 'Company Logo')

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_Select - Select element selector definition