Update README for broker stuff

Author: bsquizz

Diff for: README.md

@@ -1,50 +1,74 @@
 pact-python demo
 ================
 
-**NOTE:** This README needs to be updated since adding examples for the pact broker
-
-
 This simple client/server implementation demos how pact-python can be used for a contract test.
 
 Further reading about pact is at https://docs.pact.io/ or https://docs.pact.io/blogs-videos-and-articles
 
 It has 3 components:
-* `user-app.py` -- a simple flask app that has a REST endpoint for `/users/<name>` which returns a JSON representation of a user
-* `client.py` -- a simple client that gets a user from user-app.
-* `client-test.py` -- a set of test cases using pytest and pact-python to test a simple
+* `pact_python_demo/user-app.py` -- a simple flask app that has a REST endpoint for `/users/<name>` which returns a JSON representation of a user
+* `pact_python_demo/client.py` -- a simple client that gets a user from user-app.
+* `tests/test_client.py` -- a set of test cases using pytest and pact-python to test a simple
 contract between the client and server.
+* `broker/` -- contains docker-compose files for a pact broker server
 
-Install this with:
+Set up your virtual environment with:
 
 ```
 $ pip install pipenv
 $ pipenv install
 ```
 
+## Creating/validating pacts without the broker
+
 Enter your venv shell with:
 ```
 $ pipenv shell
 ```
 
 Run the test with:
 ```
-(venv) $ pytest client-test.py
+(venv) $ pytest
 ```
 
-You'll see a pact file is generated by this consumer test at `consumer-provider.json`
+You'll see a pact file is generated by this consumer test at `tests/userclientservice-userservice.json`
 
 Then, fire up your server-side app and verify the provider works as expected:
 ```
-(venv) $ python user-app.py
+(venv) $ python pact_python_demo/user-app.py
 (venv) $ pact-verifier --provider-base-url=http://localhost:5001 \
-            --pact-url=./consumer-provider.json \
+            --pact-url=tests/userclientservice-userservice.json \
             --provider-states-setup-url=http://localhost:5001/_pact/provider_states
 ```
 
+## Creating/validating pacts and publishing results to the pact broker
+Next, you can try incorporating the pact broker in this process:
+
+Start the broker server:
+```
+$ cd broker
+$ docker-compose up
+```
+It's accessible at http://127.0.0.1 with username 'pactbroker' and password 'pactbroker'
+
+
+To run the test, this time pushing the generated pact into the broker with version '0.1' of UserServiceClient, use:
+```
+(venv) $ pytest --update-pact 0.1
+```
+
+The `tests/conftest.py` adds this custom option, and `tests/test_client` has code in the `pact` fixture to upload to the broker if the command line option was passed.
+
+
+Then, you can validate the provider (UserService) and push the result to the broker by running `./verify_pact.sh 0.2` -- which runs the same `pact-verifier` command as above but has additional args for pulling the pact file from the broker (instead of getting the .json locally) and pushing the verification result to the broker.
+
+Log in to the broker and take a look at the matrix. You will see that UserClientService version 0.1 has been verified against UserService version 0.2
+
+
 How does this work?
 ===================
 
-The purpose of `client-test.py` is to simply verify that **if the server sends me what I'm expecting, MY client code behaves properly**. It is essentially a unit test to exercise your client code using a mocked server. Except in this case, the mock server is now a "pact mock provider". In the test, you have configured the mock provider server to respond to your client with certain data. This is the mock data to represent how you'd expect the provider to behave **given the proper state exists on the provider.** Using that mock data, you verify your client-side code works.
+The purpose of `test_client.py` is to simply verify that **if the server sends me what I'm expecting, MY client code behaves properly**. It is essentially a unit test to exercise your client code using a mocked server. Except in this case, the mock server is now a "pact mock provider". In the test, you have configured the mock provider server to respond to your client with certain data. This is the mock data to represent how you'd expect the provider to behave **given the proper state exists on the provider.** Using that mock data, you verify your client-side code works.
 
 Two tests were created to verify that my client behaves properly if: a) I get a 200OK response back w/ the json I'd expect to see, or b) I get a 404 back and I should be returning `None`