#webmock

Requests to external services during test runs can cause several issues:

Tests failing intermediately due to connectivity issues.

Dramatically slower test suites.

Hitting API rate limits on 3rd party sites (e.g. Twitter).

Service may not exist yet (only documentation for it).

Service doesn't have a sandbox or staging server.

When integrating with external services we want to make sure our test suite isn’t hitting any 3rd party services. Our tests should run in isolation.

Disable all remote connections

We'll use Webmock, a gem which helps to stub out external HTTP requests. In this example we’ll search the GitHub API for contributors to the FactoryGirl repository.

First, let’s make sure our test suite can't make external requests by disabling them in our spec_helper.rb:

# spec/spec_helper.rb require 'webmock/rspec' WebMock.disable_net_connect!(allow_localhost: true)

Now let's verify that any external requests will raise an exception and break the build:

# spec/features/external_request_spec.rb require 'spec_helper' feature 'External request' do it 'queries FactoryGirl contributors on Github' do uri = URI('https://api.github.com/repos/thoughtbot/factory_girl/contributors') response = Net::HTTP.get(uri) expect(response).to be_an_instance_of(String) end end

As expected we now see errors when external requests are made:

$ rspec spec/features/external_request_spec.rb F Failures: 1) External request queries FactoryGirl contributors on Github Failure/Error: response = Net::HTTP.get(uri) WebMock::NetConnectNotAllowedError: Real HTTP connections are disabled. Unregistered request: GET https://api.github.com/repos/thoughtbot/factory_girl/contributors with headers {'Accept'=>'*/*', 'Accept-Encoding'=>'gzip;q=1.0,deflate;q=0.6,identity;q=0.3', 'Host'=>'api.github.com', 'User-Agent'=>'Ruby'} You can stub this request with the following snippet: stub_request(:get, "https://api.github.com/repos/thoughtbot/factory_girl/contributors"). with(:headers => {'Accept'=>'*/*', 'Accept-Encoding'=>'gzip;q=1.0,deflate;q=0.6,identity;q=0.3', 'Host'=>'api.github.com', 'User-Agent'=>'Ruby'}). to_return(:status => 200, :body => "", :headers => {}) ============================================================ # ./spec/features/external_request_spec.rb:8:in `block (2 levels) in <top (required)>' Finished in 0.00499 seconds 1 example, 1 failure

We can fix this by stubbing any requests to api.github.com with Webmock, and returning pre-defined content.

# spec/spec_helper.rb RSpec.configure do |config| config.before(:each) do stub_request(:get, /api.github.com/). with(headers: {'Accept'=>'*/*', 'User-Agent'=>'Ruby'}). to_return(status: 200, body: "stubbed response", headers: {}) end end

Run the test again and now it will pass.

$ rspec spec/features/external_request_spec.rb . Finished in 0.01116 seconds 1 example, 0 failures

VCR

Another approach for preventing external requests is to record a live interaction and ‘replay’ it back during tests. The VCR gem has a concept of cassettes which will record your test suites outgoing HTTP requests and then replay them for future test runs.

Considerations when using VCR:

Communication on how cassettes are shared with other developers.

Needs the external service to be available for first test run.

Difficult to simulate errors.

We'll go a different route and create a fake version of the GitHub service.

Create a Fake (Hello Sinatra!)

When your application depends heavily on a third party service, consider building a fake service inside your application with Sinatra. This will let us run full integration tests in total isolation, and control the responses to our test suite.

First we use Webmock to route all requests to our Sinatra application, FakeGitHub.

# spec/spec_helper.rb RSpec.configure do |config| config.before(:each) do stub_request(:any, /api.github.com/).to_rack(FakeGitHub) end end

Next we'll create the FakeGitHub application.

# spec/support/fake_github.rb require 'sinatra/base' class FakeGitHub < Sinatra::Base get '/repos/:organization/:project/contributors' do json_response 200, 'contributors.json' end private def json_response(response_code, file_name) content_type :json status response_code File.open(File.dirname(__FILE__) + '/fixtures/' + file_name, 'rb').read end end

Download a sample JSON response and store it in a local file.

# spec/support/fixtures/contributors.json [ { "login": "joshuaclayton", "id": 1574, "avatar_url": "https://2.gravatar.com/avatar/786f05409ca8d18bae8d59200156272c?d=https%3A%2F%2Fidenticons.github.com%2F0d4f4805c36dc6853edfa4c7e1638b48.png", "gravatar_id": "786f05409ca8d18bae8d59200156272c", "url": "https://api.github.com/users/joshuaclayton", "html_url": "https://github.com/joshuaclayton", "followers_url": "https://api.github.com/users/joshuaclayton/followers", "following_url": "https://api.github.com/users/joshuaclayton/following{/other_user}", "gists_url": "https://api.github.com/users/joshuaclayton/gists{/gist_id}", "starred_url": "https://api.github.com/users/joshuaclayton/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/joshuaclayton/subscriptions", "organizations_url": "https://api.github.com/users/joshuaclayton/orgs", "repos_url": "https://api.github.com/users/joshuaclayton/repos", "events_url": "https://api.github.com/users/joshuaclayton/events{/privacy}", "received_events_url": "https://api.github.com/users/joshuaclayton/received_events", "type": "User", "site_admin": false, "contributions": 377 } ]

Update the test, and verify the expected stub response is being returned.

require 'spec_helper' feature 'External request' do it 'queries FactoryGirl contributors on Github' do uri = URI('https://api.github.com/repos/thoughtbot/factory_girl/contributors') response = JSON.load(Net::HTTP.get(uri)) expect(response.first['login']).to eq 'joshuaclayton' end end

Run the specs.

$ rspec spec/features/external_request_spec.rb . Finished in 0.04713 seconds 1 example, 0 failures

Voilà, all green! This now allows us to run a full integration test without ever having to make an external connection.

A few things to consider when creating a fake:

A fake version of a service can lead to additional maintenance overhead.

Your fake could get out of sync with the external endpoint.

Sinatra is a fantastic lightweight framework for building web services. We'll use it as the application framework for the HTTP endpoints in our Service Oriented Architecture.

The testing approach will be in-process, which means that the test suite is running in the same Ruby process as the web service. This eliminates the need to run an external HTTP web server.

Application structure

Unlike Rails, Sinatra isn't all that opinionated on how you set up your application (it has a few sensible defaults), which can lead to a lot of open questions on how to structure the application.

Here's the directory structure we'll use for our example application.

app/ app/models app/my_service.rb client/ client/lib/my_client.rb client/my_client.gemspec config/ spec/

Outside-in development with a Client Gem

For internal services we'll build a client gem directly into the project. With the client embedded in our codebase we can follow outside-in development cycles -- Features start with request specs from the client side, followed by the addition of end points to the service, and then unit tests within the application.

This allows the us to dogfood our client gem and bring it in as the first step of our development process.

To achieve this we need to configure a few things.

1. Set up the project gemfile to use a local copy of the client in test mode

Include the local client gem in test suite.

# Gemfile group :test do gem 'my_client', path: 'client' gem 'webmock' # ... end

2. Use webmock to send all http requests to the service

Instead of booting up a web server every time the test suite is run we'll mount the Sinatra service as a rack application with webmock.

This allows the client to talk directly to the mounted rack application without going through HTTP or a web server.

# spec/spec_helper.rb RSpec.configure do |config| config.include WebMock::API config.before(:each) do MyClient.base_url = 'http://www.example.com' stub_request(:any, /www.example.com/).to_rack(MyService) end end

3. Use the client in our request specs

Once MyService is mounted as a rack application we can use the client gem directly in our test suite.

# spec/requests/widget_management_spec.rb require 'spec_helper' describe "Widget management" do it "creates a Widget" do # set up fixture data if needed response = MyClient::Widget.create(widget_params) # assert expectations on the response end end

Private gem hosting

To use the client gem in other projects we can use a private gem hosting service like Gemfury. This allows us to include the client via gemfile in our other projects.

# Gemfile source 'https://[email protected]/me/' gem 'my_client' source 'https://rubygems.org # ...

Takeaways

Sinatra is great framework for creating lightweight web services.

Webmock allows us to test the client in-process against a rack application.

Use private gem hosting to distribute the shared client.

In the previous blog post, I demonstrated how to stub EM::HttpRequest calls using the built in EventMachine::MockHttpRequest module. While that is sufficient if you are sorely using EM::HttpRequest as your sole http client, it would mean refactoring the test code again if the client changes.

We want to make the stub calls as generic as possible so it is not tightly coupled to a specific http client implementation.

WebMock is the ideal library to utilise in this case. It is a http stubbing library that works with various popular Ruby Http clients including EM and Net::HTTP amongst others. It has a self explanatory interface and provides options to tailor your stub calls including setting request headers and body responses. In addition, it also allows you to match stub request calls based on regular expressions, which makes it even more flexible to adapt to your own test code if your application accesses various external API endpoints.

WebMock, by default, makes the external API request call so you would need to disable it using the following commands:

WebMock.disable_net_connect!

To re-enable it, simply use: WebMock.allow_net_connect! Since these commands may be used multiple times within your spec files, I tend to put them within methods inside spec_helper.rb

<script src="https://gist.github.com/790144.js"> </script>

The WebMock.reset! command clears the WebMock request registry so it treats each stub request call as a new request. This comes in useful when you want to test the number of times a particular request has been made using the following matcher: WebMock.should have_requested(:get,<my url>.once

The stub request need to be initiated before the actual call is made. It takes the following format: stub_request(METHOD,<URL>||<REGEXP>).with(<REQUEST BODY>).to_return(HASH OF OPTIONS such as body,status,headers)

For example:

<script src="https://gist.github.com/790149.js"> </script>

The syntax is self explanatory - thats the beauty of using WebMock. Essentially what the line above does is to stub out your request to @post_regexp which will be a url to your external api using the POST action; with the parameters of the request defined in the body hash ; and finally to return a hash of response which includes status code, header, and body.

You will need to include the stub call before making any actual requests else you will receive 'Request not registered errors in the console'. The reason this occurs is that within the WebMock gem, it keeps an internal hash of url requests and if its not stubbed out will attempt to make an actual request.

There are some pitfalls to avoid when using WebMock in my own experience:

Firstly, if you are running a local service such as a SOLR server, in your WebMock.disconnect call, you need to pass in 'allow_localhost => true' else WebMock will just register all your local calls to be unregistered.

Secondly, within autotests , you might have to stub out the same request twice from my own experience. Not sure if thats a configuration issue on my end or the way autotests work.

Thirdly, if you are using older versions of Rspec, you need to explicitly include the following into your spec_helper.rb file to use the matchers:

config.include WebMock::API config.include WebMock::Matchers