README.md

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.

This gem currently supports Ruby on Rails applications 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 via the command line:

$ 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(:each) do |example|
    if example.metadata[:type] == :feature
      Capybara::Webmock.start
    end
  end

  config.after(:suite) do
    Capybara::Webmock.stop
  end
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
# 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 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

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
end

You can provide extra hosts to be permitted past the proxy, but should be used carefully. This setting does not remove the default localhosts, but adds to them.

Capybara::Webmock.allowed_hosts = ["example.com", "sub.example.com"]

Development

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 rubygems.org with:

$ bundle exec rake release

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.