Capybara — Acceptance Testing Framework for Ruby Web Apps

Introduction

Capybara is a Ruby acceptance testing library that simulates how a real user interacts with a web application. It provides a clean DSL for visiting pages, filling in forms, clicking buttons, and asserting on page content, making end-to-end tests readable and maintainable.

What Capybara Does

• Simulates user actions like clicking, typing, and navigating in tests
• Provides a driver-agnostic API that works with Rack, Selenium, and headless browsers
• Automatically waits for asynchronous content to appear before assertions
• Scopes interactions to specific page sections with within blocks
• Integrates directly with RSpec, Minitest, and Cucumber

Architecture Overview

Capybara defines an abstract session interface and delegates actual browser interaction to pluggable drivers. The default Rack driver runs against your app in-process without a real browser. For JavaScript-heavy apps, the Selenium driver controls Chrome or Firefox. Each driver translates the Capybara DSL into the appropriate browser commands while the framework handles waiting, scoping, and synchronization.

Self-Hosting & Configuration

• Add capybara to your Gemfile and bundle install
• Set the default driver in your test helper (rack_test, selenium, or cuprite)
• Configure the app host and server port for remote testing
• Set default_max_wait_time to control how long Capybara waits for elements
• Register custom drivers for headless Chrome or specific browser profiles

Key Features

• Intuitive DSL that reads like plain English test steps
• Smart automatic waiting that eliminates manual sleep calls
• Multiple driver support from fast in-process to full browser testing
• Built-in matchers like have_content, have_selector, and have_field
• Session snapshots with save_and_open_page for debugging failures

Comparison with Similar Tools

• Selenium WebDriver (raw) — lower-level API without built-in waiting or DSL
• Playwright for Ruby — newer, supports more browsers but smaller Ruby ecosystem
• Cypress — JavaScript-only, different language ecosystem
• Watir — Ruby browser automation with a different API style
• SitePrism — page object layer that builds on top of Capybara

FAQ

Q: Does Capybara support JavaScript-rendered pages? A: Yes, when using the Selenium or Cuprite driver. The default Rack driver does not execute JavaScript.

Q: How does it handle AJAX waits? A: Capybara automatically retries assertions for up to default_max_wait_time seconds, so AJAX updates are handled without explicit sleeps.

Q: Can I run tests in headless mode? A: Yes. Register a headless Chrome or Firefox driver, or use the Cuprite driver which runs headless by default.

Q: Is it only for Rails? A: No. Capybara works with any Rack-compatible application, including Sinatra and Hanami. Remote apps can also be tested via a URL.

Sources

• https://github.com/teamcapybara/capybara
• https://rubydoc.info/github/teamcapybara/capybara