Merge pull request #84 from wiremock/quickstart

Restructure examples + Create the quickstart example + Add examples to the website

Author: oleg-nenashev

.github/workflows/tests.yml

@@ -42,6 +42,6 @@ jobs:
 
       - name: Integration Tests
         run: |
-          cd example/
+          cd examples/
           docker-compose build overview_srv
           docker-compose run overview_srv pytest --tb=short

CONTRIBUTING.md

@@ -20,3 +20,12 @@ General Rules:
 Setup the project using poetry.
 
 `poetry install`
+
+## Contributing examples
+
+Please submit new examples as a pull requests to the [examples directory](./examples/).
+You can also also add links to external examples and tutorials to the `README.md`
+file in the directory.
+
+When adding new examples,
+make sure to update the [documentation site page](./docs/examples.md) too.

README.md

@@ -23,7 +23,7 @@ WireMock can run in unit tests, as a standalone process or a container. Key feat
 
 - [Testcontainers Python](https://github.com/testcontainers/testcontainers-python) module to easily start WireMock server for your tests
 - REST API Client for a standalone WireMock Java server
-- Supports most of the major [Wiremock](https://wiremock.org/docs) features (more on their way soon)
+- Support for most of ajor [WireMock features ](https://wiremock.org/docs) (more on their way soon)
 
 ## References
 
@@ -33,9 +33,9 @@ WireMock can run in unit tests, as a standalone process or a container. Key feat
 
 ## Examples
 
-There are several example projects included to demonstrate the different ways that wiremock can be used to mock
+There are several [example projects](./examples/) included to demonstrate the different ways that wiremock can be used to mock
 services in your tests and systems. The example test modules demonstrate different strategies for testing against
 the same "product service" and act as a good demonstration of real world applications to help you get started.
 
-- [Testcontainers Python](example/tests/test_testcontainers.py)
-- [Standalone Java Server Version](example/tests/test_java_server.py)
+- [Testcontainers Python](examples/intro/tests/test_testcontainers.py)
+- [Standalone Java Server Version](examples/intro/tests/test_java_server.py)

docs/examples.md

@@ -0,0 +1,17 @@
+# Python WireMock examples
+
+- [quickstart](https://github.com/wiremock/python-wiremock/tree/master/examples/quickstart) -
+  example for the[Quick Start Guide](./quickstart.md)
+- [intro](https://github.com/wiremock/python-wiremock/tree/master/examples/intro) -
+  End-to-End example for both Testcontainers module
+  and native `pytest` integration.
+
+## External examples
+
+No external examples are referenced at the moment.
+Please be welcome to [contribute]([./../CONTRIBUTING.md](https://github.com/wiremock/python-wiremock/blob/master/CONTRIBUTING.md))!
+
+## Contributing examples
+
+More examples are always welcome!
+See the [Contributor Guide]([./../CONTRIBUTING.md](https://github.com/wiremock/python-wiremock/blob/master/CONTRIBUTING.md)).

docs/quickstart.md

@@ -1,59 +1,98 @@
-Quickstart
-=====
+# Quickstart
 
 The preferred way of using WireMock to mock your services is by using the provided `WireMockContainer`
 that uses [testcontainers-python](https://github.com/testcontainers/testcontainers-python)
 and provisions WireMock as a test container on-demand.
 
-### Prerequisites
+In this example we will use the [pytest](https://docs.pytest.org/) framework.
+
+## Prerequisites
 
 - Python 3.7 or above
-- Pip 20.0.0 or above
+- Pip 20.0.0 or above (use `apt install python3-pip`, for example)
+- Pytest 7.3.0 or above (use `pip install pytest`)
+- Testcontainers 3.5.0 or above (use `pip install testcontainers`)
+
+## Install Python WireMock
 
-### Install Python WireMock
+To install the most recent version of the Python WireMock library,
+use the following command:
 
 ```bash
 pip install wiremock
 ```
 
-### Use Python WireMock
+## Create the Test Fixture
+
+As a first step, we will need to provision a test WireMock server to be used in tests:
+
+1. Create an empty `test.py` file
+2. In this file, create a pytest fixture to manage the container life-cycle.
+   Use fixture `scope` to control how often the container is created
+3. Set the WireMock SDK config URL to the URL exposed by the container.
+   It will route all Admin API requests to
+   the mock server.
+4. Create REST API stub mapping for the `/hello` endpoint using the Admin SDK.
 
 ```python
 import pytest
+import requests
 
 from wiremock.testing.testcontainer import wiremock_container
+from wiremock.constants import Config
+from wiremock.client import *
 
-@pytest.fixture(scope="session") # (1)
-def wm_server():
+@pytest.fixture # (1)
+def wiremock_server():
     with wiremock_container(secure=False) as wm:
-
         Config.base_url = wm.get_url("__admin") # (2)
-
         Mappings.create_mapping(
             Mapping(
                 request=MappingRequest(method=HttpMethods.GET, url="/hello"),
                 response=MappingResponse(status=200, body="hello"),
                 persistent=False,
             )
-        ) # (3)
+        ) # (3)      
         yield wm
+```
 
+## Write your first test with WireMock
 
-def test_get_hello_world(wm_server): # (4)
+Use the `wiremock_server` fixture in your tests and make requests against the mock server.
+Add the following test to the `test.py` file:
 
-    resp1 = requests.get(wm_server.get_url("/hello"), verify=False)
+```python
+def test_get_hello_world(wiremock_server): # (4)
+    response = requests.get(wiremock_server.get_url("/hello"))
 
-    assert resp1.status_code == 200
-    assert resp1.content == b"hello"
+    assert response.status_code == 200
+    assert response.content == b"hello"
 ```
 
-1. Create a pytest fixture to manage the container life-cycle. use fixture `scope` to control how often the container is created
+## Run the test!
+
+Run the following command:
 
-2. Set the wiremock sdk config url to the url exposed by the container
+```bash
+pytest test.py -v
+```
 
-3. Create response and request mappings using the Admin SDK.
+Sample output:
+
+```
+$ pytest test.py -v
+================ test session starts ================
+platform linux -- Python 3.8.10, pytest-7.4.0, pluggy-1.2.0 -- /usr/bin/python3
+cachedir: .pytest_cache
+rootdir: /c/Users/Oleg/Documents/opensource/wiremock/python-wiremock
+configfile: pyproject.toml
+plugins: anyio-3.7.1
+collected 1 item
+
+test.py::test_get_hello_world PASSED                                [100%]
+```
 
-4. Use the `wm_server` fixture in your tests and make requests against the mock server.
+## Read More
 
 You can read more about Testcontainers support in Python WireMock [here](./testcontainers.md).
 

docs/testcontainers.md

@@ -119,7 +119,7 @@ services:
   overview_srv:
     build:
       context: ../
-      dockerfile: example/Dockerfile
+      dockerfile: examples/intro/Dockerfile
     ports:
       - "5001:5001"
     environment:

examples/README.md

@@ -0,0 +1,15 @@
+# Python WireMock examples
+
+- [Quick Start Guide](./quickstart/)
+- [End-to-End Example](./intro/) for
+  both Testcontainers module and native
+  pytest integration.
+
+## External examples
+
+No external examples are referenced at the moment.
+Please be welcome to [contribute](./../CONTRIBUTING.md)!
+
+## Contributing
+
+Feel free to contribute the examples!

example/.flake8 renamed to examples/intro/.flake8

@@ -18,13 +18,13 @@ WORKDIR /app/example
 
 # Install dependencies
 COPY . /app
-COPY ./example/pyproject.toml ./example/poetry.lock /app/example/
+COPY ./examples/intro/pyproject.toml ./examples/intro/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
+COPY ./examples/intro /app/example
 
 # Expose the port that the FastAPI app will listen on
 EXPOSE 5001

example/Dockerfile renamed to examples/intro/Dockerfile

@@ -1,4 +1,4 @@
-# Python Wiremock Example
+# Python Wiremock End-to-End Example
 
 ## Introduction
 

example/README.md renamed to examples/intro/README.md

@@ -4,7 +4,7 @@ services:
   overview_srv:
     build:
       context: ../
-      dockerfile: example/Dockerfile
+      dockerfile: examples/intro/Dockerfile
     ports:
       - "5001:5001"
     environment:
@@ -20,7 +20,7 @@ services:
   products_srv:
     build:
       context: ../
-      dockerfile: example/Dockerfile
+      dockerfile: examples/intro/Dockerfile
     ports:
       - "5002:5002"
     volumes:

example/docker-compose.yml renamed to examples/intro/docker-compose.yml

@@ -0,0 +1,21 @@
+# Python WireMock - Quickstart
+
+This example shows using WireMock to mock your services is by using the provided `WireMockContainer`
+that uses [testcontainers-python](https://github.com/testcontainers/testcontainers-python)
+and provisions WireMock as a test container on-demand.
+
+See the step-by-step guide [here](../../docs/quickstart.md)
+
+## Prerequisites
+
+- Python 3.7 or above
+- Pip 20.0.0 or above (use `apt install python3-pip`, for example)
+- Pytest 7.3.0 or above (use `pip install pytest`)
+- Testcontainers 3.5.0 or above (use `pip install testcontainers`)
+
+## TL;DR
+
+```bash
+pip install wiremock
+pytest test.py -v 
+```

example/poetry.lock renamed to examples/intro/poetry.lock

@@ -0,0 +1,25 @@
+import pytest
+import requests
+
+from wiremock.testing.testcontainer import wiremock_container
+from wiremock.constants import Config
+from wiremock.client import *
+
+@pytest.fixture # (1)
+def wiremock_server():
+    with wiremock_container(secure=False) as wm:
+        Config.base_url = wm.get_url("__admin") # (2)
+        Mappings.create_mapping(
+            Mapping(
+                request=MappingRequest(method=HttpMethods.GET, url="/hello"),
+                response=MappingResponse(status=200, body="hello"),
+                persistent=False,
+            )
+        ) # (3)      
+        yield wm
+
+def test_get_hello_world(wiremock_server): # (4)
+    response = requests.get(wiremock_server.get_url("/hello"))
+
+    assert response.status_code == 200
+    assert response.content == b"hello"

example/product_mock/__init__.py renamed to examples/intro/product_mock/__init__.py

@@ -16,4 +16,5 @@ nav:
   - Testcontainers: testcontainers.md
   - Standalone: api-client.md
   - Resources:
+    - Examples: examples.md
     - Changelog: changelog.md