Implementation:Teamcapybara Capybara Selector Table

Knowledge Sources	Capybara
Domains	Testing, Selector_System
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete selector definition for matching HTML

elements provided by with support for complex row/column content filtering and header-to-cell position tracking.

Description

The selector is registered via . The block builds an expression that matches by attribute, layouts.

Usage

Used automatically when calling find(:table, ...) or have_table(...) matchers. The expression filters allow asserting specific table content structure without manual XPath.

Code Reference

Source Location

• Repository: capybara
• File: lib/capybara/selector/definition/table.rb (109 lines)

Signature

Capybara.add_selector(:table, locator_type: [String, Symbol]) do
  xpath do |locator, caption: nil, **|
    # Builds XPath matching by id, caption text, or test_id
    # @param locator [String, Symbol, nil] Table id or caption text
    # @param caption [String, nil] Explicit caption text filter
    # @return [XPath::Expression]
  end

  expression_filter(:with_cols, valid_values: [Array]) do |xpath, cols|
    # @param cols [Array<Hash>, Array<Array>] Column content specifications
    # @return [XPath::Expression] XPath with column existence conditions
  end

  expression_filter(:cols, valid_values: [Array]) do |xpath, cols|
    # @param cols [Array<Array>] Exact column content (must be Array of Arrays)
    # @return [XPath::Expression] XPath with strict column/row count conditions
  end

  expression_filter(:with_rows, valid_values: [Array]) do |xpath, rows|
    # @param rows [Array<Hash>, Array<Array>] Row content specifications
    # @return [XPath::Expression] XPath with row existence conditions
  end

  expression_filter(:rows, valid_values: [Array]) do |xpath, rows|
    # @param rows [Array<Hash>, Array<Array>] Exact row content
    # @return [XPath::Expression] XPath with strict row count conditions
  end
end

Import

require 'capybara'
# The :table selector is auto-loaded from lib/capybara/selector/definition/table.rb

I/O Contract

Inputs

text content, or test_id attribute. An optional caption keyword further constrains the match. Four expression filters provide structured table content matching:

• with_cols -- Asserts that specified columns exist in the table. Accepts an Array of Hashes (header-to-cell mapping) or an Array of Arrays (ordered cell values). Uses prev_col_position? to verify that matched cells share the same column position across rows.
• cols -- Strict column match. Like with_cols but also enforces exact row count via match_row_count and exact column count via match_size: true on each row. Transposes the column arrays into rows for matching.
• with_rows -- Asserts that specified rows exist in the table. Each row can be a Hash (header-to-cell mapping) or an Array (ordered cell values).
• rows -- Strict row match. Like with_rows but also enforces exact row count.

Private helper methods handle the XPath construction: match_row dispatches to row_match_cells_to_headers (Hash rows) or row_match_ordered_cells (Array rows), cell_position computes column index via preceding_sibling(:td).count.plus(1), and match_row_count handles both <tbody>-wrapped and direct

Capybara.add_selector(:table)

:table

Capybara.add_selector(:table, locator_type: [String, Symbol])

xpath

XPath.descendant(:table)

id

text content

Name	Type	Required	Description
locator	String/Symbol	No	Table id attribute or
caption	String	No	Explicit caption text to match
with_cols	Array	No	Array of Hashes (header => cell) or Array of Arrays for column content assertion
cols	Array<Array>	No	Strict column match; must be Array of Arrays; enforces exact row count
with_rows	Array	No	Array of Hashes (header => cell) or Array of Arrays for row content assertion
rows	Array	No	Strict row match; enforces exact row count

Outputs

Name	Type	Description
XPath expression	XPath::Expression	XPath selecting elements matching all specified criteria Usage Examples Find Table by Caption find(:table, 'Monthly Revenue') # Matches <table> with <caption>Monthly Revenue</caption> or id="Monthly Revenue" Assert Row Content with Header Mapping expect(page).to have_table('Users', with_rows: [ { 'Name' => 'Alice', 'Role' => 'Admin' }, { 'Name' => 'Bob', 'Role' => 'Editor' } ]) Strict Column Match expect(page).to have_table('Scores', cols: [ ['Alice', 'Bob', 'Carol'], # First column values top-to-bottom ['95', '87', '92'] # Second column values top-to-bottom ]) # Enforces exactly 3 rows and exactly 2 columns Assert Partial Column Content with Headers expect(page).to have_table('Inventory', with_cols: [ { 'Product' => 'Widget', 'Stock' => '150' } ]) # Verifies that a column headed "Product" contains "Widget" in the same row # where the column headed "Stock" contains "150" Related Pages Implements Principle Principle:Teamcapybara_Capybara_Selector_Definition Principle:Teamcapybara_Capybara_Expression_Filtering