Skip to main content

Simplify working with Hoverfly from pytest

Project description


A helper for working with Hoverfly from pytest. Works both locally and in CI.


pip install pytest-hoverfly


poetry add pytest-hoverfly --dev


There are two use cases: to record a new test and to use recordings.


You need to have Docker 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
    ├── simulations

Then put this in you pytest.ini:

addopts =

Without Docker Desktop

If you're using something like 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 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:


How to record a test

from pytest_hoverfly import hoverfly
import requests

@hoverfly('my-simulation-file', record=True)
def test_google_with_hoverfly():
    assert requests.get('').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 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.

from pytest_hoverfly import hoverfly
import requests

def test_google_with_hoverfly():
    assert requests.get('').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:

    image: spectolabs/hoverfly:v1.3.2
      - 8500:8500
      - 8888:8888

    HOVERFLY_HOST: localhost

Mind that all three variables must be specified.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest_hoverfly-5.0.4.tar.gz (11.6 kB view hashes)

Uploaded source

Built Distribution

pytest_hoverfly-5.0.4-py3-none-any.whl (10.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page