Implementation:Teamcapybara Capybara Queries TextQuery

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

Overview

Capybara::Queries::TextQuery matches text content within a node, supporting exact and partial matching, case sensitivity detection, and visible/invisible text differentiation.

Description

TextQuery extends BaseQuery to verify that a node's text content matches an expected string or regular expression. The :type parameter controls whether to search :visible text only or :all text (including hidden elements); it defaults based on Capybara.ignore_hidden_elements or Capybara.visible_text_only. When :exact is true, the query requires a full match rather than a substring match. The expected text is converted into a search regexp via Capybara::Helpers.to_regexp. On failure, the query provides diagnostic hints: it checks for case-insensitive matches and non-visible text occurrences, appending messages like "it was found 2 times using a case insensitive search" or "it was found 1 time including non-visible text". The :normalize_ws option controls whitespace normalization during text extraction. Valid option keys are :count, :minimum, :maximum, :between, :wait, :exact, and :normalize_ws.

Usage

Use TextQuery through Capybara's text assertions such as have_text, have_content, assert_text, and assert_no_text. It powers all text matching in Capybara test suites.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/queries/text_query.rb
• Lines: 116

Signature

class Capybara::Queries::TextQuery < Capybara::Queries::BaseQuery
  def initialize(type = nil, expected_text, session_options:, **options)
  def resolve_for(node)
  def failure_message
  def negative_failure_message
  def description
end

Import

# No external imports beyond the Capybara framework.
# Typically required via:
require 'capybara/queries/text_query'

I/O Contract

initialize(type = nil, expected_text, session_options:, **options)
Parameter	Type	Required	Description
type	Symbol (:visible or :all)	No	Text visibility scope; defaults based on Capybara.ignore_hidden_elements / Capybara.visible_text_only
expected_text	String or Regexp	Yes	The text or pattern to search for in the node
session_options:	Capybara::SessionConfig	Yes	Session options providing defaults for exact_text and default_normalize_ws
options[:exact]	Boolean	No	Require full text match instead of substring (default: session_options.exact_text)
options[:normalize_ws]	Boolean	No	Normalize whitespace during text extraction (default: session_options.default_normalize_ws)
options[:count]	Integer	No	Exact number of times the text must appear
options[:minimum]	Integer	No	Minimum occurrences
options[:maximum]	Integer	No	Maximum occurrences
options[:between]	Range	No	Acceptable range of occurrences
options[:wait]	Numeric	No	Maximum wait time in seconds
Returns: TextQuery instance

resolve_for(node)
Parameter	Type	Required	Description
node	Capybara::Node::Element	Yes	The node whose text content will be searched
Returns: (void) -- sets internal @actual_text and @count for subsequent match evaluation

description
Parameter	Type	Required	Description
(none)
Returns: String -- e.g., "text \"Hello\"", "exact text \"Hello\"", or "text matching /Hello/i"

failure_message / negative_failure_message
Parameter	Type	Required	Description
(none)
Returns: String -- includes the base failure message plus diagnostic hints about case sensitivity and non-visible text

Usage Examples

# Substring text matching (via Capybara matchers):
expect(page).to have_text('Welcome')

# Exact text matching:
expect(page).to have_text('Welcome to the Dashboard', exact: true)

# Regexp matching:
expect(page).to have_text(/welcome/i)

# Visible text only:
expect(page).to have_text(:visible, 'Hello')

# All text including hidden elements:
expect(page).to have_text(:all, 'Hidden message')

# Count-based matching:
expect(page).to have_text('Item', count: 5)
expect(page).to have_text('Item', minimum: 1, maximum: 10)
expect(page).to have_text('Item', between: 2..8)

# Whitespace normalization:
expect(page).to have_text('spaced  out  text', normalize_ws: true)

# Underlying query usage (internal):
query = Capybara::Queries::TextQuery.new(:visible, 'Hello',
  session_options: page.session_options, exact: true)
query.resolve_for(page.find('h1'))
query.description      # => "exact text \"Hello\""
query.failure_message  # => "expected to find exact text \"Hello\" in \"Goodbye\""

Related Pages

• Teamcapybara_Capybara_Queries_BaseQuery -- abstract base class (parent)
• Teamcapybara_Capybara_Queries_CurrentPathQuery -- current path matching query (sibling)
• Teamcapybara_Capybara_RackTest_Browser -- browser abstraction providing node text
• Teamcapybara_Capybara_RackTest_Driver -- Rack-based test driver