Golang version of Pact. Pact is a contract testing framework for HTTP APIs and non-HTTP asynchronous messaging systems.
Clone or download
Failed to load latest commit information.
.github chore(docs): improve video quality May 17, 2018
client fix(tests): fix deadlock for non-race tests Jul 14, 2018
command chore(build): bump version for next release Jul 13, 2018
dsl fix(match-float): differentiate float vs int in dsl.Match. Fixes #93 Jul 31, 2018
examples fix(message): include user-configurable timeout in Message Pact Jul 14, 2018
install feat(upgrade): upgrade to 1.54.1 of standalone CLI Jul 28, 2018
scripts chore(build): improve release script for new process May 20, 2018
types feat(message): tidy up Message interface May 20, 2018
utils fix(vet error) Oct 18, 2017
vendor feat(api): v1.x.x daemonless, v3 API 🎉 May 20, 2018
.codeclimate.yml chore(build): fix codeclimate configuration Jun 4, 2016
.gitignore feat(api): v1.x.x daemonless, v3 API 🎉 May 20, 2018
.travis.yml chore(build): migrate to dep and TravisCI May 17, 2018
CHANGELOG.md chore(release): release v1.0.0-beta.2 Jul 31, 2018
CONTRIBUTING.md feat(api): v1.x.x daemonless, v3 API 🎉 May 20, 2018
Dockerfile chore(dev): Bump up `docker-compose`, `golang` & `pact-ruby-standalon… Apr 16, 2018
Gopkg.lock chore(build): migrate to dep and TravisCI May 17, 2018
Gopkg.toml chore(build): migrate to dep and TravisCI May 17, 2018
LICENSE wip(pact): initial commit Jun 4, 2016
Makefile chore(build): add Goveralls reporting May 17, 2018
README.md chore(docs): fix link section Jul 10, 2018
RELEASING.md chore(build): add simple release script to generate release notes Nov 12, 2017
appveyor.yml chore(build): detect latest binaries for Windows build May 20, 2018
doc.go chore(docs): update getting started to be compatible with latest API May 22, 2018
docker-compose.yml chore(dev): Bump up `docker-compose`, `golang` & `pact-ruby-standalon… Apr 16, 2018
main.go chore(build): moved to pact-foundation repository Jun 4, 2016
wercker.yml chore(build): release tag during deploy Mar 31, 2018


Pact Go

Golang version of Pact. Pact is a contract testing framework for HTTP APIs and non-HTTP asynchronous messaging systems.

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.

Build Status Build status Coverage Status Go Report Card GoDoc slack


From the Pact website:

The Pact family of frameworks provide support for Consumer Driven Contracts testing.

A Contract is a collection of agreements between a client (Consumer) and an API (Provider) that describes the interactions that can take place between them.

Consumer Driven Contracts is a pattern that drives the development of the Provider from its Consumers point of view.

Pact is a testing tool that guarantees those Contracts are satisfied.

Read Getting started with Pact for more information for beginners.

Table of Contents


Version Stable Spec Compatibility Install
1.0.x Yes 2, 3* See installation
1.1.x No (alpha) 2, 3* 1.1.x alpha
0.x.x Yes Up to v2 0.x.x stable

* v3 support is limited to the subset of functionality required to enable language inter-operable Message support.


  1. Download the latest CLI tools of the standalone tools and ensure the binaries are on your PATH:
  2. Unzip the package into a known location, and ensuring the pact and other binaries in the bin directory are on the PATH.
  3. Run go get -d github.com/pact-foundation/pact-go to install the source packages

See below for how to automate this:

Go get

Since 1.x.x Pact is go-gettable, and uses tags for versioning, so dep ensure --add github.com/pact-foundation/pact-go@1.0.0-beta or go get gopkg.in/pact-foundation/pact-go.v1 is now possible.

See the Changelog for versions to pin to and their history.

Installation on *nix

The following will install pact binaries into /opt/pact/bin:

cd /opt
curl -fsSL https://raw.githubusercontent.com/pact-foundation/pact-ruby-standalone/master/install.sh | bash
export PATH=$PATH:/opt/pact/bin
go get -d github.com/pact-foundation/pact-go

Test the installation:

pact help

Using Pact

Pact supports synchronous request-response style HTTP interactions and has experimental support for asynchronous interactions with JSON-formatted payloads.

Pact Go runs as part of your regular Go tests.

HTTP API Testing

Consumer Side Testing

We'll run through a simple example to get an understanding the concepts:

  1. go get github.com/pact-foundation/pact-go
  2. cd $GOPATH/src/github.com/pact-foundation/pact-go/examples/
  3. go test -v -run TestConsumer.

The simple example looks like this:

package main

import (


// Example Pact: How to run me!
// 1. cd <pact-go>/examples
// 2. go test -v -run TestConsumer
func TestConsumer(t *testing.T) {

	// Create Pact client
	pact := &dsl.Pact{
		Consumer: "MyConsumer",
		Provider: "MyProvider",
	defer pact.Teardown()

	// Pass in test case
	var test = func() error {
		u := fmt.Sprintf("http://localhost:%d/foobar", pact.Server.Port)
		req, err := http.NewRequest("GET", u, strings.NewReader(`{"s":"foo"}`))

		// NOTE: by default, request bodies are expected to be sent with a Content-Type
		// of application/json. If you don't explicitly set the content-type, you
		// will get a mismatch during Verification.
		req.Header.Set("Content-Type", "application/json")
		if err != nil {
			return err
		if _, err = http.DefaultClient.Do(req); err != nil {
			return err

		return err

	// Set up our expected interactions.
		Given("User foo exists").
		UponReceiving("A request to get foo").
			Method:  "GET",
			Path:    dsl.String("/foobar"),
			Headers: dsl.MapMatcher{"Content-Type": "application/json"},
      Status:  200,
			Headers: dsl.MapMatcher{"Content-Type": "application/json"},
			Body:    dsl.Match(&Foo{})

	// Verify
	if err := pact.Verify(test); err != nil {
		log.Fatalf("Error on Verify: %v", err)

Provider API Testing

  1. go get github.com/pact-foundation/pact-go
  2. cd $GOPATH/src/github.com/pact-foundation/pact-go/examples/
  3. go test -v -run TestProvider.

Here is the Provider test process broker down:

  1. Start your Provider API:

    You need to be able to first start your API in the background as part of your tests before you can run the verification process. Here we create startServer which can be started in its own goroutine:

    func startServer() {
      mux := http.NewServeMux()
      lastName := "billy"
      mux.HandleFunc("/foobar", func(w http.ResponseWriter, req *http.Request) {
        w.Header().Add("Content-Type", "application/json")
        fmt.Fprintf(w, fmt.Sprintf(`{"lastName":"%s"}`, lastName))
        // Break the API by replacing the above and uncommenting one of these
        // w.WriteHeader(http.StatusUnauthorized)
        // fmt.Fprintf(w, `{"s":"baz"}`)
      // This function handles state requests for a particular test
      // In this case, we ensure that the user being requested is available
      // before the Verification process invokes the API.
      mux.HandleFunc("/setup", func(w http.ResponseWriter, req *http.Request) {
        var s *types.ProviderState
        decoder := json.NewDecoder(req.Body)
        if s.State == "User foo exists" {
          lastName = "bar"
        w.Header().Add("Content-Type", "application/json")
      log.Fatal(http.ListenAndServe(":8000", mux))

Note that the server has a /setup endpoint that is given a types.ProviderState and allows the verifier to setup any provider states before each test is run.

  1. Verify provider API

    You can now tell Pact to read in your Pact files and verify that your API will satisfy the requirements of each of your known consumers:

    func TestProvider(t *testing.T) {
      // Create Pact connecting to local Daemon
      pact := &dsl.Pact{
        Consumer: "MyConsumer",
        Provider: "MyProvider",
      // Start provider API in the background
      go startServer()
      // Verify the Provider with local Pact Files
      pact.VerifyProvider(t, types.VerifyRequest{
        ProviderBaseURL:        "http://localhost:8000",
        PactURLs:               []string{filepath.ToSlash(fmt.Sprintf("%s/myconsumer-myprovider.json", pactDir))},
        ProviderStatesSetupURL: "http://localhost:8000/setup",

The VerifyProvider will handle all verifications, treating them as subtests and giving you granular test reporting. If you don't like this behaviour, you may call VerifyProviderRaw directly and handle the errors manually.

Note that PactURLs may be a list of local pact files or remote based urls (e.g. from a Pact Broker).

See the Skip()'ed integration tests for a more complete E2E example.

Provider Verification

When validating a Provider, you have 3 options to provide the Pact files:

  1. Use PactURLs to specify the exact set of pacts to be replayed:

    pact.VerifyProvider(t, types.VerifyRequest{
    	ProviderBaseURL:        "http://myproviderhost",
    	PactURLs:               []string{"http://broker/pacts/provider/them/consumer/me/latest/dev"},
    	ProviderStatesSetupURL: "http://myproviderhost/setup",
    	BrokerUsername:         os.Getenv("PACT_BROKER_USERNAME"),
    	BrokerPassword:         os.Getenv("PACT_BROKER_PASSWORD"),
  2. Use PactBroker to automatically find all of the latest consumers:

    pact.VerifyProvider(t, types.VerifyRequest{
    	ProviderBaseURL:        "http://myproviderhost",
    	BrokerURL:              "http://brokerHost",
    	ProviderStatesSetupURL: "http://myproviderhost/setup",
    	BrokerUsername:         os.Getenv("PACT_BROKER_USERNAME"),
    	BrokerPassword:         os.Getenv("PACT_BROKER_PASSWORD"),
  3. Use PactBroker and Tags to automatically find all of the latest consumers:

    pact.VerifyProvider(t, types.VerifyRequest{
    	ProviderBaseURL:        "http://myproviderhost",
    	BrokerURL:              "http://brokerHost",
    	Tags:                   []string{"latest", "sit4"},
    	ProviderStatesSetupURL: "http://myproviderhost/setup",
    	BrokerUsername:         os.Getenv("PACT_BROKER_USERNAME"),
    	BrokerPassword:         os.Getenv("PACT_BROKER_PASSWORD"),

Options 2 and 3 are particularly useful when you want to validate that your Provider is able to meet the contracts of what's in Production and also the latest in development.

See this article for more on this strategy.

For more on provider states, refer to http://docs.pact.io/documentation/provider_states.html.

API with Authorization

Sometimes you may need to add things to the requests that can't be persisted in a pact file. Examples of these would be authentication tokens, which have a small life span. e.g. an OAuth bearer token: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42.

For this case, we have a facility that should be carefully used during verification - the ability to specificy custom headers to be sent during provider verification. The property to achieve this is CustomProviderHeaders.

For example, to have an Authorization header sent as part of the verification request, modify the VerifyRequest parameter as per below:

  pact.VerifyProvider(t, types.VerifyRequest{
    CustomProviderHeaders:  []string{"Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42"},

As you can see, this is your opportunity to modify\add to headers being sent to the Provider API, for example to create a valid time-bound token.

Important Note: You should only use this feature for things that can not be persisted in the pact file. By modifying the request, you are potentially modifying the contract from the consumer tests!

Publishing pacts to a Pact Broker and Tagging Pacts

Using a Pact Broker is recommended for any serious workloads, you can run your own one or use a hosted broker.

By integrating with a Broker, you get much more advanced collaboration features and can take advantage of automation tools, such as the can-i-deploy tool, which can tell you at any point in time, which component is safe to release.

See the Pact Broker documentation for more details on the Broker.

Publishing from Go code

p := Publisher{}
err := p.Publish(types.PublishRequest{
	PactURLs:	[]string{"./pacts/my_consumer-my_provider.json"},
	PactBroker:	"http://pactbroker:8000",
	ConsumerVersion: "1.0.0",
	Tags:		[]string{"latest", "dev"},

Publishing Provider Verification Results to a Pact Broker

If you're using a Pact Broker (e.g. a hosted one at pact.dius.com.au), you can publish your verification results so that consumers can query if they are safe to release.

It looks like this:

screenshot of verification result

You need to specify the following:

PublishVerificationResults: true,
ProviderVersion:            "1.0.0",

NOTE: You need to be already pulling pacts from the broker for this feature to work.

Publishing from the CLI

Use a cURL request like the following to PUT the pact to the right location, specifying your consumer name, provider name and consumer version.

curl -v \
  -X PUT \
  -H "Content-Type: application/json" \
  -d@spec/pacts/a_consumer-a_provider.json \

Using the Pact Broker with Basic authentication

The following flags are required to use basic authentication when publishing or retrieving Pact files to/from a Pact Broker:

  • BrokerUsername - the username for Pact Broker basic authentication.
  • BrokerPassword - the password for Pact Broker basic authentication.

Asynchronous API Testing

Modern distributed architectures are increasingly integrated in a decoupled, asynchronous fashion. Message queues such as ActiveMQ, RabbitMQ, SQS, Kafka and Kinesis are common, often integrated via small and frequent numbers of microservices (e.g. lambda).

Furthermore, the web has things like WebSockets which involve bidirectional messaging.

Pact now has experimental support for these use cases, by abstracting away the protocol and focussing on the messages passing between them.

For further reading and introduction into this topic, see this article and our example for a more detailed overview of these concepts.


A Consumer is the system that will be reading a message from a queue or some intermediary - like a Kinesis stream, websocket or S3 bucket - and be able to handle it.

From a Pact testing point of view, Pact takes the place of the intermediary and confirms whether or not the consumer is able to handle a request.

The following test creates a contract for a Dog API handler:

// 1 Given this handler that accepts a User and returns an error
userHandler := func(u User) error {
	if u.ID == -1 {
		return errors.New("invalid object supplied, missing fields (id)")

	// ... actually consume the message

	return nil

// 2 We write a small adapter that will take the incoming dsl.Message
// and call the function with the correct type
var userHandlerWrapper = func(m dsl.Message) error {
	return userHandler(*m.Content.(*User))

// 3 Create the Pact Message Consumer
pact := dsl.Pact {
	return dsl.Pact{
		Consumer:                 "PactGoMessageConsumer",
		Provider:                 "PactGoMessageProvider",

// 4 Write the consumer test, and call VerifyMessageConsumer
// passing through the function
func TestMessageConsumer_Success(t *testing.T) {
	message := pact.AddMessage()
		Given("some state").
		ExpectsToReceive("some test case").
			"id":   like(127),
			"name": "Baz",
			"access": eachLike(map[string]interface{}{
				"role": term("admin", "admin|controller|user"),
			}, 3),
    AsType(&User{}) // Optional

	pact.VerifyMessageConsumer(t, message, userHandlerWrapper)


  1. The API - a contrived API handler example. Expects a User object and throws an Error if it can't handle it.
    • In most applications, some form of transactionality exists and communication with a MQ/broker happens.
    • It's important we separate out the protocol bits from the message handling bits, so that we can test that in isolation.
  2. Creates the MessageConsumer class
  3. Setup the expectations for the consumer - here we expect a User object with three fields
  4. Pact will send the message to your message handler. If the handler does not error, the message is saved, otherwise the test fails. There are a few key things to consider:
    • The actual request body that Pact will invoke on your handler will be contained within a dsl.Message object along with other context, so the body must be retrieved via Content attribute. If you set Message.AsType(T) this object will be mapped for you. If you don't want Pact to perform the conversion, you may do so on the object (dsl.Message.Content) or on the raw JSON (dsl.Message.ContentRaw).
    • All handlers to be tested must be of the shape func(dsl.Message) error - that is, they must accept a Message and return an error. This is how we get around all of the various protocols, and will often require a lightweight adapter function to convert it.
    • In this case, we wrap the actual userHandler with userHandlerWrapper provided by Pact.

Provider (Producer)

A Provider (Producer in messaging parlance) is the system that will be putting a message onto the queue.

As per the Consumer case, Pact takes the position of the intermediary (MQ/broker) and checks to see whether or not the Provider sends a message that matches the Consumer's expectations.

	functionMappings := dsl.MessageProviders{
		"some test case": func(m dsl.Message) (interface{}, error) {
			fmt.Println("Calling provider function that is responsible for creating the message")
			res := User{
				ID:   44,
				Name: "Baz",
				Access: []AccessLevel{
					{Role: "admin"},
					{Role: "admin"},
					{Role: "admin"}},

			return res, nil

	// Verify the Provider with local Pact Files
	pact.VerifyMessageProvider(t, types.VerifyMessageRequest{
		PactURLs: []string{filepath.ToSlash(fmt.Sprintf("%s/pactgomessageconsumer-pactgomessageprovider.json", pactDir))},
	}, functionMappings)


  1. Our API client contains a single function createDog which is responsible for generating the message that will be sent to the consumer via some message queue
  2. We configure Pact to stand-in for the queue. The most important bit here is the handlers block
    • Similar to the Consumer tests, we map the various interactions that are going to be verified as denoted by their description field. In this case, a request for a dog, maps to the createDog handler. Notice how this matches the original Consumer test.
  3. We can now run the verification process. Pact will read all of the interactions specified by its consumer, and invoke each function that is responsible for generating that message.

Pact Broker Integration

As per HTTP APIs, you can publish contracts and verification results to a Broker.


In addition to verbatim value matching, we have 3 useful matching functions in the dsl package that can increase expressiveness and reduce brittle test cases.

Rather than use hard-coded values which must then be present on the Provider side, you can use regular expressions and type matches on objects and arrays to validate the structure of your APIs.

Matchers can be used on the Body, Headers, Path and Query fields of the dsl.Request type, and the Body and Headers fields of the dsl.Response type.

Matching on types

dsl.Like(content) tells Pact that the value itself is not important, as long as the element type (valid JSON number, string, object etc.) itself matches.

Matching on arrays

dsl.EachLike(content, min) - tells Pact that the value should be an array type, consisting of elements like those passed in. min must be >= 1. content may be a valid JSON value: e.g. strings, numbers and objects.

Matching by regular expression

dsl.Term(example, matcher) - tells Pact that the value should match using a given regular expression, using example in mock responses. example must be a string. *

NOTE: One caveat to note, is that you will need to use valid Ruby regular expressions and double escape backslashes.


Here is a more complex example that shows how all 3 terms can be used together:

	body :=
			"response": map[string]interface{}{
				"name": Like("Billy"),
        "type": Term("admin", "admin|user|guest"),
        "items": EachLike("cat", 2)

This example will result in a response body from the mock server that looks like:

  "response": {
    "name": "Billy",
    "type": "admin",
    "items": ["cat", "cat"]

Match common formats

Often times, you find yourself having to re-write regular expressions for common formats. We've created a number of them for you to save you the time:

method description
Identifier() Match an ID (e.g. 42)
Integer() Match all numbers that are integers (both ints and longs)
Decimal() Match all real numbers (floating point and decimal)
HexValue() Match all hexadecimal encoded strings
Date() Match string containing basic ISO8601 dates (e.g. 2016-01-01)
Timestamp() Match a string containing an RFC3339 formatted timestapm (e.g. Mon, 31 Oct 2016 15:21:41 -0400)
Time() Match string containing times in ISO date format (e.g. T22:44:30.652Z)
`ipIPv4Address Match string containing IP4 formatted address
IPv6Address() Match string containing IP6 formatted address
UUID() Match strings containing UUIDs

Auto-generate matchers from struct tags

Furthermore, if you isolate your Data Transfer Objects (DTOs) to an adapters package so that they exactly reflect the interface between you and your provider, then you can leverage dsl.Match to auto-generate the expected response body in your contract tests. Under the hood, Match recursively traverses the DTO struct and uses Term, Like, and EachLike to create the contract.

This saves the trouble of declaring the contract by hand. It also maintains one source of truth. To change the consumer-provider interface, you only have to update your DTO struct and the contract will automatically follow suit.


type DTO struct {
  ID    string    `json:"id"`
  Title string    `json:"title"`
  Tags  []string  `json:"tags" pact:"min=2"`
  Date  string    `json:"date" pact:"example=2000-01-01,regex=^\\d{4}-\\d{2}-\\d{2}$"`

then specifying a response body is as simple as:

	// Set up our expected interactions.
		Given("User foo exists").
		UponReceiving("A request to get foo").
			Method:  "GET",
			Path:    "/foobar",
			Headers: map[string]string{"Content-Type": "application/json"},
			Status:  200,
			Headers: map[string]string{"Content-Type": "application/json"},
			Body:    Match(DTO{}), // That's it!!!

The pact struct tags shown above are optional. By default, dsl.Match just asserts that the JSON shape matches the struct and that the field types match.

See dsl.Match for more information.

See the matcher tests for more matching examples.



Asynchronous APIs

Integrated examples

There are number of examples we use as end-to-end integration test prior to releasing a new binary, including publishing to a Pact Broker. To enable them, set the following environment variables

cd $GOPATH/src/github.com/pact-foundation/pact-go/examples
export PACT_BROKER_USERNAME="dXfltyFMgNOFZAxr8io9wJ37iUpY42M"
export PACT_BROKER_HOST="https://test.pact.dius.com.au"

Once these variables have been exported, cd into one of the directories containing a test and run go test -v .:


Splitting tests across multiple files

Pact tests tend to be quite long, due to the need to be specific about request/response payloads. Often times it is nicer to be able to split your tests across multiple files for manageability.

You have two options to achieve this feat:

  1. Set PactFileWriteMode to "merge" when creating a Pact struct:

    This will allow you to have multiple independent tests for a given Consumer-Provider pair, without it clobbering previous interactions.

    See this PR for background.

    NOTE: If using this approach, you must be careful to clear out existing pact files (e.g. rm ./pacts/*.json) before you run tests to ensure you don't have left over requests that are no longer relevent.

  2. Create a Pact test helper to orchestrate the setup and teardown of the mock service for multiple tests.

    In larger test bases, this can reduce test suite time and the amount of code you have to manage.

    See the JS example and related issue for more.

Output Logging

Pact Go uses a simple log utility (logutils) to filter log messages. The CLI already contains flags to manage this, should you want to control log level in your tests, you can set it like so:

pact := Pact{
	LogLevel: "DEBUG", // One of DEBUG, INFO, ERROR, NONE

Check if the CLI tools are up to date

Pact ships with a CLI that you can also use to check if the tools are up to date. Simply run pact-go install, exit status 0 is good, 1 or higher is bad.

Disable CLI checks to speed up tests

Pact relies on a number of CLI tools for successful operation, and it performs some pre-emptive checks during test runs to ensure that everything will run smoothly. This check, unfortunately, can add up if spread across a large test suite. You can disable the check by setting the environment variable PACT_DISABLE_TOOL_VALIDITY_CHECK=1 or specifying it when creating a dsl.Pact struct:

  DisableToolValidityCheck: true,

You can then check if the CLI tools are up to date as part of your CI process once up-front and speed up the rest of the process!

Re-run a specific provider verification test

Sometimes you want to target a specific test for debugging an issue or some other reason.

This is easy for the consumer side, as each consumer test can be controlled within a valid *testing.T function, however this is not possible for Provider verification.

But there is a way! Given an interaction that looks as follows (taken from the message examples):

	message := pact.AddMessage()
		Given("user with id 127 exists").
		ExpectsToReceive("a user").
			"id":   like(127),
			"name": "Baz",
			"access": eachLike(map[string]interface{}{
				"role": term("admin", "admin|controller|user"),
			}, 3),

and the function used to run provider verification is go test -run TestMessageProvider, you can test the verification of this specific interaction by setting two environment variables PACT_DESCRIPTION and PACT_PROVIDER_STATE and re-running the command. For example:

cd examples/message/provider
PACT_DESCRIPTION="a user" PACT_PROVIDER_STATE="user with id 127 exists" go test -v .


Join us in slack: slack



Additional documentation can be found at the main Pact website and in the Pact Wiki.


The roadmap for Pact and Pact Go is outlined on our main website. Detail on the native Go implementation can be found here.