Implementation:Teamcapybara Capybara Node Document
| Knowledge Sources | |
|---|---|
| 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