Package: pytest-docker
Docker-based integration testsDescriptionSimplepytestfixtures that help you write integration
tests with Docker andDocker Compose.
Specify all necessary containers in adocker-compose.ymlfile and andpytest-dockerwill spin them up for the duration of your tests.pytest-dockerwas originally created by André Caron.InstallationInstallpytest-dockerwithpipor add it to your test requirements.By default, it uses thedocker composecommand, so it relies on the Compose plugin for Docker (also called Docker Compose V2).Docker Compose V1 compatibilityIf you want to use the olddocker-composecommand (deprecated since July 2023, not receiving updates since 2021)
then you can do it using thedocker-compose-commandfixture:@pytest.fixture(scope="session")defdocker_compose_command()->str:return"docker-compose"If you want to use the pip-distributed version ofdocker-composecommand, you can install it usingpip install pytest-docker[docker-compose-v1]Another option could be usage ofcompose-switch.UsageHere is an example of a test that depends on a HTTP service.With adocker-compose.ymlfile like this (using thehttpbinservice):version:'2'services:httpbin:image:"kennethreitz/httpbin"ports:-"8000:80"You can write a test like this:importpytestimportrequestsfromrequests.exceptionsimportConnectionErrordefis_responsive(url):try:response=requests.get(url)ifresponse.status_code==200:returnTrueexceptConnectionError:returnFalse@pytest.fixture(scope="session")defhttp_service(docker_ip,docker_services):"""Ensure that HTTP service is up and responsive."""# `port_for` takes a container port and returns the corresponding host portport=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))returnurldeftest_status_code(http_service):status=418response=requests.get(http_service+"/status/{}".format(status))assertresponse.status_code==statusBy default this plugin will try to opendocker-compose.ymlin yourtestsdirectory. If you need to use a custom location, override thedocker_compose_filefixture inside yourconftest.pyfile:importosimportpytest@pytest.fixture(scope="session")defdocker_compose_file(pytestconfig):returnos.path.join(str(pytestconfig.rootdir),"mycustomdir","docker-compose.yml")Available fixturesBy default the scope of the fixtures aresessionbut can be changed withpytestcommand line option--container-scope <scope>:pytest--container-scope<scope><test_directory>For available scopes and descriptions
seehttps://docs.pytest.org/en/6.2.x/fixture.html#fixture-scopesdocker_ipDetermine the IP address for TCP connections to Docker containers.docker_compose_fileGet an absolute path to thedocker-compose.ymlfile. Override this fixture in
your tests if you need a custom location.docker_compose_project_nameGenerate a project name using the current process PID. Override this fixture in
your tests if you need a particular project name.docker_servicesStart all services from the docker compose file (docker-compose up).
After test are finished, shutdown all services (docker-compose down).docker_compose_commandDocker Compose command to use to execute Dockers. Default is to use
Docker Compose V2 (command isdocker compose). If you want to use
Docker Compose V1, change this fixture to returndocker-compose.docker_setupGet 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_cleanupGet 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.DevelopmentUse of a virtual environment is recommended. See thevenvpackage for more
information.First, installpytest-dockerand its test dependencies:pipinstall-e".[tests]"Run tests withpytest-csetup.cfgto make sure that the correct configuration is used. This is also how tests are
run in CI.Useblackwith default settings for
formatting. You can also usepylintwithsetup.cfgas the configuration
file as well asmypyfor type checking.ContributingThispytestplug-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).