feat: add docs and nock example

Author: mefellows

Makefile

@@ -130,3 +130,10 @@ travis_encrypt_pact_broker_token:
 
 .env:
 	touch .env
+
+output:
+	mkdir -p ./pacts
+	touch ./pacts/tmp
+
+clean: output
+	rm pacts/*

README.md

@@ -8,18 +8,44 @@
 
 This is an example of a Node consumer using Pact to create a consumer driven contract, and sharing it via [Pactflow](https://pactflow.io).
 
-It is using a public tenant on Pactflow, which you can access [here](https://test.pact.dius.com.au) using the credentials `dXfltyFMgNOFZAxr8io9wJ37iUpY42M`/`O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1`. The latest version of the Example Consumer/Example Provider pact is published [here](https://test.pact.dius.com.au/pacts/provider/pactflow-example-provider/consumer/pactflow-example-consumer/latest).
+It implements a "Product" website, to demonstrate the new bi-directional contract capability of Pactflow (previously referred to as Provider driven contracts, or collaborative contracts). See the [Provider](https://github.com/pactflow/example-collaborative-contracts-provider) counterpart.
 
-The project uses a Makefile to simulate a very simple build pipeline with two stages - test and deploy.
 
-* Test
-  * Run tests (including the pact tests that generate the contract)
-  * Publish pacts, tagging the consumer version with the name of the current branch
-  * Check if we are safe to deploy to prod (ie. has the pact content been successfully verified)
-* Deploy (only from master)
-  * Deploy app (just pretend for the purposes of this example!)
-  * Tag the deployed consumer version as 'prod'
+It is using a public tenant on Pactflow, which you can access [here](https://test.pact.dius.com.au) using the credentials `dXfltyFMgNOFZAxr8io9wJ37iUpY42M`/`O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1`. The latest version of the Example Consumer/Example Provider pact is published [here](https://test.pact.dius.com.au/pacts/provider/pactflow-example-collaborative-contracts-provider/consumer/pactflow-example-consumer/latest).
 
+In the following diagram, you can see how the consumer testing process works - it's the same as the current Pact process! (We do show an alternative using Nock's record/replay functionality)
+
+When we call "can-i-deploy" the cross-contract validation process kicks off on Pactflow, to ensure any consumer consumes a valid subset of the OAS for the provider.
+
+![Consumer Test](docs/consumer-scope.png "Consumer Test")
+
+When you run the CI pipeline (see below for doing this), the pipeline should perform the following activities (simplified):
+
+![Consumer Pipeline](docs/consumer-pipeline.png "Consumer Pipeline")
+
+## Pre-requisites
+
+**Software**:
+
+* Tools listed at: https://docs.pactflow.io/docs/workshops/ci-cd/set-up-ci/prerequisites/
+* A pactflow.io account with an valid [API token](https://docs.pactflow.io/docs/getting-started/#configuring-your-api-token)
+
+### Environment variables
+
+To be able to run some of the commands locally, you will need to export the following environment variables into your shell:
+
+* `PACT_BROKER_TOKEN`: a valid [API token](https://docs.pactflow.io/docs/getting-started/#configuring-your-api-token) for Pactflow
+* `PACT_BROKER_BASE_URL`: a fully qualified domain name with protocol to your pact broker e.g. https://testdemo.pactflow.io
+* `PACT_PROVIDER=collaborative-contracts-provider`: this changes the default provider
 ## Usage
 
-See the [Pactflow CI/CD Workshop](https://github.com/pactflow/ci-cd-workshop).
+### Pact use case
+
+* `make test` - run the pact test locally
+* `make fake_ci` - run the CI process locally
+
+### Nock (record/replay example)
+
+* `make clean` - ensure previous pacts are cleared
+* `make test_nock` - run the nock test locally
+* `make fake_ci_nock` - run the nock version of the CI process locally

docs/consumer-pipeline.png

@@ -5,7 +5,7 @@ const nockBack = require("nock").back;
 nockBack.fixtures = "fixtures";
 
 describe("API Nock Tests", () => {
-  test("nock recordings", (done) => {
+  test("nock replay tests", (done) => {
     // reuse the nock fixture
     nockBack(
       "nock.json",

docs/consumer-scope.png

@@ -1,13 +1,10 @@
 import { API } from "./api";
 import * as fs from "fs";
-import * as path from "path";
 
-//
 const nockBack = require("nock").back;
 nockBack.setMode("record");
 nockBack.fixtures = "fixtures"
 
-
 describe("API Nock Tests", () => {
   test("nock recordings", () => {
     // recording of the fixture