Capybara::Webmock

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, 127.0.0.1, *.lvh.me, and lvh.me are the only whitelisted domains. Custom domain support is a planned feature.

This gem currently supports Ruby on Rails applications with RSpec and Cucumber test suites, using the Selenium Firefox and Chrome drivers.

Installation

Add this line to your application's Gemfile:

gem 'capybara-webmock'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capybara-webmock

Usage

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(:suite) do
    Capybara::Webmock.start
  end

  config.after(:suite) do
    Capybara::Webmock.stop
  end
end

Or, your Cucumber configuration:

# features/support/env.rb

Capybara::Webmock.start

at_exit do
  Capybara::Webmock.stop
end

Then use the capybara_webmock JavaScript driver:

# Use Firefox Driver
Capybara.javascript_driver = :capybara_webmock

or:

# Use Chrome Driver
Capybara.javascript_driver = :capybara_webmock_chrome

# Use Poltergeist Driver
Capybara.javascript_driver = :capybara_webmock_poltergeist

NOTE: These are just two 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 127.0.0.1:9292

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

Capybara::Webmock.port_number = 8080

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hashrocket/capybara-webmock. 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.

License

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

---

About

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.