Guide · Open source

How to use Capybara: setup, drivers and writing your first test

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Capybara is a Ruby library for writing acceptance tests for web applications. It simulates how a real user clicks buttons, fills in fields and reads the page, so your tests check behavior rather than internal code. This guide shows you how to install it, connect it to RSpec, Cucumber, Minitest or Test::Unit, and pick a driver. By the end you will be able to write a simple sign-in test.

Capybarateamcapybara/capybara · ★ 10.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Ruby 3.0.0 or later and Bundler installed.
2Add the gem. Add gem 'capybara' to your Gemfile.
3Install dependencies. Run bundle install in your project directory.
4Require the integration. Require capybara/rails for Rails, set Capybara.app for Rack, or require capybara/rspec for RSpec.
5Write a feature test. Visit a page, fill in fields, click a button and assert on the page content.
6Pick a driver. Use the default Rack::Test driver for speed, or js: true or driver: :selenium for a real browser.

What you need before installing Capybara

Capybara requires Ruby 3.0.0 or later and Bundler to manage your gems. It is installed as a gem, so it fits into any project that already uses a Gemfile.

Ruby 3.0.0 or later
Bundler

Install Capybara with Bundler

Add the gem to your Gemfile, then install your dependencies. Capybara works out of the box with Rails and Rack applications.

gem 'capybara'

bundle install

Connect Capybara to your app and test framework

For a Rails app, require capybara/rails in your test helper file. For a Rack app that is not Rails, set Capybara.app to your Rack app. If you use RSpec, require capybara/rspec, typically in spec_helper.rb. Cucumber and Minitest have their own setup steps described in the official README.

If you test JavaScript or a remote URL, you will need a different driver. Capybara.server = :puma is suggested in the README until your setup is working.

Rails: require 'capybara/rails'
Rack (not Rails): Capybara.app = MyRackApp
RSpec: require 'capybara/rspec'

require 'capybara/rails'

Capybara.app = MyRackApp

require 'capybara/rspec'

Write your first user-style test

Tests read like the steps a user takes. In RSpec, tag the example group with type: :feature, visit a page, fill in fields, click a button and check the page content. Use within to limit actions to one part of the page.

Capybara waits for asynchronous work to finish, so you do not need to add manual waits in most cases.

visit moves to a path
fill_in fills a field by its label
click_button presses a button by its text
expect(page).to have_content checks the page

describe "the signin process", type: :feature do
  it "signs me in" do
    visit '/sessions/new'
    within("#session") do
      fill_in 'Email', with: 'user@example.com'
      fill_in 'Password', with: 'password'
    end
    click_button 'Sign in'
    expect(page).to have_content 'Success'
  end
end

Choose a driver: headless or real browser

Capybara is agnostic about the driver running your tests. The built-in Rack::Test driver is fast and headless. Selenium runs the same tests in a real browser. Tests need no changes to switch between them.

To run a single test with JavaScript, use js: true in RSpec. To pick a specific driver, pass driver: :selenium. WebKit is not built in; it is available only through an external gem.

Rack::Test: fast, headless, default for non-JavaScript tests
Selenium: real browser, used for JavaScript by default
WebKit: external gem only

describe 'some stuff which requires js', js: true do
  it 'will use the default js driver'
  it 'will switch to one specific driver', driver: :selenium
end

Learn the core DSL and synchronization

The DSL covers navigating, clicking links and buttons, interacting with forms, querying and finding elements, scoping, working with windows, modals and debugging. Selectors and matching rules help you find the right element when a page has similar ones.

Capybara's synchronization means your checks retry until the page matches, so asynchronous updates are handled for you.

Navigating and clicking links and buttons
Interacting with forms
Scoping with within
Selectors, matching and exactness

What people use it for

Testing a sign-in form in a Rails app with RSpec feature specs
Running the same checkout test headless in CI and in a real browser
Writing Cucumber scenarios that describe user steps in plain language
Checking that a Rack application renders expected content after a form submit

Frequently asked questions

Is Capybara free to use?

Capybara is released under the MIT licence, as listed in the project's details. The README also mentions an optional Patreon page for those who want to contribute financially to its maintenance.

What version of Ruby does Capybara need?

Capybara requires Ruby 3.0.0 or later. You also need Bundler to install dependencies with bundle install.

How do I install Capybara?

Add gem 'capybara' to your Gemfile, then run bundle install. The README describes this as the setup step.

Can Capybara test JavaScript?

Yes, but not with the default headless driver. The README says you need a different driver for JavaScript, such as Selenium, which runs tests in a real browser. In RSpec you can use js: true to switch.

Does Capybara support WebKit?

Not out of the box. The README says WebKit is supported only through an external gem.

What is the difference between Capybara and Selenium?

Capybara is a test library that describes user actions; it can use Selenium as one of its drivers. Selenium WebDriver is the browser automation layer, which Capybara uses to run tests in a real browser.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Capybara suits Ruby and Rails developers who write feature or system tests and want the same test code to run headless or in a real browser. If your team does not use Ruby, or you only need unit tests of internal code, pick a different tool such as Selenium WebDriver, Cypress, Playwright or Ferrum.

Install options & downloads