DEV Community

Germán Alberto Gimenez Silva
Germán Alberto Gimenez Silva

Posted on • Originally published at rubystacknews.com on

Getting Started with Capybara and Selenium for Web Testing

#programming #software #ruby #rails

Getting Started with Capybara and Selenium for Web Testing
Getting Started with Capybara and Selenium for Web Testing

May 12, 2025

In modern web development, automated testing is crucial to ensure application quality and stability. One of the most effective ways to test user interactions in a browser is with Capybara , a Ruby-based framework that provides a high-level API for simulating how users interact with a web application. Paired with Selenium , Capybara allows developers to write end-to-end tests that drive actual browsers like Firefox and Chrome.

This guide will walk you through the basics of using Capybara with Selenium, from installation to writing your first browser-driven test with RSpec.

🔍 Want to Deep Test Your Application Without a Doubt?

If you’re looking to level up your testing strategy and ensure your application works flawlessly, get in touch with us — we’re here to help!

Get In Touch

Why Use Capybara?

Article content
Why Use Capybara?

Capybara is described as an “acceptance test framework for web applications.” In practice, it provides a smart, intuitive DSL that abstracts the complexity of browser automation. Instead of dealing with raw HTML or brittle selectors, Capybara allows you to write tests that read like instructions for a manual QA tester.

Key benefits include:

  • Realistic user simulation with commands like visit, fill_in, and click_on.
  • Built-in waiting for asynchronous events like AJAX and JavaScript DOM updates.
  • Flexible element selection using visible text and CSS selectors.
  • Pluggable drivers , including Selenium for full-browser testing and headless options for CI environments.

While Selenium is powerful on its own, its raw interface is verbose and low-level. Capybara wraps this functionality in a Ruby-friendly syntax, dramatically improving developer productivity.

Installing Capybara and Selenium

To get started, you’ll need the following gems:


$ gem install capybara selenium-webdriver
Enter fullscreen mode Exit fullscreen mode

This installs the Capybara DSL and the Selenium WebDriver required to control browsers like Firefox or Chrome. Ensure you have Mozilla Firefox (or another compatible browser) installed locally.

Running Capybara from IRB

You can experiment with Capybara directly from the Ruby console:


require 'capybara'
Capybara.current_driver = :selenium
Capybara.visit('http://si.edu')
Enter fullscreen mode Exit fullscreen mode

Once you execute these commands, Capybara will launch Firefox and navigate to the Smithsonian Institution’s website. You can interact with the page using commands such as:

  • fill_in “Search”, with: ‘Wright Brothers’
  • find_button(“Go”).click
  • page.has_content?(“National Air and Space Museum”)

This hands-on experimentation is a great way to understand how Capybara interacts with real pages.

Writing a Test with RSpec and Capybara

Article content

To formalize your testing, let’s convert the interactive session into a proper RSpec spec:


# smithsonian_spec.rb
require 'capybara/rspec'

Capybara.current_driver = :selenium

if ENV['BROWSER'] == 'chrome'
  Capybara.register_driver :selenium do |app|
    Capybara::Selenium::Driver.new(app, browser: :chrome)
  end
elsif ENV['BROWSER'] == 'poltergeist'
  require 'capybara/poltergeist'
  Capybara.register_driver :poltergeist do |app|
    Capybara::Poltergeist::Driver.new(app, timeout: 60)
  end
  Capybara.current_driver = :poltergeist
end

RSpec.describe "si.edu", type: :feature do
  it "has a search feature" do
    visit 'http://si.edu'
    fill_in "Search", with: 'Wright Brothers'
    find_button('Go').click

    expect(page).to have_content('National Air and Space Museum')
    expect(page).to_not have_content('Marshmallows')
    expect(page).to have_selector('.keymatch_result a')

    page.find('.keymatch_result a').click
    expect(page).to have_content(
      'On December 17, 1903, at Kitty Hawk, North Carolina, the Wright Flyer became the first powered, heavier-than-air machine to achieve controlled, sustained flight with a pilot aboard.'
    )

    page.save_screenshot('wright-brothers.png')
  end
end
Enter fullscreen mode Exit fullscreen mode

To run this test:


$ rspec smithsonian_spec.rb
Enter fullscreen mode Exit fullscreen mode

You can also specify the browser to use:


$ BROWSER=chrome rspec smithsonian_spec.rb
$ BROWSER=poltergeist rspec smithsonian_spec.rb
Enter fullscreen mode Exit fullscreen mode

Headless Testing and CI

Using headless browsers like Poltergeist or Headless Chrome is ideal for continuous integration systems. They allow your specs to run without a GUI, saving resources and enabling tests to run on servers or containers without a display.

Best Practices and Caveats

While powerful, browser-based testing comes with its own set of considerations:

  • Test speed : Browser interactions are slow (2–3 seconds per test), so use them judiciously.
  • Fragile selectors : UI changes can break tests. Prefer stable selectors or use data attributes.
  • Black-box testing : Capybara tests what users see, not backend changes like database writes.
  • Environment setup : Ensure compatible browsers or drivers are installed on the test machine.

Conclusion

Capybara, especially when paired with Selenium, is a robust tool for full-stack integration testing. It enables realistic simulation of user interactions and provides helpful tools like automatic waits, flexible selectors, and multi-browser support. Whether you’re testing search forms or entire user flows, Capybara lets you write tests that are readable, reliable, and representative of real-world behavior.

The magic of watching your tests automatically control a browser never really goes away. Behind the scenes, Capybara and Selenium are orchestrating advanced automation — all while letting you focus on your app’s functionality, not its internals.

Article content

Top comments (0)