The highest tagged major version is v2.

pact-go

command module

v0.0.9 Latest Latest Go to latest Published: Sep 30, 2017 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/pact-foundation/pact-go

Links

Open Source Insights

README ¶

Pact Go

Golang version of Pact. 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.

Introduction

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 on how to get going.

Pact Go implements Pact Specification v2, including flexible matching.

Installation

Download one of the zipped release distributions for your OS.
Unzip the package into a known location, and rename pact-go_<os/arch> to pact-go and ensuring it is on the PATH.
Run pact-go to see what options are available.
Run go get -d github.com/pact-foundation/pact-go to install the source packages

Running

Pact Go runs a two-step process:

Run pact-go daemon in a separate process/shell. The Consumer and Provider DSLs communicate over a local (RPC) connection, and is transparent to clients.
Create your Pact Consumer/Provider Tests. It defaults to run on port 6666.

NOTE: The daemon is thread safe and it is normal to leave it running for long periods (e.g. on a CI server).

Consumer

Start the daemon with ./pact-go daemon.
go get github.com/pact-foundation/pact-go
cd $GOPATH/src/github.com/pact-foundation/pact-go/examples
cd <pact-go>/examples.
go run -v consumer.go.

Here is a simple example (consumer_test.go) you can run with go test -v .:

package somepackage

import (
	"fmt"
	"github.com/pact-foundation/pact-go/dsl"
	"net/http"
	"testing"
)

func TestLogin(t *testing.T) {

	// Create Pact, connecting to local Daemon
	// Ensure the port matches the daemon port!
	pact := dsl.Pact{
		Port:     6666,
		Consumer: "MyConsumer",
		Provider: "MyProvider",
	}
	// Shuts down Mock Service when done
	defer pact.Teardown()

	// Set up our interactions. Note we have multiple in this test case!
	pact.
		AddInteraction().
		Given("User Matt exists").           // Provider State
		UponReceiving("A request to login"). // Test Case Name
		WithRequest(dsl.Request{
			Method: "GET",
			Path:   "/login",
			Body: `{"username":"matt"}`,
		}).
		WillRespondWith(dsl.Response{
			Status: 200,
			Body: `{"username":"matt", "id":1234}`,
		})

	// Run the test and verify the interactions.
	if err := pact.Verify(func() error {
		u := fmt.Sprintf("http://localhost:%d/login", pact.Server.Port)
		req, err := http.NewRequest("GET", u, strings.NewReader(`{"username":"matt"}`))

		// 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 nil
	}); err != nil {
		t.Fatal(err)
	}

	// Write pact to file `<pact-go>/pacts/my_consumer-my_provider.json`
	pact.WritePact()
}

Matching (Consumer Tests)

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

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.
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.
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.

Example:

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

colour := Term("red", "red|green|blue")

match := EachLike(
              EachLike(
                         fmt.Sprintf(`{
                             "size": 10,
                             "colour": %s,
                             "tag": [["jumper", "shirt]]
                         }`, colour)
              1),
         1))

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

[
  [
    {
      "size": 10,
      "colour": "red",
      "tag": [
        [
          "jumper",
          "shirt"
        ],
        [
          "jumper",
          "shirt"
        ]
      ]
    }
  ]
]

See the matcher tests for more matching examples.

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

Provider

Start your Provider API:

mux := http.NewServeMux()
mux.HandleFunc("/setup", func(w http.ResponseWriter, req *http.Request) {
	w.Header().Add("Content-Type", "application/json")
})
mux.HandleFunc("/someapi", func(w http.ResponseWriter, req *http.Request) {
	w.Header().Add("Content-Type", "application/json")
	fmt.Fprintf(w, `
		[
			[
				{
					"size": 10,
					"colour": "red",
					"tag": [
						[
							"jumper",
							"shirt"
						],
						[
							"jumper",
							"shirt"
						]
					]
				}
			]
		]`)
})
go http.ListenAndServe(":8000", mux)

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

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:
```
response := pact.VerifyProvider(types.VerifyRequest{
	ProviderBaseURL:        "http://localhost:8000",
	PactURLs:               []string{"./pacts/my_consumer-my_provider.json"},		
	ProviderStatesSetupURL: "http://localhost:8000/setup",
})

if err != nil {
	t.Fatal("Error:", err)
}
```
Note that PactURLs is 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:

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

response = pact.VerifyProvider(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"),
})

Use PactBroker to automatically find all of the latest consumers:

response = pact.VerifyProvider(types.VerifyRequest{
	ProviderBaseURL:        "http://myproviderhost",
	BrokerURL:              "http://brokerHost",		
	ProviderStatesSetupURL: "http://myproviderhost/setup",
	BrokerUsername:         os.Getenv("PACT_BROKER_USERNAME"),
	BrokerPassword:         os.Getenv("PACT_BROKER_PASSWORD"),
})

Use PactBroker and Tags to automatically find all of the latest consumers:

response = pact.VerifyProvider(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. e


See the examples or read more at http://docs.pact.io/documentation/provider_states.html.

#### Publishing 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](https://cloud.githubusercontent.com/assets/53900/25884085/2066d98e-3593-11e7-82af-3b41a20af8e5.png)

You need to specify the following:

```go
PublishVerificationResults: true,
ProviderVersion:            "1.0.0",

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

Publishing Pacts to a Broker and Tagging Pacts

See the Pact Broker documentation for more details on the Broker and this article on how to make it work for you.

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 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 -XPUT \-H "Content-Type: application/json" \
-d@spec/pacts/a_consumer-a_provider.json \
http://your-pact-broker/pacts/provider/A%20Provider/consumer/A%20Consumer/version/1.0.0

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.

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:

Set PactFileWriteMode to "update" 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.
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
}

Examples

There is a single file, end-to-end integration test we use as a smoke test before releasing a new binary, including publishing to a broker, you can run it (after starting the daemon) as follows:

cd dsl
export PACT_INTEGRATED_TESTS=1
export PACT_BROKER_USERNAME="dXfltyFMgNOFZAxr8io9wJ37iUpY42M"
export PACT_BROKER_PASSWORD="O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1"
export PACT_BROKER_HOST="https://test.pact.dius.com.au"
go test -run TestPact_Integration

Other examples:

Contact

Twitter: @pact_up
Stack Overflow: stackoverflow.com/questions/tagged/pact
Gitter: https://gitter.im/realestate-com-au/pact
Gophers #pact Slack channel

Documentation

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

Troubleshooting

See TROUBLESHOOTING for some helpful tips/tricks.

Roadmap

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

Contributing

See CONTRIBUTING.

Documentation ¶

Overview ¶

Pact Go 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.

Consumer Tests ¶

Consumer side Pact testing is an isolated test that ensures a given component is able to collaborate with another (remote) component. Pact will automatically start a Mock server in the background that will act as the collaborators' test double.

This implies that any interactions expected on the Mock server will be validated, meaning a test will fail if all interactions were not completed, or if unexpected interactions were found:

A typical consumer-side test would look something like this:

func TestLogin(t *testing.T) {

	// Create Pact, connecting to local Daemon
	// Ensure the port matches the daemon port!
	pact := Pact{
		Port:     6666,
		Consumer: "My Consumer",
		Provider: "My Provider",
	}
	// Shuts down Mock Service when done
	defer pact.Teardown()

	// Pass in your test case as a function to Verify()
	var test = func() error {
		_, err := http.Get("http://localhost:8000/")
		return err
	}

	// Set up our interactions. Note we have multiple in this test case!
	pact.
		AddInteraction().
		Given("User Matt exists"). // Provider State
		UponReceiving("A request to login"). // Test Case Name
		WithRequest(Request{
			Method: "GET",
			Path:   "/login",
		}).
		WillRespondWith(Response{
			Status: 200,
		})

	// Run the test and verify the interactions.
	err := pact.Verify(test)
	if err != nil {
		t.Fatalf("Error on Verify: %v", err)
	}

	// Write pact to file
	pact.WritePact()
}

If this test completed successfully, a Pact file should have been written to ./pacts/my_consumer-my_provider.json containing all of the interactions expected to occur between the Consumer and Provider.

Matching ¶

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

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.
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.
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.

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

colour := Term("red", "red|green|blue")

match := EachLike(

     EachLike(
                fmt.Sprintf(`{
                    "size": 10,
                    "colour": %s,
                    "tag": [["jumper", "shirt]]
                }`, colour)
     1),
1))

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

[
  [
    {
      "size": 10,
      "colour": "red",
      "tag": [
        [
          "jumper",
          "shirt"
        ],
        [
          "jumper",
          "shirt"
        ]
      ]
    }
  ]
]

See the examples in the dsl package and the matcher tests (https://github.com/pact-foundation/pact-go/blob/master/dsl/matcher_test.go) for more matching examples.

NOTE: You will need to use valid Ruby regular expressions (http://ruby-doc.org/core-2.1.5/Regexp.html) and double escape backslashes.

Provider Tests ¶

Provider side Pact testing, involves verifying that the contract - the Pact file - can be satisfied by the Provider.

A typical Provider side test would like something like:

func TestProvider_PactContract(t *testing.T) {
// Create Pact, connecting to local Daemon
// Ensure the port matches the daemon port!
	pact := Pact{
		Port: 6666,
	}
	go startMyAPI("http://localhost:8000")

	err := pact.VerifyProvider(types.VerifyRequest{
		ProviderBaseURL:        "http://localhost:8000",
		PactURLs:               []string{"./pacts/my_consumer-my_provider.json"},
		ProviderStatesSetupURL: "http://localhost:8000/setup",
	})

	if err != nil {
		t.Fatal("Error:", err)
	}
}

Note that `PactURLs` can be a list of local pact files or remote based urls (possibly from a Pact Broker - http://docs.pact.io/documentation/sharings_pacts.html).

Pact reads the specified pact files (from remote or local sources) and replays the interactions against a running Provider. If all of the interactions are met we can say that both sides of the contract are satisfied and the test passes.

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:

response = pact.VerifyProvider(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:

response = pact.VerifyProvider(types.VerifyRequest{
	ProviderBaseURL:        "http://myproviderhost",
	BrokerURL:              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:

response = pact.VerifyProvider(types.VerifyRequest{
	ProviderBaseURL:        "http://myproviderhost",
	BrokerURL:              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](http://rea.tech/enter-the-pact-matrix-or-how-to-decouple-the-release-cycles-of-your-microservices/) for more on this strategy.

Provider States ¶

Each interaction in a pact should be verified in isolation, with no context maintained from the previous interactions. So how do you test a request that requires data to exist on the provider? Provider states are how you achieve this using Pact.

Provider states also allow the consumer to make the same request with different expected responses (e.g. different response codes, or the same resource with a different subset of data).

States are configured on the consumer side when you issue a dsl.Given() clause with a corresponding request/response pair.

Configuring the provider is a little more involved, and (currently) requires running an API endpoint to configure any [provider states](http://docs.pact.io/documentation/provider_states.html) during the verification process. The option you must provide to the dsl.VerifyRequest is:

ProviderStatesSetupURL: 	POST URL to set the provider state (see types.ProviderState)

An example route using the standard Go http package might look like this:

// Handle a request from the verifier to configure a provider state (ProviderStatesSetupURL)
mux.HandleFunc("/setup", func(w http.ResponseWriter, req *http.Request) {
  w.Header().Add("Content-Type", "application/json")

  // Retrieve the Provider State
  var state types.ProviderState

  body, _ := ioutil.ReadAll(req.Body)
  req.Body.Close()
  json.Unmarshal(body, &state)

  // Configure database for different states
  if state.State == "User A exists" {
    svc.userDatabase = aExists
  } else if state.State == "User A is unauthorized" {
    svc.userDatabase = aUnauthorized
  } else {
    svc.userDatabase = aDoesNotExist
  }
})

See the examples or read more at http://docs.pact.io/documentation/provider_states.html.

Publishing Pacts to a Broker and Tagging Pacts ¶

See the Pact Broker (http://docs.pact.io/documentation/sharings_pacts.html) documentation for more details on the Broker and this article (http://rea.tech/enter-the-pact-matrix-or-how-to-decouple-the-release-cycles-of-your-microservices/) on how to make it work for you.

Publishing using Go code:

pact.PublishPacts(types.PublishRequest{
	PactBroker:             "http://pactbroker:8000",
	PactURLs:               []string{"./pacts/my_consumer-my_provider.json"},
	ConsumerVersion:        "1.0.0",
	Tags:                   []string{"latest", "dev"},
})

Publishing from the CLI: