<!-- # `mockallan` - Lightweight HTTP Server Mock -->
<!--  -->
[](https://pypi.org/project/mockallan/) [](https://pypi.org/project/mockallan/) [](https://github.com/david-domz/mockallan/actions/workflows/python-package.yml) [](https://sonarcloud.io/summary/new_code?id=david-domz_mockallan)
`mockallan` is a lightweight HTTP server mock used as a replacement for a production HTTP server in testing environments.
## Highlights
- Command-line interface for CI and testing environments.
- The Stub Configuration API allows to configure default and per-endpoint responses.
- The Assertion API enables the assertion of expected requests performed by the software under test based on the endpoint and the request body.
- Match the request body in assertions based on
- text/plain message matching
- JSON message matching
- JSON schema validation
- XML schema validation
- Regular expression matching
- Request history enables robust assertion capabilities and diagnostics.
- Concise codebase of under 1000 lines, focusing on simplicity and making the best use of resources.
- API naming adheres to the `Mock` class from the Python `unittest.mock` standard library.
## Requirements
- Python >= 3.10
## Installation
`mockallan` is available on [PyPI](https://pypi.org/project/mockallan/). Install it using pip.
```bash
pip install mockallan
```
## Getting Started
1) Run `mockallan.py`
```bash
python mockallan.py
Listening on 0.0.0.0:8080
```
2) Run your software under test.
If you currently don't have any software whose requests you want to test, you can simulate a request performed by software under test.
For example, if we expect our software under test to perform a `POST /orders/order_e2b9/products` we can run the following `curl` command.
```bash
cat > product.json << EOF
{
"product_id": "foo",
"description": "bar",
"amount": 1
}
EOF
```
```bash
curl -s -X POST http://localhost:8080/orders/order_e2b9/products --data @product.json
```
`mockallan` will reply with the factory default response.
```json
{
"status": "200",
"message": "This is mockallan factory default response."
}
```
3) Use the Assertion API to make assertions on the expected request.
```bash
curl "http://localhost:8080/assert-called?method=POST&path=/orders/order_e2b9/products"
```
If the assertion request returns 200 then everything went fine.
```json
{
"status": 200,
"type": "assertion-success",
"title": "Assertion request GET /assert-called succeeded",
"detail": "POST /orders/order_e2b9/products called 1 times."
}
```
If it returns 409 then the assertion failed and the software under test did not behave as expected.
```json
{
"status": 409,
"type": "assertion-error",
"title": "Assertion request GET /assert-called failed",
"detail": "Expected POST /orders/order_e2b9/products to be called 1 times. Called 0 times."
}
```
## Using Configurable Stub Responses
1) Create a Stub Configuration JSON file or use `stub_config.json` in this repository.
E.g.
```json
{
"endpoints": [
{
"request": {
"method": "POST",
"path": "/orders/order_e2b9/products"
},
"response": {
"code": 200,
"headers": {
"Content-type": "application/json"
},
"body": {
"status": "200",
"message": "This is the configured response for POST /orders/order_e2b9/products"
}
}
}
]
}
```
2) Run `mockallan.py` and provide the JSON file.
```bash
python mockallan.py -c stub_config.json
```
3) Run the software under test. The mock will reply with the configured response for `POST /orders/order_e2b9/products`.
4) Use the Assertion API to make assertions on expected requests.
```bash
curl -X GET 'http://localhost:8080/assert-called?method=POST&path=/orders/order_e2b9/products'
```
If the assertion request returns 200 then everything went fine. If it returns 409 then the assertion failed and the software under test did not behave as expected.
## Using Assertions `with`
The following validations can be used when performing assertion requests with `POST /assert-called-with` or `POST /assert-called-once-with`. The request body corresponds to the `text/plain` body, JSON message, JSON schema, XML schema, or regular expression to match as shown below.
### JSON Schema Validation Assertions
Add `Content-Type: application/schema+json` to the assertion request and place the JSON schema message in the body.
E.g.
```bash
curl -X POST --header 'Content-Type: application/json+schema' \
http://localhost:8080/assert-called-with?method=POST&path=/orders/order_e2b9/products \
--data '...JSON schema here...'
```
### XML Schema Validation Assertions
Add `Content-Type: application/xml` to the assertion request and place the XML schema message in the body.
E.g.
```bash
curl -X POST --header 'Content-Type: application/xml' \
http://localhost:8080/assert-called-with?method=POST&path=/orders/order_e2b9/products \
--data '...XML schema here...'
```
### Regex Validation Assertions
Add the custom header `X-Mockallan-Validator: regex` to the assertion request and place the regular expression in the body.
E.g.
```bash
curl -X POST --header 'X-Mockallan-Validator: regex' \
http://localhost:8080/assert-called-with?method=POST&path=/orders/order_e2b9/products \
--data '...regex here...'
```
<!-- ## Stub Configuration JSON
The Stub Configuration JSON format configures `mockallan` responses.
### Stub Configuration Example
```json
{
"defaults": {
"response": {
"code": 200,
"headers": {
"Content-Type": "application/json"
},
"body": {
"status": 200,
"message": "This is the default response configured in stub_config.json"
}
}
},
"endpoints": [
{
"request": {
"method": "GET"
"path": "/orders/order_e2b9/products"
},
"response": {
"code": 200
"headers": {
"Content-type": "application/json"
},
"body": {
"status": 200,
"message": "This is the configured response for GET /orders/order_e2b9/products"
}
}
}
]
}
``` -->
## Stub Configuration API
The Stub Configuration API allows the test client to configure the mock at runtime.
|Method|Path|Query Params|Request Body|Status|Response Body|
|-|-|-|-|-|-|
|PUT|/configure|-|JSON stub configuration|204|-|
|GET|/configure|-|-|200|JSON stub configuration|
## Assertion API
The Assertion API allows for the validation of expected requests.
|Method|Path|Query Params|Request Body|Status|Response Body|
|-|-|-|-|-|-|
|GET|/assert-called|method, path|-|200 OK; 409 Conflict|Assertion success or error message|
|GET|/assert-called-once|method, path|-|200 OK; 409 Conflict|Assertion success or error message|
|POST|/assert-called-with|method, path|JSON object, JSON schema, XML schema or regex|200 OK; 409 Conflict|Assertion success or error message|
|POST|/assert-called-once-with|method, path|JSON object, JSON schema, XML schema, regex or message body|200 OK; 409 Conflict|Assertion success or error message|
|GET|/call-args|-|-|200 OK|The request body that the mock was last called with|
|GET|/call-args-list|-|-|200 OK|List of all the requests made to the mock in sequence|
|GET|/call-count|-|-|200 OK|Request count|
## Naming
Stub Configuration API and Assertion API naming are inspired by class `Mock` from the standard python package `unittest.mock`.
## Contributing
Would you like to contribute? Whether you want to report a bug, suggest an enhancement, or submit a pull request, your help is highly valuable.
If you encounter a bug, experience unexpected behavior, or have ideas for improving this project, please [open an issue](https://github.com/david-domz/mockallan/issues).
## License
This project is licensed under the terms of the MIT license.
## Related Projects
- [mockallan-docker](https://github.com/david-domz/mockallan-docker) - Containerized lightweight HTTP server mock.
- [mockallan-python-client](https://github.com/david-domz/mockallan-python-client) - Mockallan python client class.
Raw data
{
"_id": null,
"home_page": "https://github.com/david-domz/mockallan",
"name": "mockallan",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "python,http,REST,mock,test,pytest",
"author": "David Dom\u00ednguez",
"author_email": "david.7b8@gmail.com",
"download_url": "",
"platform": null,
"description": "<!-- # `mockallan` - Lightweight HTTP Server Mock -->\n\n<!--  -->\n\n[](https://pypi.org/project/mockallan/) [](https://pypi.org/project/mockallan/) [](https://github.com/david-domz/mockallan/actions/workflows/python-package.yml) [](https://sonarcloud.io/summary/new_code?id=david-domz_mockallan)\n\n`mockallan` is a lightweight HTTP server mock used as a replacement for a production HTTP server in testing environments.\n\n\n## Highlights\n\n- Command-line interface for CI and testing environments.\n\n- The Stub Configuration API allows to configure default and per-endpoint responses.\n\n- The Assertion API enables the assertion of expected requests performed by the software under test based on the endpoint and the request body.\n\n- Match the request body in assertions based on\n - text/plain message matching\n - JSON message matching\n - JSON schema validation\n - XML schema validation\n - Regular expression matching\n\n- Request history enables robust assertion capabilities and diagnostics.\n\n- Concise codebase of under 1000 lines, focusing on simplicity and making the best use of resources.\n\n- API naming adheres to the `Mock` class from the Python `unittest.mock` standard library.\n\n## Requirements\n\n- Python >= 3.10\n\n## Installation\n\n`mockallan` is available on [PyPI](https://pypi.org/project/mockallan/). Install it using pip.\n\n```bash\npip install mockallan\n```\n\n## Getting Started\n\n\n1) Run `mockallan.py`\n\n```bash\npython mockallan.py\nListening on 0.0.0.0:8080\n```\n\n2) Run your software under test.\n\nIf you currently don't have any software whose requests you want to test, you can simulate a request performed by software under test.\n\nFor example, if we expect our software under test to perform a `POST /orders/order_e2b9/products` we can run the following `curl` command.\n\n```bash\ncat > product.json << EOF\n{\n\t\"product_id\": \"foo\",\n\t\"description\": \"bar\",\n\t\"amount\": 1\n}\nEOF\n```\n\n```bash\ncurl -s -X POST http://localhost:8080/orders/order_e2b9/products --data @product.json\n```\n\n`mockallan` will reply with the factory default response.\n\n```json\n{\n\t\"status\": \"200\",\n\t\"message\": \"This is mockallan factory default response.\"\n}\n```\n\n3) Use the Assertion API to make assertions on the expected request.\n\n```bash\ncurl \"http://localhost:8080/assert-called?method=POST&path=/orders/order_e2b9/products\"\n```\n\nIf the assertion request returns 200 then everything went fine.\n\n```json\n{\n\t\"status\": 200,\n\t\"type\": \"assertion-success\",\n\t\"title\": \"Assertion request GET /assert-called succeeded\",\n\t\"detail\": \"POST /orders/order_e2b9/products called 1 times.\"\n}\n```\n\nIf it returns 409 then the assertion failed and the software under test did not behave as expected.\n\n```json\n{\n\t\"status\": 409,\n\t\"type\": \"assertion-error\",\n\t\"title\": \"Assertion request GET /assert-called failed\",\n\t\"detail\": \"Expected POST /orders/order_e2b9/products to be called 1 times. Called 0 times.\"\n}\n```\n\n## Using Configurable Stub Responses\n\n1) Create a Stub Configuration JSON file or use `stub_config.json` in this repository.\n\nE.g.\n```json\n{\n\t\"endpoints\": [\n\t\t{\n\t\t\t\"request\": {\n\t\t\t\t\"method\": \"POST\",\n\t\t\t\t\"path\": \"/orders/order_e2b9/products\"\n\t\t\t},\n\t\t\t\"response\": {\n\t\t\t\t\"code\": 200,\n\t\t\t\t\"headers\": {\n\t\t\t\t\t\"Content-type\": \"application/json\"\n\t\t\t\t},\n\t\t\t\t\"body\": {\n\t\t\t\t\t\"status\": \"200\",\n\t\t\t\t\t\"message\": \"This is the configured response for POST /orders/order_e2b9/products\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t]\n}\n```\n\n2) Run `mockallan.py` and provide the JSON file.\n\n```bash\npython mockallan.py -c stub_config.json\n```\n\n3) Run the software under test. The mock will reply with the configured response for `POST /orders/order_e2b9/products`.\n\n4) Use the Assertion API to make assertions on expected requests.\n\n```bash\ncurl -X GET 'http://localhost:8080/assert-called?method=POST&path=/orders/order_e2b9/products'\n```\n\nIf the assertion request returns 200 then everything went fine. If it returns 409 then the assertion failed and the software under test did not behave as expected.\n\n\n## Using Assertions `with`\n\nThe following validations can be used when performing assertion requests with `POST /assert-called-with` or `POST /assert-called-once-with`. The request body corresponds to the `text/plain` body, JSON message, JSON schema, XML schema, or regular expression to match as shown below.\n\n### JSON Schema Validation Assertions\n\nAdd `Content-Type: application/schema+json` to the assertion request and place the JSON schema message in the body.\n\nE.g.\n```bash\ncurl -X POST --header 'Content-Type: application/json+schema'\t\\\n\thttp://localhost:8080/assert-called-with?method=POST&path=/orders/order_e2b9/products\t\\\n\t--data '...JSON schema here...'\n```\n\n### XML Schema Validation Assertions\n\nAdd `Content-Type: application/xml` to the assertion request and place the XML schema message in the body.\n\nE.g.\n```bash\ncurl -X POST --header 'Content-Type: application/xml'\t\\\n\thttp://localhost:8080/assert-called-with?method=POST&path=/orders/order_e2b9/products\t\\\n\t--data '...XML schema here...'\n```\n\n### Regex Validation Assertions\n\nAdd the custom header `X-Mockallan-Validator: regex` to the assertion request and place the regular expression in the body. \n\nE.g.\n```bash\ncurl -X POST --header 'X-Mockallan-Validator: regex'\t\\\n\thttp://localhost:8080/assert-called-with?method=POST&path=/orders/order_e2b9/products\t\\\n\t--data '...regex here...'\n```\n\n<!-- ## Stub Configuration JSON\n\nThe Stub Configuration JSON format configures `mockallan` responses.\n\n### Stub Configuration Example\n\n\n```json\n{\n\t\"defaults\": {\n\t\t\"response\": {\n\t\t\t\"code\": 200,\n\t\t\t\"headers\": {\n\t\t\t\t\"Content-Type\": \"application/json\"\n\t\t\t},\n\t\t\t\"body\": {\n\t\t\t\t\"status\": 200,\n\t\t\t\t\"message\": \"This is the default response configured in stub_config.json\"\n\t\t\t}\n\t\t}\n\t},\n\t\"endpoints\": [\n\t\t{\n\t\t\t\"request\": {\n\t\t\t\t\"method\": \"GET\"\n\t\t\t\t\"path\": \"/orders/order_e2b9/products\"\n\t\t\t},\n\t\t\t\"response\": {\n\t\t\t\t\"code\": 200\n\t\t\t\t\"headers\": {\n\t\t\t\t\t\"Content-type\": \"application/json\"\n\t\t\t\t},\n\t\t\t\t\"body\": {\n\t\t\t\t\t\"status\": 200,\n\t\t\t\t\t\"message\": \"This is the configured response for GET /orders/order_e2b9/products\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t]\n}\n``` -->\n\n## Stub Configuration API\n\nThe Stub Configuration API allows the test client to configure the mock at runtime.\n\n|Method|Path|Query Params|Request Body|Status|Response Body|\n|-|-|-|-|-|-|\n|PUT|/configure|-|JSON stub configuration|204|-|\n|GET|/configure|-|-|200|JSON stub configuration|\n\n\n## Assertion API\n\nThe Assertion API allows for the validation of expected requests.\n\n|Method|Path|Query Params|Request Body|Status|Response Body|\n|-|-|-|-|-|-|\n|GET|/assert-called|method, path|-|200 OK; 409 Conflict|Assertion success or error message|\n|GET|/assert-called-once|method, path|-|200 OK; 409 Conflict|Assertion success or error message|\n|POST|/assert-called-with|method, path|JSON object, JSON schema, XML schema or regex|200 OK; 409 Conflict|Assertion success or error message|\n|POST|/assert-called-once-with|method, path|JSON object, JSON schema, XML schema, regex or message body|200 OK; 409 Conflict|Assertion success or error message|\n|GET|/call-args|-|-|200 OK|The request body that the mock was last called with|\n|GET|/call-args-list|-|-|200 OK|List of all the requests made to the mock in sequence|\n|GET|/call-count|-|-|200 OK|Request count|\n\n\n## Naming\n\nStub Configuration API and Assertion API naming are inspired by class `Mock` from the standard python package `unittest.mock`.\n\n\n## Contributing\n\nWould you like to contribute? Whether you want to report a bug, suggest an enhancement, or submit a pull request, your help is highly valuable.\n\nIf you encounter a bug, experience unexpected behavior, or have ideas for improving this project, please [open an issue](https://github.com/david-domz/mockallan/issues).\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n## Related Projects\n\n- [mockallan-docker](https://github.com/david-domz/mockallan-docker) - Containerized lightweight HTTP server mock.\n- [mockallan-python-client](https://github.com/david-domz/mockallan-python-client) - Mockallan python client class.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight HTTP server mock used as a replacement for a production HTTP server in testing environments.",
"version": "0.0.7",
"project_urls": {
"Homepage": "https://github.com/david-domz/mockallan"
},
"split_keywords": [
"python",
"http",
"rest",
"mock",
"test",
"pytest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cefe4235bfb8e509186fd0e94e7e649ac6ad2e2ce43a9d720c32053c318c33d0",
"md5": "e5e94c87c834c544a11bd76625671604",
"sha256": "081d9c60ea1b06f8b3624ab49d8b8e9ec477bb8aaa85acaa4c6e02ae6c8ace12"
},
"downloads": -1,
"filename": "mockallan-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5e94c87c834c544a11bd76625671604",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12306,
"upload_time": "2023-10-27T14:22:49",
"upload_time_iso_8601": "2023-10-27T14:22:49.974380Z",
"url": "https://files.pythonhosted.org/packages/ce/fe/4235bfb8e509186fd0e94e7e649ac6ad2e2ce43a9d720c32053c318c33d0/mockallan-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-27 14:22:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "david-domz",
"github_project": "mockallan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "jsonschema",
"specs": [
[
"==",
"3.2.0"
]
]
},
{
"name": "lxml",
"specs": [
[
"==",
"4.9.3"
]
]
}
],
"lcname": "mockallan"
}
JSON
