Implementation:Teamcapybara Capybara Node Document

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

Overview

Capybara::Node::Document represents the full HTML document and provides document-level operations such as retrieving text, title, executing scripts, and scrolling.

Description

The Capybara::Node::Document class extends Capybara::Node::Base and serves as the top-level node representing the entire HTML document within a Capybara session. Unlike element-level nodes that target specific DOM elements, the Document class operates on the whole page.

Most of its methods work by internally locating the root /html element (or //body for quirks mode scrolling) and delegating the operation to that element. This design means that Document acts as a thin facade that routes document-wide operations through the existing element infrastructure.

The class includes Capybara::Node::DocumentMatchers, which provides title assertion and predicate methods (assert_title, has_title?, etc.). The title method itself retrieves the page title directly from the session driver rather than through DOM traversal.

Usage

Use this class when performing operations that apply to the entire document rather than a specific element. In typical Capybara usage, the page object returned by Capybara.current_session delegates many calls through a Document instance. This is the appropriate target for reading full page text, checking the document title, executing JavaScript at the page level, or scrolling the viewport.

Code Reference

Source Location

Repository: Teamcapybara_Capybara
File: lib/capybara/node/document.rb (48 lines)

Signature

module Capybara
  module Node
    class Document < Base
      include Capybara::Node::DocumentMatchers

      def text(type = nil, normalize_ws: false)
      def title
      def execute_script(*args)
      def evaluate_script(*args)
      def scroll_to(*args, quirks: false, **options)
      def inspect
    end
  end
end

Import

require 'capybara/node/document'

I/O Contract

Method	Input	Output	Description
`text(type = nil, normalize_ws: false)`	`type`: optional Symbol (`:all` or `:visible`); `normalize_ws`: Boolean	String	Returns the full text content of the document by delegating to the root `/html` element
`title`	(none)	String	Returns the document title via `session.driver.title`
`execute_script(*args)`	JavaScript string, optional arguments	nil	Executes JavaScript in the browser context by delegating to the root `/html` element
`evaluate_script(*args)`	JavaScript string, optional arguments	Object	Evaluates JavaScript and returns the result by delegating to the root `/html` element
`scroll_to(args, quirks: false, *options)`	Scroll target coordinates or element; `quirks`: Boolean to use `//body` instead of `/html`; additional scroll options	nil	Scrolls the document viewport; uses `//body` XPath when `quirks: true`
`inspect`	(none)	String	Returns `#<Capybara::Document>`

Usage Examples

# Retrieve full document text
page.text
# => "Welcome to MyApp\nHome About Contact"

# Retrieve document text with whitespace normalization
page.text(:all, normalize_ws: true)
# => "Welcome to MyApp Home About Contact"

# Get the document title
page.title
# => "MyApp - Home"

# Execute JavaScript at the document level
page.execute_script('window.scrollTo(0, 0)')

# Evaluate JavaScript and capture the result
width = page.evaluate_script('document.documentElement.clientWidth')
# => 1024

# Scroll the document to a specific position
page.scroll_to(0, 500)

# Scroll with quirks mode (targets <body> instead of <html>)
page.scroll_to(0, 500, quirks: true)

# Use title assertions via included DocumentMatchers
page.assert_title('MyApp - Home')
page.has_title?(/MyApp/)
# => true

Related Pages

Teamcapybara_Capybara_Node_Base -- Parent class providing the core node interface
Teamcapybara_Capybara_Node_Document_Matchers -- Module included for title assertion methods
Teamcapybara_Capybara_Node_Element -- Element-level node for interacting with specific DOM elements
Teamcapybara_Capybara_Session -- Session class that uses Document as its top-level node
Teamcapybara_Capybara_Node_Simple -- Lightweight alternative for static HTML without a session

Page Connections

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

Principle

Implementation

Heuristic

Environment