Implementation:Teamcapybara Capybara Queries BaseQuery

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

Overview

Capybara::Queries::BaseQuery is the abstract base class for all Capybara query objects, providing shared logic for count matching, wait time resolution, and failure message generation.

Description

BaseQuery serves as the foundation of Capybara's query hierarchy. It defines the COUNT_KEYS constant (%i[count minimum maximum between]) and implements the core count-matching algorithm used by all query subclasses. When a query specifies :count, that option takes precedence over :minimum, :maximum, and :between. The class also provides wait time resolution that falls back to session_options.default_max_wait_time when no explicit :wait option is given. Failure messages are assembled by combining a subclass-provided description with a human-readable count expectation string. The assert_valid_keys private method validates that only recognized option keys are passed, raising an ArgumentError for any invalid keys.

Usage

BaseQuery is not instantiated directly. Subclass it to create custom query types (e.g., TextQuery, SelectorQuery, CurrentPathQuery) and override description and any query-specific resolution logic. All built-in Capybara assertions and matchers delegate to query objects that inherit from this class.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/queries/base_query.rb
• Lines: 106

Signature

class Capybara::Queries::BaseQuery
  COUNT_KEYS = %i[count minimum maximum between].freeze

  attr_reader :options
  attr_writer :session_options

  def initialize(options)
  def wait
  def self.wait(options, default = Capybara.default_max_wait_time)
  def expects_none?
  def matches_count?(count)
  def failure_message
  def negative_failure_message
end

Import

# No external imports; this file is loaded as part of the Capybara query framework.
# Typically required via:
require 'capybara/queries/base_query'

I/O Contract

initialize(options)
Parameter	Type	Required	Description
options	Hash	Yes	Options hash; may include :session_options, :count, :minimum, :maximum, :between, :wait
Returns: BaseQuery instance

wait
Parameter	Type	Required	Description
(none)
Returns: Numeric -- the wait time in seconds (from :wait option or default_max_wait_time)

matches_count?(count)
Parameter	Type	Required	Description
count	Integer	Yes	The actual count to test against the query's count constraints
Returns: Boolean -- true if the count satisfies all specified constraints

expects_none?
Parameter	Type	Required	Description
(none)
Returns: Boolean -- true if a count of 0 matches the query's count options; false if no count options specified

failure_message / negative_failure_message
Parameter	Type	Required	Description
(none)
Returns: String -- human-readable failure description including count expectations

Usage Examples

# BaseQuery is abstract; this illustrates subclass usage patterns.

# Count matching logic (inherited by all subclasses):
query = SomeFinder.new(count: 3)
query.matches_count?(3)  # => true
query.matches_count?(2)  # => false

# Range-based count matching:
query = SomeFinder.new(between: 2..5)
query.matches_count?(3)  # => true
query.matches_count?(6)  # => false

# Minimum / maximum:
query = SomeFinder.new(minimum: 1, maximum: 10)
query.matches_count?(5)  # => true
query.matches_count?(0)  # => false

# Wait time resolution:
query = SomeFinder.new(wait: 5)
query.wait  # => 5

query = SomeFinder.new({})
query.wait  # => Capybara.default_max_wait_time

# Checking if zero results are acceptable:
query = SomeFinder.new(maximum: 0)
query.expects_none?  # => true

query = SomeFinder.new(minimum: 1)
query.expects_none?  # => false

Related Pages

• Teamcapybara_Capybara_Queries_TextQuery -- text content matching query (subclass)
• Teamcapybara_Capybara_Queries_CurrentPathQuery -- current path matching query (subclass)
• Teamcapybara_Capybara_RackTest_Driver -- Rack-based test driver
• Teamcapybara_Capybara_RackTest_Browser -- browser abstraction for Rack testing