docs: split readme into multiple files

pact-foundation · Jun 14, 2021 · 0b2272c · 0b2272c
1 parent 7bd4e16
commit 0b2272c
Show file tree

Hide file tree

Showing 21 changed files with 1,329 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -35,17 +35,17 @@
 
 **Why use Pact?**
 
-Contract testing with Pact let's you:
+Contract testing with Pact lets you:
 
 - ⚡ Test locally
 - 🚀 Deploy faster
 - ⬇️ Reduce the lead time for change
 - 💰 Reduce the cost of API integration testing
 - 💥 Prevent breaking changes
 - 🔎 Understand your system usage
-- 📃 Get documentation for free
-- 🗄 No need for complex data fixtures
-- 🤷‍♂️ No need for complex test environments
+- 📃 Document your APIs for free
+- 🗄 Remove the need for complex data fixtures
+- 🤷‍♂️ Reduce the reliance on complex test environments
 
 </td>
 </tr>
@@ -55,12 +55,22 @@ Contract testing with Pact let's you:
 
 ## Documentation
 
-This readme offers an basic introduction to the library. The full documentation for Pact Go and the rest of the framework is available at https://docs.pact.io/
+This readme offers an basic introduction to the library. The full documentation for Pact Go and the rest of the framework is available at https://docs.pact.io/.
 
-- [Installation](https://docs.pact.io/LINK_HERE)
-- [Consumer Testing](https://docs.pact.io/LINK_HERE)
-- [Provider Testing](https://docs.pact.io/LINK_HERE)
-- [Event Driven Systems](https://docs.pact.io/LINK_HERE)
+- [Installation](#installation)
+- [Consumer Testing](./docs/consumer)
+- [Provider Testing](./docs/provider)
+- [Event Driven Systems](./docs/messages)
+- [Migration guide](./MIGRATION)
+- [Troubleshooting](./docs/troubleshooting)
+
+### Why Pact?
+
+Watch the [video series](https://www.youtube.com/playlist?list=PLwy9Bnco-IpfZ72VQ7hce8GicVZs7nm0i) on the problems with end-to-end integrated tests, and how contract testing can help.
+
+### Tutorial (60 minutes)
+
+Learn everything in Pact Go in 60 minutes: https://github.com/pact-foundation/pact-workshop-go
 
 ## Need Help
 
@@ -80,6 +90,8 @@ pact-go -l DEBUG install
 # 🚀 now write some tests!
 ```
 
+You can also keep the library versions up to date by running the `version.CheckVersion()` function.
+
 <details><summary>Manual Installation Instructions</summary>
 
 ### Manual
@@ -128,7 +140,7 @@ import (
 
 ### Consumer package
 
-The consumer interface is in the package: `github.com/pact-foundation/pact-go/v2/consumer`
+The consumer interface is in the package: `github.com/pact-foundation/pact-go/v2/consumer`.
 
 #### Writing a Consumer test
 
@@ -218,7 +230,7 @@ func TestV3HTTPProvider(t *testing.T) {
 
 | Version | Stable | [Spec] Compatibility | Install            |
 | ------- | ------ | -------------------- | ------------------ |
-| 2.0.x   | Yes    | 2, 3                 | See [installation] |
+| 2.0.x   | Beta   | 2, 3                 | See [installation] |
 | 1.0.x   | Yes    | 2, 3\*               | 1.x.x [1xx]        |
 | 0.x.x   | Yes    | Up to v2             | 0.x.x [stable]     |
 

diff --git a/docs/consumer.md b/docs/consumer.md
@@ -0,0 +1,185 @@
+# Consumer Tests
+
+## Contract Testing Process (HTTP)
+
+Pact is a consumer-driven contract testing tool, which is a fancy way of saying that the API `Consumer` writes a test to set out its assumptions and needs of its API `Provider`(s). By unit testing our API client with Pact, it will produce a `contract` that we can share to our `Provider` to confirm these assumptions and prevent breaking changes.
+
+The process looks like this:
+
+![diagram](./diagrams/summary.png)
+
+1. The consumer writes a unit test of its behaviour using a Mock provided by Pact
+1. Pact writes the interactions into a contract file (as a JSON document)
+1. The consumer publishes the contract to a broker (or shares the file in some other way)
+1. Pact retrieves the contracts and replays the requests against a locally running provider
+1. The provider should stub out its dependencies during a Pact test, to ensure tests are fast and more deterministic.
+
+In this document, we will cover steps 1-3.
+
+## Consumer package
+
+The consumer interface is in the package: `github.com/pact-foundation/pact-go/v2/consumer`.
+
+The two primary interfaces are `NewV2Pact` and `NewV3Pact`. If your provider is also V3 compatible, you can use the V3 variant, otherwise you should stick with V2.
+
+## Writing a Consumer test
+
+The purpose of a Pact test is to unit test the API Client of the consumer.
+
+In this example, we are going to be testing our Product API client, responsible for communicating with the `ProductAPI` over HTTP. It currently has a single method `GetProduct(id)` that will return a `*Product`.
+
+Pact tests have a few key properties. We'll demonstrate a common example using the 3A `Arrange/Act/Assert` pattern.
+
+Here is a sequence diagram that shows how a consumer test works:
+
+![diagram](./diagrams/workshop_step3_pact.svg)
+
+### Example
+
+```golang
+func TestProductAPIClient(t *testing.T) {
+	// Specify the two applications in the integration we are testing
+	// NOTE: this can usually be extracted out of the individual test for re-use)
+	mockProvider, err := NewV2Pact(MockHTTPProviderConfig{
+		Consumer: "ProductAPIConsumer",
+		Provider: "ProductAPI",
+	})
+	assert.NoError(t, err)
+
+	// Arrange: Setup our expected interactions
+	mockProvider.
+		AddInteraction().
+		Given("A Product with ID 10 exists").
+		UponReceiving("A request for Product 10").
+		WithRequest("GET", S("/product/10")).
+		WillRespondWith(200).
+		WithBodyMatch(&Product{})
+
+	// Act: test our API client behaves correctly
+	err = mockProvider.ExecuteTest(func(config MockServerConfig) error {
+		// Initialise the API client and point it at the Pact mock server
+		// Pact spins up a dedicated mock server for each test
+		client := newClient(config.Host, config.Port)
+
+		// Execute the API client
+		product, err := client.GetProduct("10")
+
+		// Assert: check the result
+		assert.NoError(t, err)
+		assert.Equal(t, 10, product.ID)
+
+		return err
+	})
+	assert.NoError(t, err)
+}
+```
+
+## Matching
+
+In addition to matching on exact values, there are a number of useful matching functions
+in the `matching` package that can increase expressiveness of your tests 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 request,
+and the `Body` and `Headers` on the response.
+
+_NOTE: Some matchers are only compatible with the V3 interface, and must not be used with a V2 Pact. Your test will panic if this is attempted_
+
+| Matcher                            | Min. Compatibility | Description                                                                                                                                                                                                                                                 |
+| ---------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Like(content)`                    | V2                 | Tells Pact that the value itself is not important, as long as the element _type_ (valid JSON number, string, object etc.) itself matches.                                                                                                                   |
+| `Term(example, matcher)`           | V2                 | Tells Pact that the value should match using a given regular expression, using `example` in mock responses. `example` must be a string.                                                                                                                     |
+| `EachLike(content, min)`           | V2                 | Tells Pact that the value should be an array type, consisting of elements like those passed in. `min` must be >= 1. `content` may be any valid JSON value: e.g. strings, numbers and objects.                                                               |
+| `Equality(content)`                | V3                 | Matchers cascade, equality resets the matching process back to exact values                                                                                                                                                                                 |
+| `Includes(content)`                | V3                 | Checks if the given string is contained by the actual value                                                                                                                                                                                                 |
+| `FromProviderState(expr, example)` | V3                 | Marks an item as to be dynamically injected from the provider state during provider verification                                                                                                                                                            |
+| `EachKeyLike(key, template)`       | V3                 | Object where the key itself is ignored, but the value template must match. Useful for dynamic keys.                                                                                                                                                         |
+| `ArrayContaining(variants)`        | V3                 | Allows heterogenous items to be matched within a list. Unlike EachLike which must be an array with elements of the same shape, ArrayContaining allows objects of different types and shapes. Useful for hypermedia responses such as Siron, HAL and JSONAPI |
+| `ArrayMinMaxLike(min, max`         | V3                 | Like EachLike except has a bounds on the max and the min                                                                                                                                                                                                    |
+| `ArrayMaxLike`                     | V3                 | Like EachLike except has a bounds on the max                                                                                                                                                                                                                |
+| `DateGenerated`                    | V3                 | Matches a cross platform formatted date, and generates a current date during verification                                                                                                                                                                   |
+| `TimeGenerated`                    | V3                 | Matches a cross platform formatted date, and generates a current time during verification                                                                                                                                                                   |
+| `DateTimeGenerated`                | V3                 | Matches a cross platform formatted datetime, and generates a current datetime during verification                                                                                                                                                           |
+
+### Matching by regular expression
+
+_Example:_
+
+Here is a more complex example that shows how all 3 terms can be used together:
+
+```go
+	body :=
+		Like(map[string]interface{}{
+			"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:
+
+```json
+{
+  "response": {
+    "name": "Billy",
+    "type": "admin",
+    "items": ["cat", "cat"]
+  }
+}
+```
+
+### Match common formats
+
+| method          | Min. Compatibility | description                                                                                     |
+| --------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
+| `Identifier()`  | V2                 | Match an ID (e.g. 42)                                                                           |
+| `Integer()`     | V3                 | Match all numbers that are integers (both ints and longs)                                       |
+| `Decimal()`     | V3                 | Match all real numbers (floating point and decimal)                                             |
+| `HexValue()`    | V2                 | Match all hexadecimal encoded strings                                                           |
+| `Date()`        | V2                 | Match string containing basic ISO8601 dates (e.g. 2016-01-01)                                   |
+| `Timestamp()`   | V2                 | Match a string containing an RFC3339 formatted timestamp (e.g. Mon, 31 Oct 2016 15:21:41 -0400) |
+| `Time()`        | V2                 | Match string containing times in ISO date format (e.g. T22:44:30.652Z)                          |
+| `IPv4Address()` | V2                 | Match string containing IP4 formatted address                                                   |
+| `IPv6Address()` | V2                 | Match string containing IP6 formatted address                                                   |
+| `UUID()`        | V2                 | 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 `WithBodyMatch(object)` option to auto-generate the expected response body in your contract tests. Under the hood, it 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.
+
+_Example:_
+
+```go
+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:
+
+```go
+	// Set up our expected interactions.
+	pact.
+		AddInteraction().
+    ...
+		WithBodyMatch(DTO{}), // That's it!!!
+```
+
+The `pact` struct tags shown above are optional. By default, it asserts that the JSON shape matches the struct and that the field types match.
+
+## Publishing Pacts to a Broker
+
+We recommend publishing the contracts to a Pact Broker (or https://pactflow.io) using the [CLI Tools]()https://docs.pact.io/implementation_guides/cli/#pact-cli.
+
+[Read more](https://docs.pact.io/pact_broker/publishing_and_retrieving_pacts/) about publishing pacts.
diff --git a/docs/diagrams/message-consumer.png b/docs/diagrams/message-consumer.png
diff --git a/docs/diagrams/message-provider.png b/docs/diagrams/message-provider.png
diff --git a/docs/diagrams/summary.png b/docs/diagrams/summary.png