Set up working example of py wiremock (#59)

* Set up working example of py wiremock

This commit introduces a new "example" directory
that demonstrates how to use python-wiremock for
testing against a http service.

The idea behind this example is two fold.

1) provide some exspansive real world working examples
of using wiremock

2) develop a real world application using all of wiremocks features
to aid with e2e testing.

The example directory builds a few python services using fast api
which are built and run using docker. The two services Overview Service
and Products Service in the example app communicate with eachother via
http.  The test suite in the example app then demonstrates how to use
wiremock to stub responses from Products Service so that Overview
Service can be tested more easily without needing to run
Product Service.

Author: mikeywaites

.github/workflows/tests.yml

@@ -1,4 +1,4 @@
-name: Python Testing
+name: CI
 
 on:
   push:
@@ -7,7 +7,7 @@ on:
     branches: [master]
 
 jobs:
-  build:
+  unit-tests:
     runs-on: ubuntu-latest
 
     strategy:
@@ -31,4 +31,17 @@ jobs:
 
       - name: Test with pytest
         run: |
-          poetry run pytest
+          poetry run pytest tests/
+
+  integration-tests:
+    runs-on: ubuntu-latest
+    needs: [unit-tests]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Integration Tests
+        run: |
+          cd example/
+          docker-compose build overview_srv
+          docker-compose run overview_srv pytest --tb=short

example/.flake8

@@ -0,0 +1,5 @@
+[flake8]
+ignore = E203, E266, E501, W503, F403
+max-line-length = 88
+max-complexity = 18
+select = B,C,E,F,W,T4,B9

example/Dockerfile

@@ -0,0 +1,33 @@
+# vim: set filetype=Dockerfile:
+FROM python:3.11-slim-buster
+
+ENV POETRY_HOME="/opt/poetry" \
+    POETRY_VIRTUALENVS_CREATE=false \
+    POETRY_NO_INTERACTION=1
+
+# Prepend poetry and venv to path
+ENV PATH="$POETRY_HOME/bin:$VENV_PATH/bin:$PATH"
+
+RUN apt-get update && apt-get install --no-install-recommends -y curl default-jre-headless \
+    && curl -sSL https://install.python-poetry.org | python
+
+# Update poetry to latest version
+RUN poetry self update
+
+WORKDIR /app/example
+
+# Install dependencies
+COPY . /app
+COPY ./example/pyproject.toml ./example/poetry.lock /app/example/
+RUN poetry config virtualenvs.create false \
+    && poetry install --no-root --no-interaction --no-ansi
+
+
+# Copy the rest of the application code
+COPY ./example /app/example
+
+# Expose the port that the FastAPI app will listen on
+EXPOSE 5001
+EXPOSE 5002
+
+CMD ["python"]

example/README.md

@@ -0,0 +1,51 @@
+# Python Wiremock Example
+
+## Introduction
+
+This example code demonstrates usage of python wiremock. The example code demonstrates a fictional set of microservices
+where the `overview_service` depends on the display of products returned from the `products_service`.
+
+When the services are run normally the Overview service makes a request to the Products services and the list of
+products returned by the Product Service is displayed to the user.
+
+```
++-----------------+               +-----------------+
+| Overview Service|               | Products Service|
++-----------------+               +-----------------+
+        |                                  |
+        |         GET /products            |
+        |--------------------------------->|
+        |                                  |
+        |       List of products           |
+        |<---------------------------------|
+        |                                  |
+        |     Display products to user     |
+        |--------------------------------->|
+        |                                  |
+```
+
+When we are writing tests to ensure that the Overview Service works correctly, we do not want to have the overview service
+have to depend on real requests being made to the products services. This normally leads to the code being mocked, and other approaches that
+are hard to maintain and dont allow us to test the code closer to real world conditions.
+
+Ultimately, we want a real http request to happen under test conditions so that the tests and the code operate as if the products
+services is running and returning actual http responses. In tests we also need to be able to control what this system returns
+so that we can assert the code acts in certain ways when it gets certain responses from the server.
+
+This is what python-wiremock helps to solve.
+
+The example code demonstrates how to use python-wiremock to run a test server directly from our tests that give us
+full control over how the mock service should handle our requests. We can generate respones directly from the tests
+to allow us to write solid integration tests that dont involved mockig the code we're trying to test.
+
+## Running the tests
+
+To run the tests use docker-compose to create the necessary containers.
+
+`docker-compose run overview_srv pytest --tb=short`
+
+## How we use this example code base
+
+As well as serving as a working example of how to work with python wiremock, this example code base is also used as a "e2e" test suite of sorts.
+The docker-compose configuration bundles the python-wiremock code directly into the container so that we can actually iterate on changes against a
+real world example.

example/docker-compose.yml

@@ -0,0 +1,24 @@
+version: "3"
+
+services:
+  overview_srv:
+    build:
+      context: ../
+      dockerfile: example/Dockerfile
+    ports:
+      - "5001:5001"
+    volumes:
+      - ..:/app/
+      - .:/app/example/
+    command: uvicorn product_mock.overview_service:app --host=0.0.0.0 --port=5001
+
+  products_srv:
+    build:
+      context: ../
+      dockerfile: example/Dockerfile
+    ports:
+      - "5002:5002"
+    volumes:
+      - ..:/app/
+      - .:/app/example/
+    command: uvicorn product_mock.products_service:app --host=0.0.0.0 --port=5002