Implementation:Teamcapybara Capybara Node Simple

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

Overview

Capybara::Node::Simple is a lightweight node wrapper for static HTML strings that supports Capybara's finders and matchers without requiring a session, application, or driver.

Description

The Capybara::Node::Simple class provides a simpler alternative to Capybara::Node::Base for working with HTML content that does not require browser interaction. It is the type of node returned by Capybara.string, making it ideal for unit-testing HTML output, view templates, or any string containing HTML markup.

The class includes three key modules:

• Capybara::Node::Finders -- provides find, all, and other element-finding methods
• Capybara::Node::Matchers -- provides element assertion and predicate matchers
• Capybara::Node::DocumentMatchers -- provides title assertion methods

Notably, it does not include Capybara::Node::Actions, so interactive actions like click_button or fill_in are not available. This is by design since Simple nodes represent static, parsed HTML.

The constructor accepts either a String (which is automatically parsed into a Nokogiri document via Capybara::HTML) or an already-parsed Nokogiri node. The resulting native attribute holds the underlying Nokogiri object.

Key behavioral details:

• Visibility checking is approximate since there is no CSS engine; it inspects style attributes for display:none, checks for the hidden attribute, and excludes script, head, and template tags. Ancestor visibility is evaluated using a precomputed XPath expression (VISIBILITY_XPATH).
• Form element values are extracted with tag-specific logic: textarea reads _capybara_raw_value, select reads from option[@selected], and radio/checkbox inputs default to "on" if no explicit value is set.
• Synchronization is a no-op (synchronize simply yields) because static HTML does not change asynchronously.

Usage

Use this class when you need to apply Capybara matchers and finders to HTML content outside of a full browser session. Common use cases include unit testing Rails view helpers, testing mailer HTML output, verifying HTML fragments generated by components, or any scenario where you want Capybara's expressive query API without the overhead of a driver.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/node/simple.rb (216 lines)

Signature

module Capybara
  module Node
    class Simple
      include Capybara::Node::Finders
      include Capybara::Node::Matchers
      include Capybara::Node::DocumentMatchers

      attr_reader :native

      def initialize(native)
      def text(_type = nil, normalize_ws: false)
      def [](name)
      def tag_name
      def path
      def value
      def visible?(check_ancestors = true)
      def checked?
      def disabled?
      def selected?
      def multiple?
      def readonly?
      def synchronize(_seconds = nil)
      def allow_reload!(*)
      def title
      def inspect
      def find_css(css, **_options)
      def find_xpath(xpath, **_options)
      def session_options
      def initial_cache
      def ==(other)
    end
  end
end

Import

require 'capybara/node/simple'

I/O Contract

Method	Input	Output	Description
initialize(native)	String (HTML) or Nokogiri node	Simple instance	Parses string input via Capybara::HTML; stores Nokogiri node as @native
text(_type, normalize_ws:)	_type: ignored Symbol; normalize_ws: Boolean (default false)	String	Returns text content; collapses whitespace to single spaces and strips if normalize_ws is true
[](name)	Symbol or String attribute name	String, Boolean, or nil	Returns attribute value; special handling for "value" (delegates to #value) and checkbox "checked"
tag_name	(none)	String	Returns the lowercase tag name of the element via native.node_name
path	(none)	String	Returns the XPath expression locating this element in the document
value	(none)	String, Array, or nil	Returns the form element value with tag-specific logic for textarea, select, radio, checkbox, and input
visible?(check_ancestors)	check_ancestors: Boolean (default true)	Boolean	Approximate visibility check; returns false for hidden inputs, templates, and elements with display:none or hidden attribute
find_css(css)	CSS selector string	Array of Nokogiri nodes	Delegates to native.css
find_xpath(xpath)	XPath expression string	Array of Nokogiri nodes	Delegates to native.xpath
title	(none)	String	Returns the document title via native.title
synchronize(_seconds)	Optional Numeric (ignored)	Block result	No-op wrapper; yields immediately since static HTML does not change

Usage Examples

# Parse an HTML string into a Simple node
node = Capybara.string('<html><head><title>Test</title></head><body><h1>Hello</h1><p class="intro">World</p></body></html>')

# Use finders
heading = node.find('h1')
heading.text
# => "Hello"

# Use matchers
node.has_css?('p.intro')
# => true

node.has_content?('World')
# => true

# Check the document title
node.has_title?('Test')
# => true

# Access attributes
paragraph = node.find('p.intro')
paragraph[:class]
# => "intro"
paragraph.tag_name
# => "p"

# Visibility checking
hidden_html = Capybara.string('<div style="display:none">Secret</div><div>Visible</div>')
hidden_html.find('div', text: 'Visible').visible?
# => true

# Working with form elements
form_html = Capybara.string('<select><option selected>A</option><option>B</option></select>')
form_html.find('select').value
# => "A"

# Assertions work the same as with live sessions
node.assert_text('Hello')
node.assert_selector('p.intro')
node.assert_title('Test')

Related Pages

• Teamcapybara_Capybara_Node_Base -- Full-featured base node class with session and driver support
• Teamcapybara_Capybara_Node_Finders -- Finder methods included in Simple
• Teamcapybara_Capybara_Node_Matchers -- Matcher methods included in Simple
• Teamcapybara_Capybara_Node_Document_Matchers -- Document-level matchers included in Simple
• Teamcapybara_Capybara_Node_Document -- Document class for live sessions, contrasting with Simple for static HTML
• Teamcapybara_Capybara_Minitest_Expectations -- Minitest expectations that are also included in Simple