Skip to content
Mock external requests for Capybara JavaScript drivers
Branch: master
Clone or download
Hashrocket Workstation
Hashrocket Workstation Bump version
Latest commit ede969e Feb 7, 2019

CircleCI Version


Mock external requests for Capybara JavaScript drivers.

Browser integration tests are expensive. We can mock external requests in our tests, but once a browser is involved, we lose control.

External JavaScript libraries, CDN's, images, analytics, and more can slow an integration test suite to a crawl.

Capybara::Webmock is a Rack proxy server that sits between your Ruby on Rails Selenium test suite and the Internet, blocking external requests.

Use of this gem can significantly speed up the test suite. No more waiting on irrelevant external requests.

localhost,, *, and are the only whitelisted domains.

This gem currently supports Ruby on Rails applications using the Selenium Firefox and Chrome drivers.


Add this line to your application's Gemfile:

gem 'capybara-webmock'

And then execute:

$ bundle

Or install it via the command line:

$ gem install capybara-webmock


In your spec/rails_helper.rb, add the following:

require 'capybara/webmock'

Then in your RSpec configuration:

# spec/spec_helper.rb

RSpec.configure do |config|
  config.before(:each) do |example|
    if example.metadata[:type] == :feature

  config.after(:suite) do

Then use the capybara_webmock JavaScript driver:

# Use Firefox Driver
Capybara.javascript_driver = :capybara_webmock


# Use Chrome Driver
Capybara.javascript_driver = :capybara_webmock_chrome
# or Chrome Driver in headless mode
Capybara.javascript_driver = :capybara_webmock_chrome_headless
# Use Poltergeist Driver
Capybara.javascript_driver = :capybara_webmock_poltergeist

NOTE: These are just some default driver wrappers this gem provides. If you are already using a custom driver profile you can still use capybara-webmock, you just need to configure proxy settings to

By default the proxy server runs on port 9292, but this can be customized with the following configuration:

Capybara::Webmock.port_number = 8080

During each test, you can inspect the list of proxied requests:

it 'makes a request to /somewhere when the user visits the page' do
  visit "/some-page"
  expect(Capybara::Webmock.proxied_requests.any?{|req| req.path == "/somewhere" }).to be


After pulling down the repo, install dependencies:

$ bin/setup

Then, run the tests:

$ rake spec

For an interactive prompt that will allow you to experiment, run:

$ bin/console

To install your development gem onto your local machine, run:

$ bundle exec rake install

To release a new version, update the version number in version.rb, then update the git tag, push commits and tags, and publish the gem to with:

$ bundle exec rake release


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.


Hashrocket logo

Capybara::Webmock is supported by the team at Hashrocket, a multidisciplinary design and development consultancy. If you'd like to work with us or join our team, don't hesitate to get in touch.

You can’t perform that action at this time.