# Lovely Pytest Docker
[](https://pypi.org/project/lovely-pytest-docker/)
[](https://pypi.org/project/lovely-pytest-docker/)
[](https://app.travis-ci.com/lovelysystems/lovely-pytest-docker)
Create simple Pytest_ fixtures for writing integration tests based on Docker
containers. The framework provides a service class to start and stop containers
based Docker Compose. Each single container can be started individually.
Some parts of this package are taken from
https://github.com/AndreLouisCaron/pytest-docker
## Usage with Pytest
The docker compose file should contain all desired containers and the ports
should be exposed. In the following example we want to start the app to test
and a SQL database (Crate). Let's assume there is a ``Dockerfile`` for the app
in the same folder as the docker compose file.
```yaml
version: "3"
services:
app:
build: .
ports:
- "8080"
depends_on:
- "crate"
crate:
image: crate:latest
ports:
- "4200"
```
In the ``conftest.py`` file we can declare the docker fixtures for each service
we want to be able to start in the tests.
```python
import pytest
@pytest.fixture(scope='session')
def docker_app(docker_services):
docker_services.start('app')
public_port = docker_services.wait_for_service("app", 8080)
url = "http://{docker_services.docker_ip}:{public_port}".format(**locals())
return url
@pytest.fixture(scope='session')
def docker_crate(docker_services):
docker_services.start('crate')
public_port = docker_services.wait_for_service("crate", 4200)
dsn = "{docker_services.docker_ip}:{public_port}".format(**locals())
return dsn
```
By default the fixture will look for the ``docker-compose.yml`` file in the
``tests`` subfolder of the path where ``pytest.ini`` resides (or the project's
root directory if no ini file is given - as in the tests example). In many
cases you will want to override the location for the docker compose files. Just
overwrite the ``docker_compose_files`` fixture in your ``conftest.py`` file.
```python
@pytest.fixture(scope='session')
def docker_compose_files(pytestconfig):
"""Get the docker-compose.yml absolute path.
Override this fixture in your tests if you need a custom location.
"""
return [
project_path('docker', 'docker-compose.yml'),
]
```
In your test file declare the fixtures you want to use:
```python
def test_something(docker_app, docker_crate):
# e.g. initialize database
...
# test something (e.g. request to docker_app)
...
```
A working configuration and test example can be found in the ``tests`` folder
of this package.
## Execution in Docker Container
It's possible to execute a command inside one of the Docker containers. Use
the ``exec`` method of the ``docker_services`` fixture::
```python
def test_execute(docker_services):
# the first argument is the service name of the compose file,
# the following arguments build the command to run
res = docker_services.execute('crate', 'ls', '-a')
```
## Stopping a Docker Container
It's possible to stop single Docker containers. Use
the ``stop`` method of the ``docker_services`` fixture::
def test_stop(docker_services):
# the first argument is the service name of the compose file,
# the following arguments build the command to run
res = docker_services.stop('crate')
## Wait for Service
The ``wait_for_service`` method of the service module checks whether the
docker service is really started. By default it makes a HTTP GET request to the
server's ``/`` endpoint. The service will retry to check until a timeout of
30 seconds has passed.
### Custom Service Checker
Some services may work differently and require a custom checker.
Create a custom service checker function which receives the IP address and the
port as parameters::
```python
def custom_service_checker(ip_address, port):
# if service is ready
return True
# otherwise return False
```
In the fixture provide the custom service checker function as ``check_service``
parameter to the ``wait_for_service`` method::
```python
@pytest.fixture(scope='session')
def docker_custom_service(docker_services):
docker_services.start('custom_service')
public_port = docker_services.wait_for_service(
"app",
8080,
check_server=custom_service_checker
)
url = "http://{docker_services.docker_ip}:{public_port}".format(**locals())
return url
```
To use another request path with the default checker the `url_checker` method
can be used to create a `check_url` method for another path::
```python
docker_services.wait_for_service(
"app",
8080,
check_server=url_checker('/probe_status'),
)
```
## Run Tests
Tests are held in the ``tests`` directory. Running tests is done via the
[pytest](http://doc.pytest.org) package with::
```shell
./gradlew pytest
```
## Publish a new Version
Use gradle to build and twine to upload like this:
```shell
./gradlew sdist
twine upload build/sdist/lovely-pytest-docker-<version>.tar.gz
```
Note: twine needs to be installed by othher means (e.g. ``pip install twine``)
Raw data
{
"_id": null,
"home_page": "https://github.com/lovelysystems/lovely-pytest-docker",
"name": "lovely-pytest-docker",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "pytest testing docker compose",
"author": "Lovely Systems",
"author_email": "office@lovelysystems.com",
"download_url": "https://files.pythonhosted.org/packages/44/ee/f0093b5b13ea0726e2a9e44da30b9018ab512d38728d84a879f427dc9ea4/lovely_pytest_docker-1.0.0.tar.gz",
"platform": null,
"description": "# Lovely Pytest Docker\n\n[](https://pypi.org/project/lovely-pytest-docker/)\n[](https://pypi.org/project/lovely-pytest-docker/)\n[](https://app.travis-ci.com/lovelysystems/lovely-pytest-docker)\n\nCreate simple Pytest_ fixtures for writing integration tests based on Docker\ncontainers. The framework provides a service class to start and stop containers\nbased Docker Compose. Each single container can be started individually.\n\nSome parts of this package are taken from\nhttps://github.com/AndreLouisCaron/pytest-docker\n\n## Usage with Pytest\n\nThe docker compose file should contain all desired containers and the ports\nshould be exposed. In the following example we want to start the app to test\nand a SQL database (Crate). Let's assume there is a ``Dockerfile`` for the app\nin the same folder as the docker compose file.\n\n```yaml\n\n\nversion: \"3\"\nservices:\n app:\n build: .\n ports:\n - \"8080\"\n depends_on:\n - \"crate\"\n\n crate:\n image: crate:latest\n ports:\n - \"4200\"\n```\n\nIn the ``conftest.py`` file we can declare the docker fixtures for each service\nwe want to be able to start in the tests.\n\n```python\n\n import pytest\n\n @pytest.fixture(scope='session')\n def docker_app(docker_services):\n docker_services.start('app')\n public_port = docker_services.wait_for_service(\"app\", 8080)\n url = \"http://{docker_services.docker_ip}:{public_port}\".format(**locals())\n return url\n\n @pytest.fixture(scope='session')\n def docker_crate(docker_services):\n docker_services.start('crate')\n public_port = docker_services.wait_for_service(\"crate\", 4200)\n dsn = \"{docker_services.docker_ip}:{public_port}\".format(**locals())\n return dsn\n```\n\nBy default the fixture will look for the ``docker-compose.yml`` file in the\n``tests`` subfolder of the path where ``pytest.ini`` resides (or the project's\nroot directory if no ini file is given - as in the tests example). In many\ncases you will want to override the location for the docker compose files. Just\noverwrite the ``docker_compose_files`` fixture in your ``conftest.py`` file.\n\n```python\n @pytest.fixture(scope='session')\n def docker_compose_files(pytestconfig):\n \"\"\"Get the docker-compose.yml absolute path.\n Override this fixture in your tests if you need a custom location.\n \"\"\"\n return [\n project_path('docker', 'docker-compose.yml'),\n ]\n```\n\nIn your test file declare the fixtures you want to use:\n\n```python\n def test_something(docker_app, docker_crate):\n # e.g. initialize database\n ...\n # test something (e.g. request to docker_app)\n ...\n```\n\nA working configuration and test example can be found in the ``tests`` folder\nof this package.\n\n## Execution in Docker Container\n\nIt's possible to execute a command inside one of the Docker containers. Use\nthe ``exec`` method of the ``docker_services`` fixture::\n\n```python\n def test_execute(docker_services):\n # the first argument is the service name of the compose file,\n # the following arguments build the command to run\n res = docker_services.execute('crate', 'ls', '-a')\n```\n\n## Stopping a Docker Container\n\nIt's possible to stop single Docker containers. Use\nthe ``stop`` method of the ``docker_services`` fixture::\n\n def test_stop(docker_services):\n # the first argument is the service name of the compose file,\n # the following arguments build the command to run\n res = docker_services.stop('crate')\n\n## Wait for Service\n\nThe ``wait_for_service`` method of the service module checks whether the\ndocker service is really started. By default it makes a HTTP GET request to the\nserver's ``/`` endpoint. The service will retry to check until a timeout of\n30 seconds has passed.\n\n### Custom Service Checker\n\nSome services may work differently and require a custom checker.\n\nCreate a custom service checker function which receives the IP address and the\nport as parameters::\n\n```python\n def custom_service_checker(ip_address, port):\n # if service is ready\n return True\n # otherwise return False\n```\n\nIn the fixture provide the custom service checker function as ``check_service``\nparameter to the ``wait_for_service`` method::\n\n```python\n @pytest.fixture(scope='session')\n def docker_custom_service(docker_services):\n docker_services.start('custom_service')\n public_port = docker_services.wait_for_service(\n \"app\",\n 8080,\n check_server=custom_service_checker\n )\n url = \"http://{docker_services.docker_ip}:{public_port}\".format(**locals())\n return url\n```\n\nTo use another request path with the default checker the `url_checker` method\ncan be used to create a `check_url` method for another path::\n\n```python\n docker_services.wait_for_service(\n \"app\",\n 8080,\n check_server=url_checker('/probe_status'),\n )\n```\n\n## Run Tests\n\nTests are held in the ``tests`` directory. Running tests is done via the\n[pytest](http://doc.pytest.org) package with::\n\n```shell\n ./gradlew pytest\n```\n\n## Publish a new Version\n\nUse gradle to build and twine to upload like this:\n\n```shell\n ./gradlew sdist\n twine upload build/sdist/lovely-pytest-docker-<version>.tar.gz\n```\n\nNote: twine needs to be installed by othher means (e.g. ``pip install twine``)\n",
"bugtrack_url": null,
"license": null,
"summary": "Pytest testing utilities with docker containers.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/lovelysystems/lovely-pytest-docker"
},
"split_keywords": [
"pytest",
"testing",
"docker",
"compose"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "44eef0093b5b13ea0726e2a9e44da30b9018ab512d38728d84a879f427dc9ea4",
"md5": "07404383fe03ada83b1065229bdb70a2",
"sha256": "7283abfe400c31ecc7155f9338c6f5af476f2ab506e1aadb9f7e9a5005e491d6"
},
"downloads": -1,
"filename": "lovely_pytest_docker-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "07404383fe03ada83b1065229bdb70a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12901,
"upload_time": "2024-09-02T11:48:44",
"upload_time_iso_8601": "2024-09-02T11:48:44.075871Z",
"url": "https://files.pythonhosted.org/packages/44/ee/f0093b5b13ea0726e2a9e44da30b9018ab512d38728d84a879f427dc9ea4/lovely_pytest_docker-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 11:48:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lovelysystems",
"github_project": "lovely-pytest-docker",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [],
"lcname": "lovely-pytest-docker"
}
JSON
