Metadata-Version: 2.1
Name: dockerfixtures
Version: 0.2.4
Summary: Cointainers as Pytest fixtures made easy
Home-page: https://github.com/cans/python-docker-fixtures
Author: Nicolas CANIART
Author-email: nicolas@caniart.net
License: GPLv2
Project-URL: Code, https://github.com/cans/python-docker-fixtures
Project-URL: Issue-tracker, https://github.com/cans/python-docker-fixtures/issues
Keywords: docker,testing,fixtures
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.12,>=3.7
Description-Content-Type: text/x-rst
License-File: COPYING
Requires-Dist: docker (~=4.1)
Provides-Extra: dev
Requires-Dist: build ; extra == 'dev'
Requires-Dist: coverage ; extra == 'dev'
Requires-Dist: kafka-python ; extra == 'dev'
Requires-Dist: pre-commit (<2.10.0) ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-mock ; extra == 'dev'
Requires-Dist: Sphinx ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: pdbpp ; (python_version < "3.9") and extra == 'dev'
Requires-Dist: ipdb ; (python_version >= "3.9") and extra == 'dev'

============================================
Docker containers as test fixtures made easy
============================================

.. image:: https://badge.fury.io/py/dockerfixtures.svg
    :alt: Latest version on Pypi: ?
    :target: https://badge.fury.io/py/dockerfixtures
.. image:: https://img.shields.io/pypi/pyversions/dockerfixtures.svg
    :alt: Supported Python versions: ?
    :target: https://pypi.org/project/dockerfixtures
.. image:: https://travis-ci.com/cans/python-docker-fixtures.svg?branch=master
    :alt: Build status (travis.com): ?
    :target: https://travis-ci.com/cans/python-docker-fixtures
.. image:: https://circleci.com/gh/cans/python-docker-fixtures.svg?style=svg
    :alt: Build status (circleci.com): ?
    :target: https://circleci.com/gh/cans/python-docker-fixtures
.. image:: https://codecov.io/gh/cans/python-docker-fixtures/branch/master/graph/badge.svg
    :alt: Test coverage: ? %
    :target: https://codecov.io/gh/cans/python-docker-fixtures


This package was inspired by others, but after trying to make heads and tails
of them when faced with bugs, I ended-up finding simpler to start over.

Using dockerfixtures with pytest
================================

To spawn a container in your tests, proceed as follow:

.. code-block:: Python

    import docker
    from dockerfixtures import image, container
    import pytest

    @pytest.fixture(scope='session')
    def docker_client():
         return docker.from_env()

    @pytest.fixture(scope='session')
    def pg_image() -> image.Image:
        return image.Image('postgres', tags='12')

    @pytest.fixture(scope='function')
    def pg_container(docker_client: docker.client.DockerClient,
                     pg_image: image.Image) -> container.Container:
        yield from container.fixture(docker_client, some_image)

    # If you don't need to reuse the image

    @pytest.fixture(scope='session')
    def pg_container(docker_client) -> container.Container:
        some_image = image.Image('postgres', tags='12')
        yield from container.fixture(docker_client, some_image)


Why not a pytest plugin ?
=========================

Other implementation of this have been provinding a pytest
plugin, so you might wonder why this one doesn't ?

First reason is I have not looked into it that much, yet.

But anyhow, you would still need to import the
``dockerfixtures.image`` module. So I am not very sure what the
benefits would be ?

Also I found those plugins to provide somewhat bizarre API, for
example to define the fixtures' scope. I haven't looked into
why they do that, yet. Here there are no surprises, a container
fixture looks like any other fixture.

Pytest plugins are global: they have to be imported in your
`top-level`_ ``conftest.py`` (see note). I think it is good
practice to keep your tests properly partitioned based on their
external dependencies. It can help split workload if the need
arises. In a collaborative environment, having to import
``dockerfixtures``, may help prevent breaking that partitioning
during reviews.


.. _top-level: https://docs.pytest.org/en/latest/writing_plugins.html#requiring-loading-plugins-in-a-test-module-or-conftest-file
