Implementation:Teamcapybara Capybara Minitest Expectations

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

Overview

Capybara::Minitest::Expectations provides Minitest::Spec-style expectation syntax for Capybara matchers, allowing test authors to use must_have_* and wont_have_* methods directly on page objects and nodes.

Description

The Capybara::Minitest::Expectations module bridges Capybara's matcher and assertion system with Minitest::Spec's expectation DSL. Rather than defining each expectation method by hand, the module dynamically generates expectation methods by iterating over a list of Capybara assertion names and creating corresponding must_have_* and wont_have_* methods using class_eval.

The generation covers the following categories of expectations:

• Content matchers: must_have_text, must_have_content, wont_have_text, wont_have_content
• Element selectors: must_have_selector, must_have_xpath, must_have_css, must_have_element and their wont_have_* counterparts
• Form elements: must_have_button, must_have_field, must_have_select, must_have_checked_field, must_have_unchecked_field and negations
• Navigation matchers: must_have_link, must_have_current_path, must_have_title and negations
• Structural matchers: must_have_table, must_have_ancestor, must_have_sibling
• Aggregate selectors: must_have_all_of_selectors, must_have_none_of_selectors, must_have_any_of_selectors
• Style matching: must_match_style
• Match selectors: must_match_selector, must_match_xpath, must_match_css and their wont_match_* counterparts

Each generated method creates a Minitest::Expectation instance that delegates to the underlying assert_* or refute_* method on the current test context. The module is automatically included into Capybara::Session, Capybara::Node::Base, and Capybara::Node::Simple unless the environment variable MT_NO_EXPECTATIONS is set.

Usage

Use this module when writing Capybara integration or acceptance tests using Minitest::Spec syntax. It allows natural expectation chains such as page.must_have_content("Hello") instead of the assertion-style assert_content(page, "Hello"). Import the file with require 'capybara/minitest/spec' to activate all expectations. Set the MT_NO_EXPECTATIONS environment variable to disable automatic inclusion.

Code Reference

Source Location

• Repository: Teamcapybara_Capybara
• File: lib/capybara/minitest/spec.rb (279 lines)

Signature

module Capybara::Minitest::Expectations
  # Dynamically generated for each assertion:
  def must_have_selector(...)
  def wont_have_selector(...)
  def must_have_css(...)
  def wont_have_css(...)
  def must_have_xpath(...)
  def wont_have_xpath(...)
  def must_have_text(...)
  def wont_have_text(...)
  def must_have_content(...)
  def wont_have_content(...)
  def must_have_title(...)
  def wont_have_title(...)
  def must_have_current_path(...)
  def wont_have_current_path(...)
  def must_have_link(...)
  def wont_have_link(...)
  def must_have_button(...)
  def wont_have_button(...)
  def must_have_field(...)
  def wont_have_field(...)
  def must_have_select(...)
  def wont_have_select(...)
  def must_have_table(...)
  def wont_have_table(...)
  def must_have_checked_field(...)
  def wont_have_checked_field(...)
  def must_have_unchecked_field(...)
  def wont_have_unchecked_field(...)
  def must_have_ancestor(...)
  def must_have_sibling(...)
  def must_have_all_of_selectors(...)
  def must_have_none_of_selectors(...)
  def must_have_any_of_selectors(...)
  def must_match_style(...)
  def must_match_selector(...)
  def wont_match_selector(...)
  def must_match_xpath(...)
  def wont_match_xpath(...)
  def must_match_css(...)
  def wont_match_css(...)
  def must_have_style(...)  # deprecated, delegates to must_match_style
end

Import

require 'capybara/minitest/spec'

I/O Contract

Method Pattern	Input	Output	Side Effects
must_have_*(locator, **options)	Locator string or symbol, plus optional filters (e.g., :count, :wait, :text)	Returns true on success	Raises Minitest::Assertion on failure
wont_have_*(locator, **options)	Locator string or symbol, plus optional filters	Returns true on success	Raises Minitest::Assertion on failure
must_have_text(text, **options)	String or Regexp to match against page/node text	Returns true on success	Raises Minitest::Assertion on failure
must_have_title(title, **options)	String or Regexp to match against document title	Returns true on success	Raises Minitest::Assertion on failure
must_have_current_path(path, **options)	String or Regexp to match against current URL path	Returns true on success	Raises Minitest::Assertion on failure
must_match_style(styles)	Hash of CSS property/value pairs	Returns true on success	Raises Minitest::Assertion on failure

Usage Examples

require 'capybara/minitest/spec'

class MyFeatureTest < Minitest::Spec
  include Capybara::DSL

  it "displays the welcome message" do
    visit '/'
    page.must_have_content 'Welcome'
    page.must_have_title 'Home Page'
    page.must_have_current_path '/'
  end

  it "contains a login button" do
    visit '/login'
    page.must_have_button 'Sign In'
    page.wont_have_button 'Logout'
  end

  it "shows the navigation links" do
    visit '/'
    page.must_have_link 'About', href: '/about'
    page.must_have_css 'nav.main-nav'
    page.must_have_selector :css, '.header', count: 1
  end

  it "validates form fields" do
    visit '/profile'
    page.must_have_field 'Email'
    page.must_have_checked_field 'Subscribe'
    page.wont_have_unchecked_field 'Terms'
    page.must_have_select 'Country'
  end

  it "checks multiple selectors at once" do
    visit '/'
    page.must_have_all_of_selectors :css, '.header', '.footer', '.content'
    page.must_have_none_of_selectors :css, '.error', '.warning'
  end

  it "verifies element style" do
    visit '/'
    find('.alert').must_match_style(color: 'rgb(255, 0, 0)')
  end
end

Related Pages

• Teamcapybara_Capybara_Node_Matchers -- The underlying matcher methods that expectations delegate to
• Teamcapybara_Capybara_Node_Document_Matchers -- Document-level matchers used for title expectations
• Teamcapybara_Capybara_Session_Matchers -- Session-level matchers used for current_path expectations
• Teamcapybara_Capybara_Minitest -- The parent Minitest assertion module
• Teamcapybara_Capybara_Node_Base -- Base node class that includes this module
• Teamcapybara_Capybara_Node_Simple -- Simple node class that includes this module
• Teamcapybara_Capybara_Session -- Session class that includes this module