Skip to main content

Simple pytest fixtures for Docker and Docker Compose based tests

Project description

Docker-based integration tests

PyPI version Build Status Python versions Code style

Description

Simple pytest fixtures that help you write integration tests with Docker and Docker Compose. Specify all necessary containers in a docker-compose.yml file and pytest-docker will spin them up for the duration of your tests.

pytest-docker was originally created by André Caron.

Installation

Install pytest-docker with pip or add it to your test requirements.

By default, it uses the docker compose command, so it relies on the Compose plugin for Docker (also called Docker Compose V2).

Docker Compose V1 compatibility

If you want to use the old docker-compose command (deprecated since July 2023, not receiving updates since 2021) then you can do it using the docker-compose-command fixture:

@pytest.fixture(scope="session")
def docker_compose_command() -> str:
    return "docker-compose"

If you want to use the pip-distributed version of docker-compose command, you can install it using

pip install pytest-docker[docker-compose-v1]

Another option could be usage of compose-switch.

Usage

Here is an example of a test that depends on an HTTP service.

With a docker-compose.yml file like this (using the httpbin service):

version: '2'
services:
  httpbin:
    image: "kennethreitz/httpbin"
    ports:
      - "8000:80"

You can write a test like this:

import pytest
import requests

from requests.exceptions import ConnectionError


def is_responsive(url):
    try:
        response = requests.get(url)
        if response.status_code == 200:
            return True
    except ConnectionError:
        return False


@pytest.fixture(scope="session")
def http_service(docker_ip, docker_services):
    """Ensure that HTTP service is up and responsive."""

    # `port_for` takes a container port and returns the corresponding host port
    port = docker_services.port_for("httpbin", 80)
    url = "http://{}:{}".format(docker_ip, port)
    docker_services.wait_until_responsive(
        timeout=30.0, pause=0.1, check=lambda: is_responsive(url)
    )
    return url


def test_status_code(http_service):
    status = 418
    response = requests.get(http_service + "/status/{}".format(status))

    assert response.status_code == status

By default, this plugin will try to open docker-compose.yml in your tests directory. If you need to use a custom location, override the docker_compose_file fixture inside your conftest.py file:

import os
import pytest


@pytest.fixture(scope="session")
def docker_compose_file(pytestconfig):
    return os.path.join(str(pytestconfig.rootdir), "mycustomdir", "docker-compose.yml")

To use multiple compose files, return a list of paths from the docker_compose_file fixture:

import os
import pytest


@pytest.fixture(scope="session")
def docker_compose_file(pytestconfig):
    return [
        os.path.join(str(pytestconfig.rootdir), "tests", "compose.yml"),
        os.path.join(str(pytestconfig.rootdir), "tests", "compose.override.yml"),
    ]

If you want to debug the test suite in your IDE (Pycharm, VsCode, etc.) and need to stop the test, the stack will be left running. To avoid creating multiple stacks, you can pin the project name and always teardown before starting a new stack:

import pytest

# Pin the project name to avoid creating multiple stacks
@pytest.fixture(scope="session")
def docker_compose_project_name() -> str:
    return "my-compose-project"

# Stop the stack before starting a new one
@pytest.fixture(scope="session")
def docker_setup():
    return ["down -v", "up --build -d"]

Available fixtures

By default, the scope of the fixtures are session but can be changed with pytest command line option --container-scope <scope>:

pytest --container-scope <scope> <test_directory>

For available scopes and descriptions see https://docs.pytest.org/en/6.2.x/fixture.html#fixture-scopes

docker_ip

Determine the IP address for TCP connections to Docker containers.

docker_compose_file

Get an absolute path to the docker-compose.yml file. Override this fixture in your tests if you need a custom location.

docker_compose_project_name

Generate a project name using the current process PID. Override this fixture in your tests if you need a particular project name.

docker_services

Start all services from the docker compose file (docker-compose up). After test are finished, shutdown all services (docker-compose down).

docker_compose_command

Docker Compose command to use to execute Dockers. Default is to use Docker Compose V2 (command is docker compose). If you want to use Docker Compose V1, change this fixture to return docker-compose.

docker_setup

Get the list of docker_compose commands to be executed for test spawn actions. Override this fixture in your tests if you need to change spawn actions. Returning anything that would evaluate to False will skip this command.

docker_cleanup

Get the list of docker_compose commands to be executed for test clean-up actions. Override this fixture in your tests if you need to change clean-up actions. Returning anything that would evaluate to False will skip this command.

Development

Use of a virtual environment is recommended. See the venv package for more information.

First, install pytest-docker and its test dependencies:

pip install -e ".[tests]"

Run tests with

pytest -c setup.cfg

to make sure that the correct configuration is used. This is also how tests are run in CI.

Use black with default settings for formatting. You can also use pylint with setup.cfg as the configuration file as well as mypy for type checking.

Contributing

This pytest plug-in and its source code are made available to you under a MIT license. It is safe to use in commercial and closed-source applications. Read the license for details!

Found a bug? Think a new feature would make this plug-in more practical? We welcome issues and pull requests!

When creating a pull request, be sure to follow this projects conventions (see above).

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_docker-3.2.3.tar.gz (13.5 kB view details)

Uploaded Source

Built Distribution

pytest_docker-3.2.3-py3-none-any.whl (8.6 kB view details)

Uploaded Python 3

File details

Details for the file pytest_docker-3.2.3.tar.gz.

File metadata

  • Download URL: pytest_docker-3.2.3.tar.gz
  • Upload date:
  • Size: 13.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for pytest_docker-3.2.3.tar.gz
Algorithm Hash digest
SHA256 26a1c711d99ef01e86e7c9c007f69641552c1554df4fccb065b35581cca24206
MD5 97a6cebe9147548f9b57d26db5c8cbb4
BLAKE2b-256 7975285187953062ebe38108e77a7919c75e157943fa3513371c88e27d3df7b2

See more details on using hashes here.

File details

Details for the file pytest_docker-3.2.3-py3-none-any.whl.

File metadata

  • Download URL: pytest_docker-3.2.3-py3-none-any.whl
  • Upload date:
  • Size: 8.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for pytest_docker-3.2.3-py3-none-any.whl
Algorithm Hash digest
SHA256 f973c35e6f2b674c8fc87e8b3354b02c15866a21994c0841a338c240a05de1eb
MD5 640411892ed3e18c1613125bb8886640
BLAKE2b-256 c5c7e057e0d1de611ce1bbb26cccf07ddf56eb30a6f6a03aa512a09dac356e03

See more details on using hashes here.

Supported by

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