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

Page Connections

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

Principle

Implementation

Heuristic

Environment