[](https://github.com/wrike/pytest-hoverfly/actions/workflows/main.yml)
A helper for working with [Hoverfly](https://hoverfly.readthedocs.io/en/latest/) from `pytest`. Works both locally and in CI.
### Installation
`pip install pytest-hoverfly`
or
`poetry add pytest-hoverfly --dev`
### Usage
There are two use cases: to record a new test and to use recordings.
#### Prerequisites
You need to have [Docker](https://www.docker.com/) installed. `pytest-hoverfly` uses it under the hood to create Hoverfly instances.
Create a directory to store simulation files. Pass `--hoverfly-simulation-path` option
when calling `pytest`. The path may be absolute or relative to your `pytest.ini` file.
E.g. if you have a structure like this:
```
├── myproject
├── ...
├── pytest.ini
└── tests
├── conftest.py
├── simulations
```
Then put this in you pytest.ini:
```
[pytest]
addopts =
--hoverfly-simulation-path=tests/simulations
```
#### Without Docker Desktop
If you're using something like [lima](https://github.com/lima-vm/lima) instead of Docker Desktop, you need to specify a path to Docker API. For lima:
`export DOCKER_HOST=unix:///Users/<YOUR-USER>/.lima/default/sock/docker.sock`
If you're using [minikube](https://github.com/kubernetes/minikube) instead of Docker Desktop, you need to specify the service host because the exposed ports are not available on localhost. For minikube you get the service IP with `minikube ip` command and then put it in the env var:
`export SERVICE_HOST=192.168.0.xxx`
#### How to record a test
```python
from pytest_hoverfly import hoverfly
import requests
@hoverfly('my-simulation-file', record=True)
def test_google_with_hoverfly():
assert requests.get('https://google.com').status_code == 200
```
Write a test. Decorate it with `@hoverfly`, specifying a name of a file to save the simulation to.
Run the test. A Hoverfly container will be created, and `HTTP_PROXY` and `HTTPS_PROXY` env vars
will be set to point to this container. After test finishes, the resulting simulation will
be exported from Hoverfly and saved to a file you specified. After test session ends, Hoverfly
container will be destroyed (unless `--hoverfly-reuse-container` is passed to pytest).
This will work for cases when a server always returns the same response for the same
request. If you need to work with stateful endpoints (e.g. wait for Teamcity build
to finish), use `@hoverfly('my-simulation, record=True, stateful=True)`. See
[Hoverfly docs](https://docs.hoverfly.io/en/latest/pages/tutorials/basic/capturingsequences/capturingsequences.html)
for details.
#### How to use recordings
Remove `record` parameter. That's it. When you run the test, it will create a container
with Hoverfly, upload your simulation into it, and use it instead of a real service.
```python
from pytest_hoverfly import hoverfly
import requests
@hoverfly('my-simulation-file')
def test_google_with_hoverfly():
assert requests.get('https://google.com').status_code == 200
```
Caveat: if you're using an HTTP library other than `aiohttp` or `requests` you need to
tell it to use Hoverfly as HTTP(S) proxy and to trust Hoverfly's certificate. See
`_patch_env` fixture for details on how it's done for `aiohttp` and `requests`.
#### How to re-record a test
Add `record=True` again, and run the test. The simulation file will be overwritten.
#### Change Hoverfly version
To use a different Hoverfly version, specify `--hoverfly-image`. It must be a valid Docker image tag.
#### Start Hoverfly with custom parameters
Use `--hoverfly-args`. It is passed as is to a Hoverfly container.
### Usage in CI
CI systems like Gitlab CI or Github Actions allow you to run arbitrary services as containers. `pytest-hoverfly` can detect if a Hoverfly instance is already running by looking at certain environment variables. If it detects a running instance, `pytest-hovefly` uses it, and doesn't create a new container.
For Github Actions:
```
services:
hoverfly:
image: spectolabs/hoverfly:v1.3.2
ports:
- 8500:8500
- 8888:8888
env:
HOVERFLY_HOST: localhost
HOVERFLY_PROXY_PORT: 8500
HOVERFLY_ADMIN_PORT: 8888
```
Mind that all three variables must be specified.
Raw data
{
"_id": null,
"home_page": "https://github.com/wrike/pytest-hoverfly",
"name": "pytest-hoverfly",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "hoverfly,pytest,tests",
"author": "Devops team at Wrike",
"author_email": "devops@team.wrike.com",
"download_url": "https://files.pythonhosted.org/packages/a6/92/7647f1095f4466ac2646555cf460b9bdcab1f56649a89bd5e42aaba7c57f/pytest_hoverfly-5.0.4.tar.gz",
"platform": null,
"description": "[](https://github.com/wrike/pytest-hoverfly/actions/workflows/main.yml)\n\n\nA helper for working with [Hoverfly](https://hoverfly.readthedocs.io/en/latest/) from `pytest`. Works both locally and in CI.\n\n### Installation\n`pip install pytest-hoverfly`\n\nor\n\n`poetry add pytest-hoverfly --dev`\n\n\n### Usage\nThere are two use cases: to record a new test and to use recordings.\n\n#### Prerequisites\nYou need to have [Docker](https://www.docker.com/) installed. `pytest-hoverfly` uses it under the hood to create Hoverfly instances.\n\nCreate a directory to store simulation files. Pass `--hoverfly-simulation-path` option\nwhen calling `pytest`. The path may be absolute or relative to your `pytest.ini` file.\nE.g. if you have a structure like this:\n```\n\u251c\u2500\u2500 myproject\n \u251c\u2500\u2500 ...\n\u251c\u2500\u2500 pytest.ini\n\u2514\u2500\u2500 tests\n \u251c\u2500\u2500 conftest.py\n \u251c\u2500\u2500 simulations\n```\n\nThen put this in you pytest.ini:\n```\n[pytest]\naddopts =\n --hoverfly-simulation-path=tests/simulations\n```\n\n#### Without Docker Desktop\nIf you're using something like [lima](https://github.com/lima-vm/lima) instead of Docker Desktop, you need to specify a path to Docker API. For lima:\n\n`export DOCKER_HOST=unix:///Users/<YOUR-USER>/.lima/default/sock/docker.sock`\n\nIf you're using [minikube](https://github.com/kubernetes/minikube) instead of Docker Desktop, you need to specify the service host because the exposed ports are not available on localhost. For minikube you get the service IP with `minikube ip` command and then put it in the env var:\n\n`export SERVICE_HOST=192.168.0.xxx`\n\n#### How to record a test\n```python\nfrom pytest_hoverfly import hoverfly\nimport requests\n\n\n@hoverfly('my-simulation-file', record=True)\ndef test_google_with_hoverfly():\n assert requests.get('https://google.com').status_code == 200\n```\n\nWrite a test. Decorate it with `@hoverfly`, specifying a name of a file to save the simulation to.\nRun the test. A Hoverfly container will be created, and `HTTP_PROXY` and `HTTPS_PROXY` env vars\nwill be set to point to this container. After test finishes, the resulting simulation will\nbe exported from Hoverfly and saved to a file you specified. After test session ends, Hoverfly\ncontainer will be destroyed (unless `--hoverfly-reuse-container` is passed to pytest).\n\nThis will work for cases when a server always returns the same response for the same\nrequest. If you need to work with stateful endpoints (e.g. wait for Teamcity build\nto finish), use `@hoverfly('my-simulation, record=True, stateful=True)`. See\n[Hoverfly docs](https://docs.hoverfly.io/en/latest/pages/tutorials/basic/capturingsequences/capturingsequences.html)\nfor details.\n\n#### How to use recordings\nRemove `record` parameter. That's it. When you run the test, it will create a container\nwith Hoverfly, upload your simulation into it, and use it instead of a real service.\n\n```python\nfrom pytest_hoverfly import hoverfly\nimport requests\n\n\n@hoverfly('my-simulation-file')\ndef test_google_with_hoverfly():\n assert requests.get('https://google.com').status_code == 200\n```\n\nCaveat: if you're using an HTTP library other than `aiohttp` or `requests` you need to\ntell it to use Hoverfly as HTTP(S) proxy and to trust Hoverfly's certificate. See\n`_patch_env` fixture for details on how it's done for `aiohttp` and `requests`.\n\n#### How to re-record a test\nAdd `record=True` again, and run the test. The simulation file will be overwritten.\n\n\n#### Change Hoverfly version\nTo use a different Hoverfly version, specify `--hoverfly-image`. It must be a valid Docker image tag.\n\n#### Start Hoverfly with custom parameters\nUse `--hoverfly-args`. It is passed as is to a Hoverfly container.\n\n### Usage in CI\nCI systems like Gitlab CI or Github Actions allow you to run arbitrary services as containers. `pytest-hoverfly` can detect if a Hoverfly instance is already running by looking at certain environment variables. If it detects a running instance, `pytest-hovefly` uses it, and doesn't create a new container.\n\nFor Github Actions:\n\n```\nservices:\n hoverfly:\n image: spectolabs/hoverfly:v1.3.2\n ports:\n - 8500:8500\n - 8888:8888\n\n env:\n HOVERFLY_HOST: localhost\n HOVERFLY_PROXY_PORT: 8500\n HOVERFLY_ADMIN_PORT: 8888\n```\n\nMind that all three variables must be specified.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simplify working with Hoverfly from pytest",
"version": "5.0.4",
"split_keywords": [
"hoverfly",
"pytest",
"tests"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02247fa27140aa78689e330d02a261fcf5e8bcc543cd12054f02bd1b54769c7e",
"md5": "08b753db2212a502ef9e4c249b580cab",
"sha256": "39379d31bc92ed3cbfc77ab191e52ba3627115fb32500f4470a12356ce136614"
},
"downloads": -1,
"filename": "pytest_hoverfly-5.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08b753db2212a502ef9e4c249b580cab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 10897,
"upload_time": "2023-01-30T16:06:34",
"upload_time_iso_8601": "2023-01-30T16:06:34.186533Z",
"url": "https://files.pythonhosted.org/packages/02/24/7fa27140aa78689e330d02a261fcf5e8bcc543cd12054f02bd1b54769c7e/pytest_hoverfly-5.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6927647f1095f4466ac2646555cf460b9bdcab1f56649a89bd5e42aaba7c57f",
"md5": "7217d072b89e0abef03bbc774ddd83c8",
"sha256": "d0b6479f4bad8f3c700a83fdb5230e7e4125c49e62a8e6c7ee85c83c5d55372a"
},
"downloads": -1,
"filename": "pytest_hoverfly-5.0.4.tar.gz",
"has_sig": false,
"md5_digest": "7217d072b89e0abef03bbc774ddd83c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 11552,
"upload_time": "2023-01-30T16:06:35",
"upload_time_iso_8601": "2023-01-30T16:06:35.283753Z",
"url": "https://files.pythonhosted.org/packages/a6/92/7647f1095f4466ac2646555cf460b9bdcab1f56649a89bd5e42aaba7c57f/pytest_hoverfly-5.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-30 16:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "wrike",
"github_project": "pytest-hoverfly",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pytest-hoverfly"
}
JSON
