Plugin histories

Webrat: Ruby acceptance testing before Capybara

Plugin histories · By the Gemfile Review editorial team · Published 2026-10-24

Before Capybara and Rails system tests, Webrat was how many Rails developers wrote tests that clicked through their application like a user. It shaped the vocabulary still used today, then quietly stopped being developed.

What Webrat did

Webrat added a browser-like API to Rails integration tests. Instead of constructing HTTP requests by hand, you described what a user would do:

visit "/signup"
fill_in "Email", with: "ada@example.com"
fill_in "Password", with: "correct horse"
click_button "Create account"
assert_contain "Welcome"

Behind the scenes, Webrat parsed the returned HTML, found the form fields by their labels, names or ids, and submitted the form with the right parameters, all inside the Ruby process. There was no real browser, so tests were fast and needed nothing installed beyond Ruby. When JavaScript had to run, Webrat offered a Selenium mode that drove a real browser through the same API, plus adapters for Merb, Sinatra and Mechanize.

Webrat became a cornerstone of behaviour-driven development in Ruby. Cucumber's generated step definitions for Rails originally used it, which is why phrases such as When I fill in "Email" with "..." and And I press "Sign in" appear in so many old feature files.

Status

The Webrat repository belongs to GitHub user brynary. According to RubyGems.org, its last release is 0.7.3, published on 2 January 2011, and it never reached 1.0. It did not follow Rails beyond the 3.0 era, and its dependencies target Ruby versions long out of support. Webrat should not be used in any current application.

Why Capybara replaced it

Capybara appeared in 2009 with an API intentionally close to Webrat's, but with a different architecture: a single DSL on top of interchangeable drivers. The same test could run against Rack::Test (fast, no JavaScript), Selenium with a real browser, or other headless drivers, by changing one setting. Capybara also introduced automatic waiting for asynchronous content, which became essential as applications relied more on JavaScript. Cucumber's Rails integration switched to Capybara, and the community followed.

Rails itself adopted Capybara: system tests, added in Rails 5.1, are built on it, and the Rails generators create them for you. The system testing section of the Rails testing guide describes the current setup.

Migrating Webrat tests

Most Webrat steps translate directly; the main differences are in assertions and in scoping:

A few habits need attention during migration:

• Use Capybara's matchers, not raw strings. expect(page).to have_content waits for asynchronous content when a JavaScript driver is used; page.html.include? does not, and leads to flaky tests.
• Ambiguity is an error. Capybara raises if a locator matches several elements, where Webrat often picked the first. Fix this by making labels unique or by scoping with within.
• Old Cucumber web steps. The generic web_steps.rb file that early cucumber-rails generated was removed from later versions. Rewrite feature files in terms of user intent ("When I sign in as an admin") with step definitions that call Capybara, or move the scenarios to system tests.

Choosing a driver today

Rails system tests default to Selenium with a headless Chrome browser. Alternatives include Rack::Test for pages without JavaScript, which is the closest equivalent to Webrat's in-process approach and the fastest option, and Cuprite, which drives Chrome directly through the DevTools protocol without a separate WebDriver binary. Many teams use Rack::Test by default and switch to a browser driver only for tests tagged as needing JavaScript.

Legacy

Webrat's lasting contribution is its vocabulary. visit, fill_in, click_button and within survive almost unchanged in Capybara and therefore in every Rails system test written today. For the rest of the modern testing toolbox, see our guide to testing Rails applications.

Read next

More in Plugin histories

Category guides

Testing

The Rails testing toolbox in 2026: Minitest or RSpec, fixtures or FactoryBot, system tests with Capybara, shoulda-matchers, and what replaced Webrat, Spork and factory_girl.

Plugin histories

Spork

What Spork did for RSpec and Cucumber in the Rails 2 and 3 era, why it stopped at 1.0.0rc4, and how Spring, Bootsnap and parallel testing solve the same problem today.

Plugin histories

Authlogic

What Authlogic is, how its UserSession model works, its status in 2026 (still maintained, supporting Rails 7.2 to 8.1), and how it compares with Devise, Rodauth and the Rails 8 generator.