# vedro-replay
[](https://pypi.org/project/vedro-replay/)
[](https://pypi.org/project/vedro-replay/)
## Documentation
### replay-tests
The idea is to test the API using requests that are sent to the production application.
Having requests, we can send them to the API of the test version and to the API of the stable version.
After receiving two responses from two versions of the application, you can compare the response status, headers, and body.
The stable version in this case is considered to work correctly and in case of a difference in the answers it means that there is a bug (or feature) in the test version of the application.
### vedro-replay
Python package for working with replay tests on vedro (docs: [vedro.io](https://vedro.io/docs/quick-start)) framework.
Enable generation of replay-tests by request files and contains the necessary tools for working and configuring tests.
## Installation
```shell
$ pip3 install vedro-replay
```
## Usage
### Commands
```shell
$ vedro-replay -h
```
```
usage: vedro-replay [-h] {generate} ...
vedro-replay commands
positional arguments:
{generate} List of available commands
generate Generate vedro-replay tests
options:
-h, --help show this help message and exit
```
#### Generate vedro-replay tests
```shell
$ vedro-replay generate -h
```
```
usage: vedro-replay generate [-h] [--requests-dir REQUESTS_DIR] [--force]
[{all,vedro_cfg,config,interfaces,contexts,helpers,helpers_methods,scenarios}] - by default all
positional arguments:
{all,vedro_cfg,interfaces,contexts,helpers,helpers_methods,scenarios}
Generation option
options:
-h, --help show this help message and exit
--requests-dir REQUESTS_DIR
The path to the directory containing the request files
--force Forced regeneration. The files will be overwritten
```
To be able to generate a test, you need to have a directory with files containing requests
(`requests` directory is expected by default, you can specify a specific directory using the `--requests-dir` argument).
Example:
```shell
tests # Root directory
|----requests
|----|----byid.http # File with API requests of the /byid method
|----|----search.http # File with API requests of the /search method
```
Example of file contents (for more information about the request format, see the following paragraph):
```shell
$ cat requests/byid.http
### byid request with id=123
GET http://{{host}}/byid?id=123
```
Having requests, you can generate tests on them:
```shell
$ vedro-replay generate
```
Example of generation:
```
tests # Root directory
|----requests
|----|----byid.http # File with API requests of the /byid method
|----|----search.http # File with API requests of the /search method
|----contexts
|----helpers
|----interfaces
|----scenarios # Testing scenarios
|----|----byid.py # Scenario, using requests from a file requests/byid.http
|----|----search.py
|----config.py
|----vedro.cfg.py
```
### Request format
The request format is based on
[format .http from jetbrains](https://www.jetbrains.com/help/idea/exploring-http-syntax.html)
The structure of the request has the following form:
```shell
### Comment
Method Request-URI
Header-field: Header-value
JSON-Body
```
Rules:
- Each request starts with a string with the characters "###" at the beginning.
Also on the same line it is possible to write a comment (optional) to the query that will be output in the test being run.
- http method must consist of capital letters
- Request-URI should always have the format http(s)://{{host}}[path][query].
The host looks like this, for the ability to send requests for tests using an http client inside the IDE Idea/Pycharm/...
- Headers are optional
- Json-body is optional
Examples can be found [here](https://github.com/kvs8/vedro-replay/blob/main/tests/unit/test_data/get_requests.http)
and [here](https://github.com/kvs8/vedro-replay/blob/main/tests/unit/test_data/post_requests.http)
### Running tests
To run the tests, need two hosts to send requests to them. You need to set environment variables in any convenient way:
```shell
GOLDEN_API_URL=master.app
TESTING_API_URL=branch.app
```
After that, you can run the tests:
```shell
$ vedro run -vvv
```
### Setting up scenario
Sometimes there may be fields or headers in the API response that have a random value or that will differ from the value from the response from the test application.
Such values will not allow testing, so they must be cut from the comparison of the two answers.
```python
# helpers/helpers.py:
def prepare_byid(response) -> Response: # Generated method for scenario byid.py
exclude_headers = ['date'] # Date header exclude
exclude_body = ['meta.api_version'] # Excluding a field from the body
return filter_response(JsonResponse(response), exclude_headers, exclude_body)
```
#### To ignore headers, simply specify their names separated by commas, for example:
```python
exclude_headers = ['header-name', 'x-header-name']
```
#### To exclude json fields from the response, use the format below
Original response body:
```json
{
"meta": {
"api_version": "1.0.0",
"issue_date": "20230926"
},
"items": [
{
"id": "1_abc",
"name": "chair"
},
{
"id": "2_sdv",
"name": "table"
}
]
}
```
- Exclude by json keys:
```python
exclude_body = ['meta.api_version']
```
Result:
```json
{
"meta": {
"issue_date": "20230926"
},
"items": [
{
"id": "1_abc",
"name": "chair"
},
{
"id": "2_sdv",
"name": "table"
}
]
}
```
- Exclude for each list element:
```python
exclude_body = ['items.*.id']
```
Result:
```json
{
"meta": {
"api_version": "1.0.0",
"issue_date": "20230926"
},
"items": [
{
"name": "chair"
},
{
"name": "table"
}
]
}
```
- Exclude list item by index:
```python
exclude_body = ['items.1']
```
Result:
```json
{
"meta": {
"api_version": "1.0.0",
"issue_date": "20230926"
},
"items": [
{
"id": "1_abc",
"name": "chair"
}
]
}
```
- Exclude string value by regular expression
```python
exclude_body = ['items.*.id:\d+']
```
Result:
```json
{
"meta": {
"api_version": "1.0.0",
"issue_date": "20230926"
},
"items": [
{
"id": "1",
"name": "chair"
},
{
"id": "2",
"name": "table"
}
]
}
```
#### Rules exclude:
- Dictionary keys are separated by a symbol '`.`'
- If the value is a list and you need to bypass all the elements of the list, use the symbol '`*`'
- The exclude path and the regular expression are separated by a symbol '`:`'
- If the path is not contained (or not completely) in the dictionary, nothing will be cut. Similarly, for a regular expression, if nothing was found for the regular expression, the value will not change
Raw data
{
"_id": null,
"home_page": "https://github.com/kvs8/vedro-replay",
"name": "vedro-replay",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Konstantin Shefer",
"author_email": "kostya.shefer.999@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e7/68/cd61321b11f74fa65a0d81557dbc1a75686ab668047188ab8b9cea5162df/vedro-replay-1.1.0.tar.gz",
"platform": null,
"description": "# vedro-replay\n\n[](https://pypi.org/project/vedro-replay/)\n[](https://pypi.org/project/vedro-replay/)\n\n## Documentation\n\n### replay-tests\nThe idea is to test the API using requests that are sent to the production application. \nHaving requests, we can send them to the API of the test version and to the API of the stable version. \nAfter receiving two responses from two versions of the application, you can compare the response status, headers, and body. \nThe stable version in this case is considered to work correctly and in case of a difference in the answers it means that there is a bug (or feature) in the test version of the application.\n\n### vedro-replay\nPython package for working with replay tests on vedro (docs: [vedro.io](https://vedro.io/docs/quick-start)) framework. \nEnable generation of replay-tests by request files and contains the necessary tools for working and configuring tests.\n\n\n## Installation\n```shell\n$ pip3 install vedro-replay\n```\n\n\n## Usage\n\n### Commands\n```shell\n$ vedro-replay -h\n```\n```\nusage: vedro-replay [-h] {generate} ...\n\nvedro-replay commands\n\npositional arguments:\n {generate} List of available commands\n generate Generate vedro-replay tests\n\noptions:\n -h, --help show this help message and exit\n```\n\n#### Generate vedro-replay tests\n```shell\n$ vedro-replay generate -h\n```\n```\nusage: vedro-replay generate [-h] [--requests-dir REQUESTS_DIR] [--force] \n [{all,vedro_cfg,config,interfaces,contexts,helpers,helpers_methods,scenarios}] - by default all\n\npositional arguments:\n {all,vedro_cfg,interfaces,contexts,helpers,helpers_methods,scenarios}\n Generation option\n\noptions:\n -h, --help show this help message and exit\n --requests-dir REQUESTS_DIR\n The path to the directory containing the request files\n --force Forced regeneration. The files will be overwritten\n```\n\nTo be able to generate a test, you need to have a directory with files containing requests \n(`requests` directory is expected by default, you can specify a specific directory using the `--requests-dir` argument).\n\nExample:\n```shell\ntests # Root directory\n|----requests\n|----|----byid.http # File with API requests of the /byid method\n|----|----search.http # File with API requests of the /search method\n```\n\nExample of file contents (for more information about the request format, see the following paragraph):\n```shell\n$ cat requests/byid.http\n### byid request with id=123\nGET http://{{host}}/byid?id=123\n```\nHaving requests, you can generate tests on them:\n```shell\n$ vedro-replay generate\n```\nExample of generation:\n```\ntests # Root directory\n|----requests\n|----|----byid.http # File with API requests of the /byid method\n|----|----search.http # File with API requests of the /search method\n|----contexts \n|----helpers\n|----interfaces \n|----scenarios # Testing scenarios\n|----|----byid.py # Scenario, using requests from a file requests/byid.http\n|----|----search.py\n|----config.py\n|----vedro.cfg.py\n```\n\n### Request format\nThe request format is based on \n[format .http from jetbrains](https://www.jetbrains.com/help/idea/exploring-http-syntax.html) \nThe structure of the request has the following form:\n```shell\n### Comment\nMethod Request-URI\nHeader-field: Header-value\n\nJSON-Body\n```\n\nRules:\n- Each request starts with a string with the characters \"###\" at the beginning.\nAlso on the same line it is possible to write a comment (optional) to the query that will be output in the test being run.\n- http method must consist of capital letters\n- Request-URI should always have the format http(s)://{{host}}[path][query].\nThe host looks like this, for the ability to send requests for tests using an http client inside the IDE Idea/Pycharm/...\n- Headers are optional\n- Json-body is optional\n\nExamples can be found [here](https://github.com/kvs8/vedro-replay/blob/main/tests/unit/test_data/get_requests.http) \nand [here](https://github.com/kvs8/vedro-replay/blob/main/tests/unit/test_data/post_requests.http)\n\n### Running tests\nTo run the tests, need two hosts to send requests to them. You need to set environment variables in any convenient way:\n```shell\nGOLDEN_API_URL=master.app\nTESTING_API_URL=branch.app\n```\n\nAfter that, you can run the tests:\n```shell\n$ vedro run -vvv \n```\n\n### Setting up scenario\nSometimes there may be fields or headers in the API response that have a random value or that will differ from the value from the response from the test application. \nSuch values will not allow testing, so they must be cut from the comparison of the two answers.\n\n```python\n# helpers/helpers.py:\n\ndef prepare_byid(response) -> Response: # Generated method for scenario byid.py\n exclude_headers = ['date'] # Date header exclude\n exclude_body = ['meta.api_version'] # Excluding a field from the body\n return filter_response(JsonResponse(response), exclude_headers, exclude_body)\n```\n\n#### To ignore headers, simply specify their names separated by commas, for example:\n```python\nexclude_headers = ['header-name', 'x-header-name']\n```\n\n#### To exclude json fields from the response, use the format below\n\nOriginal response body:\n```json\n{\n \"meta\": {\n \"api_version\": \"1.0.0\",\n \"issue_date\": \"20230926\"\n },\n \"items\": [\n {\n \"id\": \"1_abc\",\n \"name\": \"chair\"\n },\n {\n \"id\": \"2_sdv\",\n \"name\": \"table\"\n }\n ]\n}\n```\n\n- Exclude by json keys:\n```python\nexclude_body = ['meta.api_version']\n```\nResult:\n```json\n{\n \"meta\": {\n \"issue_date\": \"20230926\"\n },\n \"items\": [\n {\n \"id\": \"1_abc\",\n \"name\": \"chair\"\n },\n {\n \"id\": \"2_sdv\",\n \"name\": \"table\"\n }\n ]\n}\n```\n\n- Exclude for each list element:\n```python\nexclude_body = ['items.*.id']\n```\nResult:\n```json\n{\n \"meta\": {\n \"api_version\": \"1.0.0\",\n \"issue_date\": \"20230926\"\n },\n \"items\": [\n {\n \"name\": \"chair\"\n },\n {\n \"name\": \"table\"\n }\n ]\n}\n```\n\n- Exclude list item by index:\n```python\nexclude_body = ['items.1']\n```\nResult:\n```json\n{\n \"meta\": {\n \"api_version\": \"1.0.0\",\n \"issue_date\": \"20230926\"\n },\n \"items\": [\n {\n \"id\": \"1_abc\",\n \"name\": \"chair\"\n }\n ]\n}\n```\n\n- Exclude string value by regular expression\n```python\nexclude_body = ['items.*.id:\\d+']\n```\nResult:\n```json\n{\n \"meta\": {\n \"api_version\": \"1.0.0\",\n \"issue_date\": \"20230926\"\n },\n \"items\": [\n {\n \"id\": \"1\",\n \"name\": \"chair\"\n },\n {\n \"id\": \"2\",\n \"name\": \"table\"\n }\n ]\n}\n``` \n \n#### Rules exclude:\n- Dictionary keys are separated by a symbol '`.`'\n- If the value is a list and you need to bypass all the elements of the list, use the symbol '`*`'\n- The exclude path and the regular expression are separated by a symbol '`:`'\n- If the path is not contained (or not completely) in the dictionary, nothing will be cut. Similarly, for a regular expression, if nothing was found for the regular expression, the value will not change\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "vedro-replay package",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/kvs8/vedro-replay"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ce784b6b600a8cdeea006d6f06d2e57e85cdade712c07b3d48cdde9bd6d1ff5",
"md5": "e29051bd3555d2f9a56c33d1e36778a8",
"sha256": "75e6ba8bd4813bbd93d43f32cd69a4f66f81cc75f1815e7dc5239fe019606c27"
},
"downloads": -1,
"filename": "vedro_replay-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e29051bd3555d2f9a56c33d1e36778a8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18330,
"upload_time": "2024-04-12T07:37:06",
"upload_time_iso_8601": "2024-04-12T07:37:06.645456Z",
"url": "https://files.pythonhosted.org/packages/0c/e7/84b6b600a8cdeea006d6f06d2e57e85cdade712c07b3d48cdde9bd6d1ff5/vedro_replay-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e768cd61321b11f74fa65a0d81557dbc1a75686ab668047188ab8b9cea5162df",
"md5": "8517372414339ef3faa5b98032e5ff86",
"sha256": "d773cb59ec0a80d5449ad3f6acd714b18113c092f16eccf18028df988d70ea97"
},
"downloads": -1,
"filename": "vedro-replay-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8517372414339ef3faa5b98032e5ff86",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16800,
"upload_time": "2024-04-12T07:37:08",
"upload_time_iso_8601": "2024-04-12T07:37:08.407997Z",
"url": "https://files.pythonhosted.org/packages/e7/68/cd61321b11f74fa65a0d81557dbc1a75686ab668047188ab8b9cea5162df/vedro-replay-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 07:37:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kvs8",
"github_project": "vedro-replay",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "vedro-replay"
}
JSON
