“Captain! All the integration tests have failed again! Could it be just another false negative?”
“Well, you just never know, Son. Fire all the torpedoes anyway”
I feel the way we do integration testing is sort of like driving your car from Melbourne to Sydney each time your mechanic makes a change to it. Or setting your house on fire to test your smoke alarm. It is excessive, tiresome and way too costly.
In a previous blog I talked about using the Pact gem to validate integration points in your architecture (see Testing interactions with web services without integration tests in ruby).
Since then Pact has improved a lot, and the original example was a bit contrived. Well, totally contrived. I thought it time to provide a more concrete example using the latest version of Pact.
What is Pact?
From the Pact website:
Enables consumer driven contract testing, providing a mock service and DSL for the consumer project, and interaction playback and verification for the service provider project.
Essentially, Pact provides a mechanism for creating a contract between a service consumer and a service provider, and then providing the tools to validate that the consumer and provider adhere to the contact independently of each other.
Pact, a tale of two parts – courtesy Bethany Skurrie
An example: Splitting out events to an Event Service
For one of our clients, we were required to create a RESTful Web API for customers to get a feed of events that have occurred in their web application. In this particular case, the web application was extremely large and complex, as we did not want to add more to it. We decided to create a new small service in Ruby that would house the API, and we would push events to it via HTTP as they occurred.
Event Architecture
The source system would do a POST request to an event resource URI, and this would create a new event in the event store. This new event would then be available via a feed to users of the API. The API would use a HMAC authentication scheme, and the events would be sent and stored in JSON format. For the Ruby HMAC library I used, refer to https://github.com/Asquera/warden-hmac-authentication.
Testing the interactions between the source system and the event API
The source system is a large web application that requires a lot of running components to function. And our new web API required a data store to store the events. We sure didn’t want to create a test environment with all of the services running in it just to make sure we haven’t broken the interaction between the two applications.
The Consumer
For this particular interaction, the consumer is the source system which is going to push the events to the event API. It will use a HTTP Client library (HTTParty in this case) to make the request and include all the necessary headers for HMAC authentication scheme. Here is a very simple version that posts a JSON version of an event and returns a boolean.
require 'httparty'
require 'hmac/signer'
require 'digest'
class SourceSystemClient
include HTTParty
base_uri 'http://events-service'
attr_reader :hmac_secret
def save_event(event)
json_body = event.to_json
response = self.class.post('/events', body: json_body, headers: hmac_headers(json_body))
response.code == 200
end
def hmac_headers(json_body)
hmac = HMAC.new
md5 = Digest::MD5.hexdigest json_body
now = Time.now
headers = { 'Content-Md5' => md5 }
signature => hmac.generate_signature(secret: @hmac_secret, method: 'POST', date: now, path: '/events', headers: headers)
headers.merge 'X-Hmac-Date' => now.httpdate, 'Authorization' => "HMAC #{signature}", 'Content-Type' => 'application/json'
end
endview rawclient.rb hosted with ❤ by GitHub
The event model looks something like this:
require 'securerandom'
class Event
attr_accessor :event_id, :timestamp, :host, :remote_address, :event_type, :user
def initialize
@event_id = SecureRandom.uuid
@timestamp = Time.now
end
def to_hash
{
eventId: @event_id,
timestamp: @timestamp.gmtime,
host: @host,
remoteAddress: @remote_address,
eventType: @event_type,
user: @user
}
end
endview rawevent.rb hosted with ❤ by GitHub
This event generates the following JSON (running on my laptop):
{
"eventId": "13ec9646-a33b-4319-a941-dbb924a60130",
"timestamp": "2014-05-13 01:06:38 UTC",
"host": "rholshausen.local",
"remoteAddress": "0:0:0:0:0:0:0:1%0",
"eventType": "LOGIN",
"user": "rholshausen"
}view rawevent.json hosted with ❤ by GitHub
The actual request that gets sent is:
POST /events HTTP/1.1
Content-Md5: CHEFLZW9taJ4sH6fxPN82Q==
X-Hmac-Date: Tue, 13 May 2014 01:21:17 GMT
Authorization: HMAC 1f5ca8529707d870bb993b10fd17ddf53971e4b4
Content-Type: application/json
Connection: close
Host: localhost:9292
Content-Length: 192
{"eventId":"13ec9646-a33b-4319-a941-dbb924a60130","timestamp":"2014-05-13 01:06:38 UTC","host":"rholshausen.local","remoteAddress":"0:0:0:0:0:0:0:1%0","eventType":"LOGIN","user":"rholshausen"}view rawexample post hosted with ❤ by GitHub
The Pact
We will start with the Consumer and create a Pact test which will define the contract between the source system and the RESTful web API. We’ll use the Pact DSL which integrates nicely into rspec. First we create a pact helper:
require 'pact/consumer/rspec' # Require the pact rspec helper
Pact.service_consumer "Source System" do # register a consumer with pact
has_pact_with "Event API" do # register the provider that has the pact
mock_service :event_api do # register the mock service that will run and pretend to be the provider
port 1234
end
end
endview rawpact_helper.rb hosted with ❤ by GitHub
When the spec runs, this will start a mock HTTP server listening on port 1234. The spec file follows:
require 'pact_helper'
require_relative '../lib/client'
require_relative '../lib/event'
describe SourceSystemClient, :pact => true do
before do
subject.class.base_uri 'http://localhost:1234'
end
describe 'a request to store an event' do
let(:event) { Event.new }
let(:event_json) { event.to_hash }
before do
event_api.upon_receiving('A POST request with an event').
with(method: :post, path: '/events', headers: {'Content-Type' => 'application/json'}, body: event_json).
will_respond_with(status: 200, headers: {'Content-Type' => 'application/json'})
end
it 'is successful' do
expect(subject.save_event(event)).to be_true
end
end
endview rawconsumer_spec.rb hosted with ❤ by GitHub
Running this test passes, and it generates a pact file of the interaction.
{
"provider": {
"name": "Event API"
},
"consumer": {
"name": "Source System"
},
"interactions": [
{
"description": "A POST request with an event",
"request": {
"method": "post",
"path": "/events",
"body": {
"eventId": "7622cb68-3ee5-4f93-a32b-da82f3ff95b5",
"timestamp": "2014-05-13 02:03:33 UTC",
"host": null,
"remoteAddress": null,
"eventType": null,
"user": null
},
"headers": {
"Content-Type": "application/json"
}
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
}
}
}
],
"metadata": {
"pactSpecificationVersion": "1.0.0"
}
}view rawpact.json hosted with ❤ by GitHub
The Provider
Our little Ruby web service is going to provide an event resource that can accept POST requests containing the events. It will validate the request and authenticate it using a HMAC scheme. We’re using Grape for the API and Warden HMAC gem for the HMAC verification . We will also use the ROAR gem for converting the JSON into an Event model.
require 'grape'
require 'models/event_repository'
require 'models/events_decorator'
require 'digest/md5'
class EventsApi < Grape::API
version 'v1', using: :accept_version_header
helpers do
def body_matches_content_md5(body)
content_md5 = request.env['HTTP_CONTENT_MD5']
body_md5 = Base64.encode64(Digest::MD5.digest(body)).chomp
body_md5 == content_md5
end
end
content_type :json, 'application/json'
default_format :json
parser :json, nil
# enable warden HMAC authentication
before do
env['warden'].authenticate! :scope => :hmac
end
desc 'singleEvent: Store a single Event'
post do
# Check that the MD5 for the body actually matches the header. This is important as the HMAC signature includes the MD5 checksum header, but the
# warden HMAC does not verify it matches the body
error!('Unauthorized - Content-MD5 header is required for POST', 401) unless body_matches_content_md5(env['api.request.body'])
event = Models::Event.new.extend(Models::EventDecorator).from_json(env['api.request.body'])
Models::EventRepository.instance.add_event(event)
end
endview rawprovider.rb hosted with ❤ by GitHub
We can now verify the pact file generated in our consumer test against our provider. Pact has a very convenient rake task to do this (see the section in Pact service provider project in the pact documentation). We just need to setup a helper in spec/service_consumers/pact_helper.rb to configure the verification task with the path to the pact file.
Running the pact verify task gives us two errors:
The second error is easy to fix. In our client we don’t actual expect a response body, only the success (200) HTTP code. So expecting a content type header is incorrect. We can fix that in our consumer pact test by removing the header. Also, a POST to a Grape API returns a 201, not a 200. So we should change that too.
The first error is due to the missing authentication headers, so we got an unauthenticated (401) response. We’ll need to add those to our consumer spec.
Getting the Pact tests to pass
I’ll update the client to expect a 201 instead of a 200.
require 'httparty'
require 'hmac/signer'
require 'digest'
require 'json'
class SourceSystemClient
include HTTParty
debug_output $stderr
base_uri 'http://localhost:9292'
attr_accessor :hmac_secret
def save_event(event)
json_body = JSON.generate(event.to_hash)
response = self.class.post('/events', body: json_body, headers: hmac_headers(json_body))
response.code == 201
end
def hmac_headers(json_body)
hmac = HMAC::Signer.new
md5 = Digest::MD5.base64digest json_body
now = Time.now
headers = { 'Content-Md5' => md5 }
signature = hmac.generate_signature(secret: @hmac_secret, method: 'POST', date: now.httpdate, path: '/events', headers: headers)
headers.merge 'X-Hmac-Date' => now.httpdate, 'Authorization' => "HMAC #{signature}", 'Content-Type' => 'application/json'
end
endview rawclient_updated.rb hosted with ❤ by GitHub
We just need to get the HMAC Authentication headers added to our consumer pact test. Our client class already calculates these headers, so they will be easy to add. Here is the updated spec:
require 'pact_helper'
require_relative '../lib/client'
require_relative '../lib/event'
describe SourceSystemClient, :pact => true do
let!(:now) { Time.now }
before do
subject.class.base_uri 'http://localhost:1234'
subject.hmac_secret = '01234567890'
Time.stub(:now).and_return(now)
end
describe 'posting an event to the event service' do
let(:event) { Event.new }
let(:event_json) { event.to_hash }
before do
event_api.upon_receiving('A POST request with an event').
with(method: :post, path: '/events', headers: subject.hmac_headers(JSON.generate(event_json)), body: event_json).
will_respond_with(status: 201)
end
it 'is successful' do
expect(subject.save_event(event)).to be_true
end
end
endview rawconsumer_spec_updated.rb hosted with ❤ by GitHub
Running this generates the following pact file:
{
"provider": {
"name": "Event API"
},
"consumer": {
"name": "Source System"
},
"interactions": [
{
"description": "A POST request with an event",
"request": {
"method": "post",
"path": "/events",
"headers": {
"Content-Md5": "QRYlWyL4AwKkqs2sfV6WBA==",
"X-Hmac-Date": "Tue, 13 May 2014 05:57:15 GMT",
"Authorization": "HMAC a59a8cb934fa910d62a61fd19bbfbb23ba1c4caa",
"Content-Type": "application/json"
},
"body": {
"eventId": "80573745-eaee-4e5e-8000-d0eb938c826b",
"timestamp": "2014-05-13 05:57:15 UTC",
"host": null,
"remoteAddress": null,
"eventType": null,
"user": null
}
},
"response": {
"status": 201
}
}
],
"metadata": {
"pactSpecificationVersion": "1.0.0"
}
} view rawupdated_pact.json hosted with ❤ by GitHub
Now, coping this latest pact over to the provider project and re-running the verification task, we get a success, Yay!
$ rake pact:verify
Using spec/service_consumers/pact_helper.rb
Verifying a pact between Source System and Event API
A post request with an event
returns a response which
has status code 201
Finished in 0.10356 seconds
1 example, 0 failuresview rawspec run pass hosted with ❤ by GitHub
In Conclusion
Instead of having to build a test environment running with two servers and databases to test that our interaction between our source system and our event API works, we now have two fast tests that achieve the same result. As long as we maintain the pact file between the two systems, we can be reasonably sure that our integration is working correctly.
There is a number of ways of maintaining the pact file. We can get our consumer build to publish the pact file to the CI server as a build artefact. The pact verification task supports loading the pact file from a URL. That way we can get it to always use the pact file from the latest successful build.
There is also a Pact Broker project that provides a repository of pact files. It allows you to be able to verify your providers against pact files from different versions of your consumer, statically check the compatibility of consumers and providers, and automate your CI and CD workflows.
NOTE: The Pact Broker is an open source tool that requires you to deploy, administer and host it yourself. If you would prefer a plug-and-play option, we’ve created Pactflow, a fully managed Pact Broker with additional features to simplify teams getting started and scaling with Pact and contract testing. You can get started quickly and for free on our Developer Plan