Skip to content

Commit

Permalink
feat(publish): publish pacts to a broker
Browse files Browse the repository at this point in the history 
Publish pacts to a broker, including tagging and basic authentication.
  • Loading branch information
@mefellows
mefellows committed Jun 10, 2016
1 parent d5df2e4 commit 7f64f9c
Show file tree
Hide file tree
Showing 6 changed files with 271 additions and 200 deletions.
42 changes: 42 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,45 @@ npm i -g cz-conventional-changelog
```

`git cz` to commit and commitizen will guide you.

## Developing

For full integration testing locally, Ruby 2.1.5 must be installed. Under the
hood, Pact Go bundles the
[Pact Mock Service](https://github.com/bethesque/pact-mock_service) and
[Pact Provider Verifier](https://github.com/pact-foundation/pact-provider-verifier)
projects to implement up to v2.0 of the Pact Specification. This is only
temporary, until [Pact Reference](https://github.com/pact-foundation/pact-reference/)
work is completed.

* Git clone https://github.com/pact-foundation/pact-go.git
* Run `make dev` to build the package and setup the Ruby 'binaries' locally

### Vendoring

We use [Govend](https://github.com/govend/govend) to vendor packages. Please ensure
any new packages are added to `vendor.yml` prior to patching.

## Integration Tests

Before releasing a new version, in addition to the standard (isolated) tests
we smoke test the key features against a running Daemon and Broker.

1. Start daemon:

```
go build .
./pact-go daemon
```

2. Start a broker

See [Pact Broker](https://github.com/bethesque/pact_broker#usage) for details.
Make sure you have basic auth setup so we can test authentication.

3. Run the integrated tests

```
cd dsl
PACT_INTEGRATED_TESTS=1 PACT_BROKER_USERNAME="pactuser" PACT_BROKER_PASSWORD="pactpassword" PACT_BROKER_HOST="http://pactbroker" go test -run TestPact_Integration
```
201 changes: 104 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,27 @@ how to get going.
[![Go Report Card](https://goreportcard.com/badge/github.com/pact-foundation/pact-go)](https://goreportcard.com/report/github.com/pact-foundation/pact-go)
[![GoDoc](https://godoc.org/github.com/pact-foundation/pact-go?status.svg)](https://godoc.org/github.com/pact-foundation/pact-go)

## Table of Contents
<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:1 -->

1. [Table of Contents](#table-of-contents)
2. [Installation](#installation)
3. [Running](#running)
1. [Consumer](#consumer)
1. [Matching (Consumer Tests)](#matching-consumer-tests)
2. [Provider](#provider)
3. [Publishing Pacts to a Broker and Tagging Pacts](#publishing-pacts-to-a-broker-and-tagging-pacts)
1. [Publishing from Go code](#publishing-from-go-code)
2. [Publishing from the CLI](#publishing-from-the-cli)
4. [Using the Pact Broker with Basic authentication](#using-the-pact-broker-with-basic-authentication)
5. [Output Logging](#output-logging)
4. [Contact](#contact)
5. [Documentation](#documentation)
6. [Roadmap](#roadmap)
7. [Contributing](#contributing)

<!-- /TOC -->

## Installation

* Download a [release](https://github.com/pact-foundation/pact-go/releases) for your OS.
Expand All @@ -45,7 +66,7 @@ DSLs communicate over a local (RPC) connection, and is transparent to clients.
*NOTE: The daemon is completely thread safe and it is normal to leave the daemon
running for long periods (e.g. on a CI server).*

### Example - Consumer
### Consumer
1. Start the daemon with `./pact-go daemon`.
1. `cd <pact-go>/examples`.
1. `go run consumer.go`.
Expand Down Expand Up @@ -94,7 +115,79 @@ func TestSomeApi(t *testing.T) {
}
```

### Example - Provider

#### 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:

```go
jumper := Like(`"jumper"`)
shirt := Like(`"shirt"`)
tag := EachLike(fmt.Sprintf(`[%s, %s]`, jumper, shirt), 2)
size := Like(10)
colour := Term("red", "red|green|blue")

match := formatJSON(
EachLike(
EachLike(
fmt.Sprintf(
`{
"size": %s,
"colour": %s,
"tag": %s
}`, size, colour, tag),
1),
1))
```

This example will result in a response body from the mock server that looks like:
```json
[
[
{
"size": 10,
"colour": "red",
"tag": [
[
"jumper",
"shirt"
],
[
"jumper",
"shirt"
]
]
}
]
]
```

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

*NOTE*: One caveat to note, is that you will need to use valid Ruby
[regular expressions](http://ruby-doc.org/core-2.1.5/Regexp.html) and double
escape backslashes.

Read more about [flexible matching](https://github.com/realestate-com-au/pact/wiki/Regular-expressions-and-type-matching-with-Pact).


### Provider

1. Start your Provider API:

Expand Down Expand Up @@ -155,24 +248,17 @@ Note that `PactURLs` is a list of local pact files or remote based
urls (e.g. from a
[Pact Broker](http://docs.pact.io/documentation/sharings_pacts.html)).

#### Using the Pact Broker with Basic authentication

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

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

See the `Skip()'ed` [integration tests](https://github.com/pact-foundation/pact-go/blob/master/dsl/pact_test.go)
for a more complete E2E example.

### Publishing Pacts to a Broker and Tag Pacts
### 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.

#### Publish from Go code
#### Publishing from Go code

```go
pact.PublishPacts(&types.PublishRequest{
Expand All @@ -185,7 +271,7 @@ pact.PublishPacts(&types.PublishRequest{
})
```

#### Publish from CLI
#### 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.
Expand All @@ -196,75 +282,13 @@ curl -v -XPUT \-H "Content-Type: application/json" \
http://your-pact-broker/pacts/provider/A%20Provider/consumer/A%20Consumer/version/1.0.0
```

### 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:

```go
jumper := Like(`"jumper"`)
shirt := Like(`"shirt"`)
tag := EachLike(fmt.Sprintf(`[%s, %s]`, jumper, shirt), 2)
size := Like(10)
colour := Term("red", "red|green|blue")

match := formatJSON(
EachLike(
EachLike(
fmt.Sprintf(
`{
"size": %s,
"colour": %s,
"tag": %s
}`, size, colour, tag),
1),
1))
```
### Using the Pact Broker with Basic authentication

This example will result in a response body from the mock server that looks like:
```json
[
[
{
"size": 10,
"colour": "red",
"tag": [
[
"jumper",
"shirt"
],
[
"jumper",
"shirt"
]
]
}
]
]
```

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

*NOTE*: One caveat to note, is that you will need to use valid Ruby
[regular expressions](http://ruby-doc.org/core-2.1.5/Regexp.html) and double
escape backslashes.
The following flags are required to use basic authentication when
publishing or retrieving Pact files to/from a Pact Broker:

Read more about [flexible matching](https://github.com/realestate-com-au/pact/wiki/Regular-expressions-and-type-matching-with-Pact).
* `BrokerUsername` - the username for Pact Broker basic authentication.
* `BrokerPassword` - the password for Pact Broker basic authentication.

### Output Logging

Expand All @@ -283,29 +307,12 @@ pact := &Pact{

* Twitter: [@pact_up](https://twitter.com/pact_up)
* Google users group: https://groups.google.com/forum/#!forum/pact-support
* Gitter: https://gitter.im/realestate-com-au/pact

## Documentation

Additional documentation can be found at the main [Pact website](http://pact.io) and in the [Pact Wiki](https://github.com/realestate-com-au/pact/wiki).

## Developing

For full integration testing locally, Ruby 2.1.5 must be installed. Under the
hood, Pact Go bundles the
[Pact Mock Service](https://github.com/bethesque/pact-mock_service) and
[Pact Provider Verifier](https://github.com/pact-foundation/pact-provider-verifier)
projects to implement up to v2.0 of the Pact Specification. This is only
temporary, until [Pact Reference](https://github.com/pact-foundation/pact-reference/)
work is completed.

* Git clone https://github.com/pact-foundation/pact-go.git
* Run `make dev` to build the package and setup the Ruby 'binaries' locally

### Vendoring

We use [Govend](https://github.com/govend/govend) to vendor packages. Please ensure
any new packages are added to `vendor.yml` prior to patching.

## Roadmap

The [roadmap](docs.pact.io/roadmap/) for Pact and Pact Go is outlined on our main website.
Expand Down
Loading

0 comments on commit 7f64f9c

Please sign in to comment.