Manages Docker containers during your integration tests
Project description
This package contains a pytest plugin for integrating Docker Compose into your automated integration tests.
Given a path to a docker-compose.yml file, it will automatically build the project at the start of the test run, bring the containers up before each test starts, and tear them down after each test ends.
Dependencies
Make sure you have Docker installed.
This plugin has been tested against the following software:
- Python 3.6
- pytest 3.4 and 3.5.
Note
This plugin is not compatible with Python 2.
Installation
Install the plugin using pip:
> pip install pytest-docker-compose
Usage
For performance reasons, the plugin is not enabled by default, so you must activate it manually in the tests that use it:
pytest_plugins = ["docker_compose"]
See Installing and Using Plugins for more information.
To interact with Docker containers in your tests, use the following fixtures:
- docker_network_info
A list of pytest_docker_compose.NetworkInfo objects for each container, grouped by service name.
This information can be used to configure API clients and other objects that will connect to services exposed by the Docker containers in your tests.
NetworkInfo is a container with the following fields:
- container_port: The port (and usually also protocol name) exposed internally to the container. You can use this value to find the correct port for your test, when the container exposes multiple ports.
- hostname: The hostname (usually “localhost”) to use when connecting to the service from the host.
- host_port: The port number to use when connecting to the service from the host.
Tip
Unless you need to interface directly with Docker primitives, this is the correct fixture to use in your tests.
- docker_containers
- A list of the Docker compose.container.Container objects running during the test.
- docker_project
- The compose.project.Project object that the containers are built from. This fixture is generally only used internally by the plugin.
Waiting for Services to Come Online
The fixture will wait until every container is up before handing control over to the test.
However, just because a container is up does not mean that the services running on it are ready to accept incoming requests yet!
If your tests need to wait for a particular condition (for example, to wait for an HTTP health check endpoint to send back a 200 response), make sure that your fixtures account for this.
Here’s a simple example of a fixture that waits for an HTTP service to come online before starting each test.
import pytest import typing from pytest_docker_compose import NetworkInfo from time import sleep, time from my_app import ApiClient pytest_plugins = ["docker_compose"] @pytest.fixture(name="api_client") def fixture_api_client( docker_network_info: typing.Dict[str, typing.List[NetworkInfo]], ) -> ApiClient: # ``docker_network_info`` is grouped by service name. service = docker_network_info["my_api_service"][0] # Create an instance of our custom application's API client. api_client = ApiClient( base_url=f"http://{service.hostname}:{service.host_port}/api/v1", ) # Wait for the HTTP service to be ready. start = time() timeout = 5 for name, network_info in docker_network_info.items(): while True: if time() - start >= timeout: raise RuntimeError( f"Unable to start all container services " "within {timeout} seconds.", ) try: if api_client.health_check()["status"] == "ok": break except (ConnectionError, KeyError): pass sleep(0.1) # HTTP service is up and listening for requests. return api_client # Tests can then interact with the API client directly. def test_frog_blast_the_vent_core(api_client: ApiClient): assert api_client.frog_blast_the_vent_core() == { "status": "I'm out of ammo!", }
Running Integration Tests
Use pytest to run your tests as normal:
pytest
By default, this will look for a docker-compose.yml file in the current working directory. You can specify a different file via the --docker-compose option:
pytest --docker-compose=/path/to/docker-compose.yml
Tip
Alternatively, you can specify this option in your pytest.ini file:
[pytest] addopts = --docker-compose=/path/to/docker-compose.yml
The option will be ignored for tests that do not use this plugin.
See Configuration Options for more information on using configuration files to modify pytest behavior.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pytest-docker-compose-1.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | ca82c60c9fb59e098a6be306f7b1d36fb2a494cbc2e4baf2d9b6aa5844a9bc58 |
|
MD5 | 686ad008e466eb6f2b42cfccf46b83e2 |
|
BLAKE2-256 | aae1430252ff01f55497d6e480269837e411bfebaffaea9fee244abcc1838e43 |
Hashes for pytest_docker_compose-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3589b15c209628e9d408671acecf10444d32fa3cc65295c8212ff10bc187a2f9 |
|
MD5 | 0bcb0554df4f83037323c853da6cc6e0 |
|
BLAKE2-256 | 7858ea49b322ddb188ce62febdc7c44e4e84bc76e522103d47ed6d2742bbbcf9 |