Skip to content

Commit a9e2666

Browse files
oleg-nenashevoleg-nenashev
authored
Rework and deduplicate the Python WireMock documentation (#79)
* Rework and deduplicate the Python WireMock documentation * Fix links
1 parent d510164 commit a9e2666

File tree

9 files changed

+221
-163
lines changed

9 files changed

+221
-163
lines changed

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Contributing to Python WireMock
2+
3+
[![a](https://img.shields.io/badge/slack-%23wiremock%2Fpython-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
4+
5+
## Get Started
6+
7+
1. Join us ion the `#wiremock-python` channel on the [WireMock Slack](https://slack.wiremock.org/)
8+
2. Check out the GitHub issues!
9+
10+
## Pull Requests
11+
12+
General Rules:
13+
14+
- All Tests must pass
15+
- Coverage shouldn't decrease
16+
- All Pull Requests should be rebased against master **before** submitting the PR.
17+
18+
## Development
19+
20+
Setup the project using poetry.
21+
22+
`poetry install`

‎README.md‎

Lines changed: 10 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# Python WireMock Admin API Client
1+
# Python WireMock
22

33
<p align="center">
44
<a href="https://wiremock.org/docs/solutions/python/" target="_blank">
55
<img width="512px" src="docs/images/python-wiremock-horizontal.png" alt="WireMock Logo"/>
66
</a>
77
</p>
88

9-
Python Wiremock is an HTTP client that allows users to interact with a Wiremock instance from within a Python project.
9+
Python WireMock is a library that allows users to interact with a WireMock instance from within a Python project.
10+
Full documentation can be found at [wiremock.readthedocs.org](http://wiremock.readthedocs.org/).
1011

1112
[![a](https://img.shields.io/badge/slack-%23wiremock%2Fpython-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
1213
[![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](http://wiremock.readthedocs.org/)
@@ -20,91 +21,22 @@ FIXME: Reporting is dead: https://github.com/wiremock/python-wiremock/issues/74
2021

2122
WireMock can run in unit tests, as a standalone process or a container. Key features include:
2223

24+
- [Testcontainers Python](https://github.com/testcontainers/testcontainers-python) module to easily start WireMock server for your tests
25+
- REST API Client for a standalone WireMock Java server
2326
- Supports most of the major [Wiremock](https://wiremock.org/docs) features (more on their way soon)
24-
- Support for [testcontainers-python](https://github.com/testcontainers/testcontainers-python) to easily start wiremock server for your tests
25-
- Support for standalone wiremock JAVA sever
2627

27-
## Install as Dependency
28+
## References
2829

29-
To install:
30-
31-
`pip install wiremock`
32-
33-
To install with testing dependencies:
34-
35-
`pip install wiremock[testing]`
36-
37-
To install via Poetry:
38-
39-
`poetry add --extras=testing wiremock`
40-
41-
## Quick Start
42-
43-
The preferred way of using WireMock to mock your services is by using the provided `WireMockContainer` [testcontainers-python](https://github.com/testcontainers/testcontainers-python).
44-
45-
```python
46-
import pytest
47-
48-
from wiremock.testing.testcontainer import wiremock_container
49-
50-
@pytest.fixture(scope="session") # (1)
51-
def wm_server():
52-
with wiremock_container(secure=False) as wm:
53-
54-
Config.base_url = wm.get_url("__admin") # (2)
55-
56-
Mappings.create_mapping(
57-
Mapping(
58-
request=MappingRequest(method=HttpMethods.GET, url="/hello"),
59-
response=MappingResponse(status=200, body="hello"),
60-
persistent=False,
61-
)
62-
) # (3)
63-
yield wm
64-
65-
66-
def test_get_hello_world(wm_server): # (4)
67-
68-
resp1 = requests.get(wm_server.get_url("/hello"), verify=False)
69-
70-
assert resp1.status_code == 200
71-
assert resp1.content == b"hello"
72-
```
73-
74-
1. Create a pytest fixture to manage the container life-cycle. use fixture `scope` to control how often the container is created
75-
76-
2. Set the wiremock sdk config url to the url exposed by the container
77-
78-
3. Create response and request mappings using the Admin SDK.
79-
80-
4. Use the `wm_server` fixture in your tests and make requests against the mock server.
81-
82-
You can read more about Testcontainers support in python-wiremock [here](docs/testcontainers.md).
30+
- [Quickstart Guide](./docs/quickstart.md)
31+
- [Installation](./docs/install.md)
32+
- [Full documentation](http://wiremock.readthedocs.org/)
8333

8434
## Examples
8535

8636
There are several example projects included to demonstrate the different ways that wiremock can be used to mock
8737
services in your tests and systems. The example test modules demonstrate different strategies for testing against
8838
the same "product service" and act as a good demonstration of real world applications to help you get started.
8939

90-
- [Python Testcontainers](example/tests/test_testcontainers.py)
40+
- [Testcontainers Python](example/tests/test_testcontainers.py)
9141

9242
- [Standalone Java Server Version](example/tests/test_java_server.py)
93-
94-
## Documentation
95-
96-
wiremock documentation can be found at http://wiremock.readthedocs.org/
97-
98-
## Pull Requests
99-
100-
General Rules:
101-
102-
- All Tests must pass
103-
- Coverage shouldn't decrease
104-
- All Pull Requests should be rebased against master **before** submitting the PR.
105-
106-
## Development
107-
108-
Setup the project using poetry.
109-
110-
`poetry install`

‎docs/api-client.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
Using with a Standalone WireMock
2+
===========
3+
4+
An example app:
5+
6+
```python
7+
from wiremock.constants import Config
8+
from wiremock.client import *
9+
10+
Config.base_url = 'https://mockserver.example.com/__admin/'
11+
# Optionally set a custom cert path:
12+
# Config.requests_cert = ... (See requests documentation)
13+
# Optionally disable cert verification
14+
# Config.requests_verify = False
15+
16+
mapping = Mapping(
17+
priority=100,
18+
request=MappingRequest(
19+
method=HttpMethods.GET,
20+
url='/hello'
21+
),
22+
response=MappingResponse(
23+
status=200,
24+
body='hi'
25+
),
26+
persistent=False,
27+
)
28+
29+
mapping = Mappings.create_mapping(mapping=mapping)
30+
31+
all_mappings = Mappings.retrieve_all_mappings()
32+
```
33+
34+
### Starting WireMock server with a context manager
35+
36+
```python
37+
from wiremock.constants import Config
38+
from wiremock.client import *
39+
from wiremock.server.server import WireMockServer
40+
41+
with WireMockServer() as wm:
42+
Config.base_url = 'http://localhost:{}/__admin'.format(wm.port)
43+
Mappings.create_mapping(...) # Set up stubs
44+
requests.get(...) # Make API calls
45+
```
46+
47+
### Starting WireMock server in a unittest.TestCase
48+
49+
```python
50+
51+
class MyTestClassBase(TestCase):
52+
@classmethod
53+
def setUpClass(cls):
54+
wm = self.wiremock_server = WireMockServer()
55+
wm.start()
56+
Config.base_url = 'http://localhost:{}/__admin'.format(wm.port)
57+
58+
@classmethod
59+
def tearDownClass(cls):
60+
self.wiremock_server.stop()
61+
```
62+
63+
### Customizing the path to java
64+
65+
```python
66+
WireMockServer(java_path='/path/to/my/java')
67+
```
68+
69+
### Customizing the WireMock server JAR file:
70+
71+
```python
72+
WireMockServer(jar_path='/my/secret/location/wiremock-standalone-2.35.0.jar')
73+
```

‎docs/changelog.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@ ChangeLog
33

44
Changes to the library are recorded here.
55

6+
Newer version
7+
------
8+
9+
See [GitHub Releases](https://github.com/wiremock/python-wiremock/releases)
10+
611
v2.4.0
712
------
813

‎docs/index.md‎

Lines changed: 22 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,42 @@
1-
Python client for WireMock standalone Admin API
2-
=====
1+
# Python WireMock
32

4-
This library provides a HTTP client to the WireMock standalone server's
5-
admin API.
3+
Python WireMock is an HTTP client that allows users to interact with a WireMock instance from within a Python project.
64

7-
Links
8-
=====
5+
[![a](https://img.shields.io/badge/slack-%23wiremock%2Fpython-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
96

10-
- WireMock Standalone: <https://wiremock.org/docs/standalone/>
11-
- Documentation: <https://wiremock.readthedocs.io/en/latest/>
12-
- Official Repository:
13-
<https://github.com/wiremock/python-wiremock.git>
14-
- Package: TODO
7+
## Key Features
158

16-
Requirements
17-
============
9+
WireMock can run in unit tests, as a standalone process or a container, or in the cloud.
10+
Python WireMock enables all these usage modes.
11+
Key features include:
1812

19-
wiremock is known to support Python 3.7.
13+
- [Testcontainers Python](https://github.com/testcontainers/testcontainers-python) module to easily start WireMock server for your tests
14+
- REST API Client for a standalone WireMock Java server
15+
- Supports most of the major [Wiremock](https://wiremock.org/docs) features (more on their way soon)
2016

21-
Download
22-
========
17+
## Documentation
2318

24-
PyPI: TODO
19+
- [Quickstart](./quickstart.md)
20+
- [Installation](./install.md)
21+
- [Testconatiners module](./testcontainers.md)
22+
- [Using with standalone WireMock](./api-client.md)
2523

26-
```bash
27-
$ pip install wiremock
28-
```
24+
## Links
2925

30-
Source: <https://github.com/wiremock/python-wiremock.git>
26+
- WireMock Standalone: <https://wiremock.org/docs/standalone/>
27+
- Documentation: <https://wiremock.readthedocs.io/en/latest/>
28+
- Official Repository: <https://github.com/wiremock/python-wiremock.git>
29+
- Package: <https://pypi.org/project/wiremock>
3130

32-
```bash
33-
$ git clone TODO
34-
$ poetry install
35-
```
31+
<!--
3632
3733
Contents
3834
========
3935
4036
Indices and tables
4137
------------------
4238
43-
<!--
39+
4440
* :ref:`genindex`
4541
* :ref:`modindex`
4642
* :ref:`search`

‎docs/install.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Installation
2+
3+
## Requirements
4+
5+
Python WireMock is known to support Python 3.7 or above.
6+
7+
## Pip
8+
9+
To install:
10+
11+
`pip install wiremock`
12+
13+
To install with testing dependencies:
14+
15+
`pip install wiremock[testing]`
16+
17+
## Poetry
18+
19+
To install via Poetry:
20+
21+
`poetry add wiremock`
22+
23+
Or:
24+
25+
```bash
26+
git clone [TODO](https://github.com/wiremock/python-wiremock.git)
27+
poetry install
28+
```
29+
30+
To install with testing dependencies:
31+
32+
`poetry add --extras=testing wiremock`

0 commit comments

Comments
 (0)