{"id":13501426,"url":"https://github.com/tox-dev/tox-docker","last_synced_at":"2025-04-04T08:09:52.882Z","repository":{"id":21238900,"uuid":"89016565","full_name":"tox-dev/tox-docker","owner":"tox-dev","description":"A tox plugin to run one or more Docker containers during tests","archived":false,"fork":false,"pushed_at":"2024-04-29T16:54:25.000Z","size":232,"stargazers_count":173,"open_issues_count":22,"forks_count":39,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-05-09T21:59:45.109Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tox-dev.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-21T19:22:15.000Z","updated_at":"2024-06-04T13:34:37.730Z","dependencies_parsed_at":"2024-04-15T18:06:36.253Z","dependency_job_id":"fa72c864-14d5-4cbf-85a4-f9c89acd0f49","html_url":"https://github.com/tox-dev/tox-docker","commit_stats":{"total_commits":182,"total_committers":12,"mean_commits":"15.166666666666666","dds":"0.31868131868131866","last_synced_commit":"c1564b7165addf43245863cac60de2e42bde0d3d"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tox-dev%2Ftox-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tox-dev","download_url":"https://codeload.github.com/tox-dev/tox-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142074,"owners_count":20890653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T22:01:37.141Z","updated_at":"2025-04-04T08:09:52.864Z","avatar_url":"https://github.com/tox-dev.png","language":"Python","readme":"============\n tox-docker\n============\n\nA `tox \u003chttps://tox.wiki/en/latest/\u003e`__ plugin which runs one or\nmore `Docker \u003chttps://www.docker.com/\u003e`__ containers during the test run.\n\nLinks: `Source Code \u003chttps://github.com/tox-dev/tox-docker\u003e`__ |\n`Documentation \u003chttps://tox-docker.readthedocs.io/en/latest/\u003e`__\n\n.. image:: https://dev.azure.com/dcrosta/tox-docker/_apis/build/status/tox-dev.tox-docker?branchName=master\n   :target: https://dev.azure.com/dcrosta/tox-docker/_build?definitionId=1\u0026_a=summary\n   :alt: Build Status\n\nUsage and Installation\n----------------------\n\ntox loads all plugins automatically. To use tox-docker, ``pip install`` it\ninto the same Python environment as you install tox into, whether that's a\nvirtualenv, etc.\n\nYou do not need to do anything special when running tox to invoke\ntox-docker, however you do need to configure your project to configure\ndocker containers (see \"Configuration\" below).\n\nConfiguration\n-------------\n\nEach docker container you want to run must be configured via a\n``[docker:container-name]`` section. The ``container-name`` is a name you\nchoose which must start with a letter and consist of only letters, numbers,\ndots, hyphens, and underscores. Each ``[docker:container-name]`` section must\ncontain at least an ``image`` directive, which must name a `Docker image\n\u003chttps://docs.docker.com/glossary/#image\u003e`__ as you'd pass to ``docker\nrun``; or a ``build`` directive, containing the path to a `Dockerfile\n\u003chttps://docs.docker.com/glossary/#dockerfile\u003e`__ as you'd pass to\n``docker build``::\n\n    [docker:db]\n    image = postgres:9-alpine\n\n    # OR\n\n    [docker:app]\n    dockerfile = {toxinidir}/Dockerfile\n\nThen, in your ``[testenv]``, use the ``docker`` directive to list containers\nyou wish to run during those tests::\n\n    [testenv]\n    docker =\n        db\n    commands = ...\n\nThe ``[docker:container-name]`` section may contain the following directives:\n\n``image``\n    The `Docker image \u003chttps://docs.docker.com/glossary/#image\u003e`__ to run.\n    This value is passed directly to Docker, and may be of any of the forms\n    that Docker accepts in eg ``docker run``. One of ``image`` or\n    ``dockerfile`` is required.\n\n``dockerfile``\n    Path to a `Dockerfile \u003chttps://docs.docker.com/glossary/#dockerfile\u003e`__\n    to build and run. One of ``dockerfile`` or ``image`` is required.\n\n``dockerfile_target``\n    Name of the build-stage to build in a multi-stage Dockerfile. An error\n    is raised if ``dockerfile_target`` is set without ``dockerfile`` set.\n\n``environment``\n    A multi-line list of ``KEY=value`` settings which is used to set\n    environment variables for the container. The variables are only available\n    to the container, not to other containers or the test environment.\n\n``expose``\n    A multi-line list of port mapping specifications, as\n    ``ENV_VAR=CONTAINER_PORT/PROTO``. Within the testenv, the environment\n    variable ``ENV_VAR`` will contain the port number to connect to the\n    docker container's ``EXPOSE`` d port. If ``expose`` is specified, only\n    the listed ports will have environment variables created for them.\n\n    If ``expose`` is not specified, all the container's ``EXPOSE`` d ports\n    are made available (equivalent to ``docker run -P ...``) using default\n    environment variable names of the form\n    ``\u003ccontainer-name\u003e_\u003cport-number\u003e_\u003cprotocol\u003e_PORT`` (eg ``NGINX_80_TCP_PORT``\n    or ``TELEGRAF_8092_UDP_PORT``), with the container name and protocol\n    converted to upper case, and non-alphanumeric characters replaced with an\n    underscore (``_``).\n\n``host_var``\n    The name of an environment variable that will contain the hostname or IP\n    address to use to communicate with the container. Defaults to\n    ``\u003ccontainer_name\u003e_HOST`` if not set, with the container name converted to\n    upper case, and non-alphanumeric characters replaced with an underscore\n    (``_``).\n\n``links``\n    A multi-line list of `container links\n    \u003chttps://docs.docker.com/network/links/\u003e`__, as ``other-container-name``\n    or ``other-container-name:alias``. If no alias is given, the\n    ``other-container-name`` is used. Within the container, the ``EXPOSE`` d\n    ports of the other container will be available via the alias as hostname.\n\n    When using links, you must specify containers in the correct start order\n    in the ``docker`` directive of your testenv -- tox-docker does not attempt\n    to resolve a valid start order.\n\n``volumes``\n    A multi-line list of `volumes\n    \u003chttps://docs.docker.com/storage/volumes/\u003e`__ to make available to the\n    container, as ``\u003ctype\u003e:\u003coptions\u003e:\u003coutside_path_or_name\u003e:\u003cinside_path\u003e``.\n    The ``type`` must be ``bind``, and the only supported options are ``rw``\n    (read-write) or ``ro`` (read-only). The ``outside_path_or_name`` must\n    be a path that exists on the host system. Both the ``outside_path``\n    and ``inside_path`` must be absolute paths.\n\n``healthcheck_cmd``, ``healthcheck_interval``, ``healthcheck_retries``, ``healthcheck_start_period``, ``healthcheck_timeout``\n    These set or customize parameters of the container `health check\n    \u003chttps://docs.docker.com/engine/reference/builder/#healthcheck\u003e`__. The\n    ``healthcheck_interval``, ``healthcheck_start_period``, and\n    ``healthcheck_timeout`` are specified as a number of seconds.\n    ``healthcheck_cmd`` is an argv list which must name a command and\n    arguments that can be run within the container; if not specified, any\n    health check built in to the container is used.\n\n    If any healthcheck parameters are defined, tox-docker will delay the\n    test run until the container reports healthy, and will fail the test\n    run if it never does so (within the parameters specified).\n\nCommand-Line Arguments\n----------------------\n\nAll Docker container configuration is specified in ``tox.ini``, but some\naspects of tox-docker's behavior can be changed at run-time:\n\n``--docker-dont-stop=CONTAINER``\n    After the test run, don't stop \u0026 remove the named ``CONTAINER`` --\n    leaving the container running allows manual inspection of it, eg via\n    ``docker exec ...``. May be specified multiple times to leave several\n    containers running.\n\nContainer Naming \u0026 Parallel Runs\n--------------------------------\n\nSince version 4, tox-docker adds a suffix to the name of running containers,\nso that parallel invocations of tox may succeed (eg on a busy CI server).\nThe details of the name suffix are not specified, and may change in a future\nversion -- you should not rely on the details of the generated name.\n\nEven with unique container names, parallel runs may still fail, if you map a\nstatic exposed port number for a container (as the tox host will not let two\nprocesses bind the same port).\n\nExample\n-------\n\n.. code-block:: ini\n\n    [testenv:integration-tests]\n    deps = pytest\n    commands = py.test {toxinidir}/tests\n    docker =\n        db\n        appserv\n\n    [docker:db]\n    image = postgres:11-alpine\n    # Environment variables are passed to the container. They are only\n    # available to that container, and not to the testenv, other\n    # containers, or as replacements in other parts of tox.ini\n    environment =\n        POSTGRES_PASSWORD=hunter2\n        POSTGRES_USER=dbuser\n        POSTGRES_DB=tox_test_db\n    # The healthcheck ensures that tox-docker won't run tests until the\n    # container is up and the command finishes with exit code 0 (success)\n    healthcheck_cmd = PGPASSWORD=$POSTGRES_PASSWORD psql \\\n        --user=$POSTGRES_USER --dbname=$POSTGRES_DB \\\n        --host=127.0.0.1 --quiet --no-align --tuples-only \\\n        -1 --command=\"SELECT 1\"\n    healthcheck_timeout = 1\n    healthcheck_retries = 30\n    healthcheck_interval = 1\n    healthcheck_start_period = 1\n    # Configure a bind-mounted volume on the host to store Postgres' data\n    # NOTE: this is included for demonstration purposes of tox-docker's\n    # volume capability; you probably _don't_ want to do this for real\n    # testing use cases, as this could persist data between test runs\n    volumes =\n        bind:rw:/my/own/datadir:/var/lib/postgresql/data\n\n    [docker:appserv]\n    # You can use any value that `docker run` would accept as the image\n    image = your-registry.example.org:1234/your-appserv\n    # Within the appserv container, host \"db\" is linked to the postgres container\n    links =\n        db:db\n    # Expose ports to the testenv\n    expose =\n        APP_HTTP_PORT=8080/tcp\n\n\nEnvironment Variables\n---------------------\n\nIf you are running in a Docker-In-Docker environment, you can override the address\nused for port checking using the environment variable ``TOX_DOCKER_GATEWAY``. This\nvariable should be the hostname or ip address used to connect to the container.\n\nVersion Compatibility\n---------------------\n\nTox-docker requires tox to be run in Python 3.8 or newer, and requires tox\nversion 4 or newer. Older versions of tox-docker may work with older\nversions of Python or tox, but these configurations are no longer supported.\n\nUpgrading\n---------\n\nSome configuration options were removed:\n\nNew in 5.0:\n\n``ports``\n    This directive was removed in tox-docker version 5.0. Use ``expose``\n    instead. The ability to map a container port to a specific host port was\n    completely removed.\n\n\n==========\nChange Log\n==========\n\n* 5.0.1 (unreleased)\n    * Corrected link \u0026 typos in README (thanks @kurtmckee)\n    * Removed redundant seed-isort-config precommit hook (thanks @kurtmckee)\n    * Fixed CI on Python 3.12\n* 5.0.0\n    * Remove support for tox 3\n    * Removed support for Python 3.7 and earlier\n    * Remove ``ports``; add ``expose`` and ``host_var``\n    * Support ``docker`` (the Python module) 7.x (thanks @jonathangreen)\n* 4.1.1\n    * Fix typo in README (thanks @akx)\n* 4.1.0\n    * Drop test support for docker (Python library) 3.x; add test support\n      for docker 6.x. Other versions may work, but we only support tested\n      versions.\n    * Add support for ``dockerfile`` and ``dockerfile_target`` directives\n      to build local images\n* 4.0.0\n    * Support tox 4 as well as tox 3\n    * Drop support for Python 3.6\n    * Give running containers a unique name to support concurrent \u0026 parallel\n      tox use cases (thanks @chaitu-tk and @goodtune for inspiration)\n    * Add support for image registry URLs that contain a port\n* 3.1.0\n    * Support docker-py 5.x\n* 3.0.0\n    * Support tox 3 and newer only\n    * Automatically cleans up started docker containers, even if Tox\n      encounters an error during the test run (thanks @d9pouces)\n* 2.0.0\n    * Support Python 3.6 and newer only\n    * Move all container configuration to ``[docker:container-name]``\n      sections\n    * Don't infer container health by pinging TCP ports; only the\n      healthcheck indicates a container's health\n\n\n===========\nDevelopment\n===========\n\nCode Style\n----------\n\nTox-docker uses black and isort to enforce style standards on the codebase.\nThe formatting is ordinarily done for you via `pre-commit\n\u003chttps://pre-commit.com/\u003e`_, and is enforced via the ``tox -e style`` build.\nTo work on tox-docker locally with pre-commit, `pip install -r\ndev-requirements.txt`` and ``pre-commit install`` to set up the git hooks;\nsubsequently, when you ``git commit``, the formatter will be run. If the\nchanged files are not conformant, the hook will have reformatted them and\nyou may need to run pre-commit again. You can run ``pre-commit run --files\n*.py`` to manually run the formatters.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Ftox-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftox-dev%2Ftox-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftox-dev%2Ftox-docker/lists"}