Implementation:Teamcapybara Capybara Node Document Matchers

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

Overview

Capybara::Node::DocumentMatchers provides document-level title assertion and predicate methods for verifying the HTML document title within Capybara tests.

Description

The Capybara::Node::DocumentMatchers module supplies four public methods focused exclusively on matching the page title: two assertion methods (assert_title and assert_no_title) and two predicate methods (has_title? and has_no_title?).

The assertion methods accept either a String (for substring or exact matching) or a Regexp (for pattern matching) as the first argument. They support an :exact option to control whether string matching is a substring check or an exact comparison, and a :wait option to specify how long Capybara should retry before failing (defaulting to Capybara.default_max_wait_time).

Internally, both assertion methods delegate to the private _verify_title method, which constructs a Capybara::Queries::TitleQuery and calls synchronize to repeatedly evaluate the query within the wait period. If the condition is not met, a Capybara::ExpectationNotMet exception is raised.

The predicate methods (has_title? and has_no_title?) wrap the corresponding assertion methods using make_predicate, converting exceptions into boolean true/false return values.

This module is included in both Capybara::Node::Document and Capybara::Node::Simple, allowing title checks on both live sessions and static HTML strings.

Usage

Use this module's methods when you need to verify the HTML page title in integration tests. The assertion variants are suitable for test frameworks that expect exceptions on failure, while the predicate variants are useful in conditional logic or custom matchers. The wait/retry mechanism in the assertion methods makes them robust for testing pages where the title may change asynchronously.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/node/document_matchers.rb (67 lines)

Signature

module Capybara
  module Node
    module DocumentMatchers
      def assert_title(title, **options)
      def assert_no_title(title, **options)
      def has_title?(title, **options)
      def has_no_title?(title, **options)

    private
      def _verify_title(title, options)
    end
  end
end

Import

require 'capybara/node/document_matchers'

I/O Contract

Method	Input	Output	Raises
assert_title(title, **options)	title: String or Regexp; :wait: Numeric (default Capybara.default_max_wait_time); :exact: Boolean (default false)	true	Capybara::ExpectationNotMet if title does not match within wait time
assert_no_title(title, **options)	title: String or Regexp; :wait: Numeric; :exact: Boolean	true	Capybara::ExpectationNotMet if title still matches within wait time
has_title?(title, **options)	title: String or Regexp; :wait: Numeric; :exact: Boolean	Boolean	(none -- exceptions are caught internally)
has_no_title?(title, **options)	title: String or Regexp; :wait: Numeric; :exact: Boolean	Boolean	(none -- exceptions are caught internally)

Options Detail

Option	Type	Default	Description
:wait	Numeric	Capybara.default_max_wait_time	Maximum time in seconds to retry the title query before raising an error
:exact	Boolean	false	When true and a String is passed, requires an exact match rather than substring inclusion

Usage Examples

# Assert the page has a specific title (substring match)
page.assert_title('Dashboard')

# Assert the page has an exact title
page.assert_title('Admin Dashboard', exact: true)

# Assert the page title matches a regular expression
page.assert_title(/Dashboard - \w+/)

# Assert the page does NOT have a given title
page.assert_no_title('Login')

# Use predicate methods for conditional checks
if page.has_title?('Welcome')
  puts "On the welcome page"
end

# Check that title has changed (with custom wait time)
page.assert_title('New Page Title', wait: 10)

# Predicate with negation
page.has_no_title?('Old Title')
# => true (if the title is no longer "Old Title")

Related Pages

• Teamcapybara_Capybara_Node_Document -- The Document class that includes this module
• Teamcapybara_Capybara_Node_Simple -- The Simple node class that also includes this module
• Teamcapybara_Capybara_Queries_TitleQuery -- The query object used internally to evaluate title conditions
• Teamcapybara_Capybara_Node_Matchers -- Element-level matchers for selectors, text, and form elements
• Teamcapybara_Capybara_Minitest_Expectations -- Minitest expectations that wrap these matchers as must_have_title/wont_have_title