Docker-based integration tests
=====
[](https://pypi.org/project/pytest-docker/)
[](https://github.com/avast/pytest-docker/actions/workflows/tests.yaml)
[](https://pypi.org/project/pytest-docker/)
[](https://github.com/psf/black)
# Description
Simple [pytest](http://doc.pytest.org/) fixtures that help you write integration
tests with Docker and [Docker Compose](https://docs.docker.com/compose/).
Specify all necessary containers in a `docker-compose.yml` file and 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`](#docker_compose_command) fixture:
```python
@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`](https://github.com/docker/compose-switch).
# Usage
Here is an example of a test that depends on a HTTP service.
With a `docker-compose.yml` file like this (using the
[httpbin](https://httpbin.org/) service):
```yaml
version: '2'
services:
httpbin:
image: "kennethreitz/httpbin"
ports:
- "8000:80"
```
You can write a test like this:
```python
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:
```python
import os
import pytest
@pytest.fixture(scope="session")
def docker_compose_file(pytestconfig):
return os.path.join(str(pytestconfig.rootdir), "mycustomdir", "docker-compose.yml")
```
## Available fixtures
By default the scope of the fixtures are `session` but can be changed with
`pytest` command line option `--container-scope <scope>`:
```bash
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](https://docs.python.org/3/library/venv.html) package for more
information.
First, install `pytest-docker` and its test dependencies:
```bash
pip install -e ".[tests]"
```
Run tests with
```bash
pytest -c setup.cfg
```
to make sure that the correct configuration is used. This is also how tests are
run in CI.
Use [black](https://pypi.org/project/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).
Raw data
{
"_id": null,
"home_page": "https://github.com/avast/pytest-docker",
"name": "pytest-docker",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "docker,docker-compose,pytest",
"author": "Max K., Andre Caron",
"author_email": "maxim.kovykov@avast.com",
"download_url": "https://files.pythonhosted.org/packages/e7/a6/543f2fb157ad228fcc04a8974aa16c989058834d8e539608814cf722f1b3/pytest-docker-3.1.1.tar.gz",
"platform": null,
"description": "Docker-based integration tests\n=====\n\n[](https://pypi.org/project/pytest-docker/)\n[](https://github.com/avast/pytest-docker/actions/workflows/tests.yaml)\n[](https://pypi.org/project/pytest-docker/)\n[](https://github.com/psf/black)\n\n# Description\n\nSimple [pytest](http://doc.pytest.org/) fixtures that help you write integration\ntests with Docker and [Docker Compose](https://docs.docker.com/compose/).\nSpecify all necessary containers in a `docker-compose.yml` file and and\n`pytest-docker` will spin them up for the duration of your tests.\n\n`pytest-docker` was originally created by Andr\u00e9 Caron.\n\n# Installation\n\nInstall `pytest-docker` with `pip` or add it to your test requirements.\n\nBy default, it uses the `docker compose` command, so it relies on the Compose plugin for Docker (also called Docker Compose V2).\n\n## Docker Compose V1 compatibility\n\nIf you want to use the old `docker-compose` command (deprecated since July 2023, not receiving updates since 2021)\n then you can do it using the [`docker-compose-command`](#docker_compose_command) fixture:\n\n```python\n@pytest.fixture(scope=\"session\")\ndef docker_compose_command() -> str:\n return \"docker-compose\"\n```\n\nIf you want to use the pip-distributed version of `docker-compose` command, you can install it using\n\n```\npip install pytest-docker[docker-compose-v1]\n```\n\nAnother option could be usage of [`compose-switch`](https://github.com/docker/compose-switch).\n\n# Usage\n\nHere is an example of a test that depends on a HTTP service.\n\nWith a `docker-compose.yml` file like this (using the\n[httpbin](https://httpbin.org/) service):\n\n```yaml\nversion: '2'\nservices:\n httpbin:\n image: \"kennethreitz/httpbin\"\n ports:\n - \"8000:80\"\n```\n\nYou can write a test like this:\n\n```python\nimport pytest\nimport requests\n\nfrom requests.exceptions import ConnectionError\n\n\ndef is_responsive(url):\n try:\n response = requests.get(url)\n if response.status_code == 200:\n return True\n except ConnectionError:\n return False\n\n\n@pytest.fixture(scope=\"session\")\ndef http_service(docker_ip, docker_services):\n \"\"\"Ensure that HTTP service is up and responsive.\"\"\"\n\n # `port_for` takes a container port and returns the corresponding host port\n port = docker_services.port_for(\"httpbin\", 80)\n url = \"http://{}:{}\".format(docker_ip, port)\n docker_services.wait_until_responsive(\n timeout=30.0, pause=0.1, check=lambda: is_responsive(url)\n )\n return url\n\n\ndef test_status_code(http_service):\n status = 418\n response = requests.get(http_service + \"/status/{}\".format(status))\n\n assert response.status_code == status\n```\n\nBy default this plugin will try to open `docker-compose.yml` in your\n`tests` directory. If you need to use a custom location, override the\n`docker_compose_file` fixture inside your `conftest.py` file:\n\n```python\nimport os\nimport pytest\n\n\n@pytest.fixture(scope=\"session\")\ndef docker_compose_file(pytestconfig):\n return os.path.join(str(pytestconfig.rootdir), \"mycustomdir\", \"docker-compose.yml\")\n```\n\n## Available fixtures\n\nBy default the scope of the fixtures are `session` but can be changed with\n`pytest` command line option `--container-scope <scope>`:\n\n```bash\npytest --container-scope <scope> <test_directory>\n```\n\nFor available scopes and descriptions\nsee <https://docs.pytest.org/en/6.2.x/fixture.html#fixture-scopes>\n\n### `docker_ip`\n\nDetermine the IP address for TCP connections to Docker containers.\n\n### `docker_compose_file`\n\nGet an absolute path to the `docker-compose.yml` file. Override this fixture in\nyour tests if you need a custom location.\n\n### `docker_compose_project_name`\n\nGenerate a project name using the current process PID. Override this fixture in\nyour tests if you need a particular project name.\n\n### `docker_services`\n\nStart all services from the docker compose file (`docker-compose up`).\nAfter test are finished, shutdown all services (`docker-compose down`).\n\n### `docker_compose_command`\n\nDocker Compose command to use to execute Dockers. Default is to use\nDocker Compose V2 (command is `docker compose`). If you want to use\nDocker Compose V1, change this fixture to return `docker-compose`.\n\n### `docker_setup`\n\nGet the list of docker_compose commands to be executed for test spawn actions.\nOverride this fixture in your tests if you need to change spawn actions.\nReturning anything that would evaluate to False will skip this command.\n\n### `docker_cleanup`\n\nGet the list of docker_compose commands to be executed for test clean-up actions.\nOverride this fixture in your tests if you need to change clean-up actions.\nReturning anything that would evaluate to False will skip this command.\n\n# Development\n\nUse of a virtual environment is recommended. See the\n[venv](https://docs.python.org/3/library/venv.html) package for more\ninformation.\n\nFirst, install `pytest-docker` and its test dependencies:\n\n```bash\npip install -e \".[tests]\"\n```\n\nRun tests with\n\n```bash\npytest -c setup.cfg\n```\n\nto make sure that the correct configuration is used. This is also how tests are\nrun in CI.\n\nUse [black](https://pypi.org/project/black/) with default settings for\nformatting. You can also use `pylint` with `setup.cfg` as the configuration\nfile as well as `mypy` for type checking.\n\n# Contributing\n\nThis `pytest` plug-in and its source code are made available to you under a MIT\nlicense. It is safe to use in commercial and closed-source applications. Read\nthe license for details!\n\nFound a bug? Think a new feature would make this plug-in more practical? We\nwelcome issues and pull requests!\n\nWhen creating a pull request, be sure to follow this projects conventions (see\nabove).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple pytest fixtures for Docker and Docker Compose based tests",
"version": "3.1.1",
"project_urls": {
"Homepage": "https://github.com/avast/pytest-docker"
},
"split_keywords": [
"docker",
"docker-compose",
"pytest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1aa469defc13bf77ee5aeb3e7b7c45393d6c7312e9c4d8b55d280a094ff76ff3",
"md5": "bb96f7231334d2f3f17f8cb941a91907",
"sha256": "fd0d48d6feac41f62acbc758319215ec9bb805c2309622afb07c27fa5c5ae362"
},
"downloads": -1,
"filename": "pytest_docker-3.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb96f7231334d2f3f17f8cb941a91907",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8243,
"upload_time": "2024-02-02T09:18:10",
"upload_time_iso_8601": "2024-02-02T09:18:10.610824Z",
"url": "https://files.pythonhosted.org/packages/1a/a4/69defc13bf77ee5aeb3e7b7c45393d6c7312e9c4d8b55d280a094ff76ff3/pytest_docker-3.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7a6543f2fb157ad228fcc04a8974aa16c989058834d8e539608814cf722f1b3",
"md5": "cb2cf49219aa895b8ed9e3552aa64da6",
"sha256": "2371524804a752aaa766c79b9eee8e634534afddb82597f3b573da7c5d6ffb5f"
},
"downloads": -1,
"filename": "pytest-docker-3.1.1.tar.gz",
"has_sig": false,
"md5_digest": "cb2cf49219aa895b8ed9e3552aa64da6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12918,
"upload_time": "2024-02-02T09:18:11",
"upload_time_iso_8601": "2024-02-02T09:18:11.740183Z",
"url": "https://files.pythonhosted.org/packages/e7/a6/543f2fb157ad228fcc04a8974aa16c989058834d8e539608814cf722f1b3/pytest-docker-3.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 09:18:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avast",
"github_project": "pytest-docker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytest-docker"
}
JSON
