基本用法

a简单的 tox.ini / 默认环境

将有关项目和希望项目在其中运行的测试环境的基本信息放入 tox.ini 应该驻留在您的 setup.py 文件：

# content of: tox.ini , put in same dir as setup.py
[tox]
envlist = py27,py36
[testenv]
# install testing framework
# ... or install anything else you might need here
deps = pytest
# run the tests
# ... or run any other command line tool you need to run here
commands = pytest

要对项目进行sdist打包、安装和测试，现在可以在命令提示符下键入：

tox

这将对当前项目进行sdist打包，创建两个 virtualenv 环境中，将sdist-package安装到环境中，并在每个环境中运行指定的命令。使用：

tox -e py36

您可以将测试运行限制在python3.6环境中。

tox目前了解以下模式：

py: The current Python version tox is using
pypy: Whatever available PyPy there is
jython: Whatever available Jython there is
pyN: Python of version N. for example py2 or py3 ... etc
pyNM: Python of version N.M. for example py27 or py38 ... etc
pypyN: PyPy of version N. for example pypy2 or pypy3 ... etc
pypyNM: PyPy version N.M. for example pypy27 or pypy35 ... etc

但是，您也可以创建自己的测试环境名称，请参阅中的一些示例 examples .

pyproject.tomltox传统ini

tox 配置也可以在 pyproject.toml (如果要避免额外的文件)。

目前，通过以下方式仅支持旧格式 legacy_tox_ini 不过，计划进行本机实现。

[build-system]
requires = [ "setuptools >= 35.0.2", "wheel >= 0.29.0"]
build-backend = "setuptools.build_meta"

[tool.tox]
legacy_tox_ini = """
[tox]
envlist = py27,py36

[testenv]
deps = pytest >= 3.0.0, <4
commands = pytest
"""

请注意，当您定义 pyproject.toml 您必须定义 build-system 每节PEP-518。

指定平台

2.0 新版功能.

如果要指定您的测试环境在哪些平台上运行，您可以设置一个平台正则表达式，如下所示：

[testenv]
platform = linux2|darwin

如果表达式与 sys.platform 将跳过测试环境。

允许非Virtualenv命令

1.5 新版功能.

有时，您可能希望使用Virtualenv中未包含的工具，例如 make ， bash 或者其他人。若要避免警告，可以使用 allowlist_externals TESTNEV配置：

# content of tox.ini
[testenv]
allowlist_externals = make
                      /bin/bash

根据要求.txt或定义约束

1.6.1 新版功能.

(实验性)如果您有 requirements.txt 文件或 constraints.txt 文件，您可以将其添加到您的 deps 如下所示的变量：

[testenv]
deps = -rrequirements.txt

或

[testenv]
deps =
    -rrequirements.txt
    -cconstraints.txt

所有安装命令都使用以下命令执行 {{toxinidir}} (所在的目录 tox.ini 驻留)作为当前工作目录。因此，潜在的 pip 安装将假定 requirements.txt 或 constraints.txt 存在于：存在于 {{toxinidir}}/requirements.txt 或 {{toxinidir}}/constraints.txt .

这实际上是依赖项列表的所有元素都被直接传递到的副作用 pip .

有关以下内容的更多详细信息 requirements.txt 文件或 constraints.txt 文件请参阅：

• https://pip.pypa.io/en/stable/user_guide/#requirements-files

• https://pip.pypa.io/en/stable/user_guide/#constraints-files

使用不同的默认PyPI URL

要从不同的默认PyPI服务器安装依赖项和包，您可以交互键入：

tox -i https://pypi.my-alternative-index.org

这会导致tox安装依赖项，sdist安装步骤使用指定的URL作为索引服务器。

您可以通过使用 PIP_INDEX_URL 环境变量。此变量也可以在 tox.ini ：

[testenv]
setenv =
    PIP_INDEX_URL = https://pypi.my-alternative-index.org

或者，一种配置，其中 PIP_INDEX_URL 可以从环境中覆盖：

[testenv]
setenv =
    PIP_INDEX_URL = {env:PIP_INDEX_URL:https://pypi.my-alternative-index.org}

从多个PyPI服务器安装依赖项

您可以使用以下命令检测tox以安装来自多个PyPI服务器的依赖项 PIP_EXTRA_INDEX_URL 环境变量：

[testenv]
setenv =
    PIP_EXTRA_INDEX_URL = https://mypypiserver.org
deps =
    # docutils will be installed directly from PyPI
    docutils
    # mypackage missing at PyPI will be installed from custom PyPI URL
    mypackage

将安装此配置 docutils 并将从默认的Python PyPI服务器安装 mypackage 从我们的索引服务器(位于 https://mypypiserver.org URL。

警告

使用额外的PyPI索引安装私有软件包可能会导致安全问题。例如，如果 mypackage 注册了默认的PyPI索引，则pip将安装 mypackage 来自默认的PyPI索引，而不是来自自定义索引。

进一步自定义安装

1.6 新版功能.

默认情况下，毒素使用 pip 若要安装软件包，测试中的软件包和您在中指定的任何依赖项 tox.ini 。您可以完全自定义tox的install-command，通过特定于testenv的 install_command = ARGV 设置。例如，要使用pip的 --find-links 和 --no-index 用于为您的依赖项指定备用源的选项：

[testenv]
install_command = pip install --pre --find-links https://packages.example.com --no-index {opts} {packages}

强制重新创建虚拟环境

0.9 新版功能.

要强制TOX重新创建(特定)虚拟环境，请执行以下操作：

tox --recreate -e py27

将触发现有py27环境的完全重新安装(如果该环境不存在，则重新创建)。

向下传递环境变量

2.0 新版功能.

默认情况下，tox只会将 PATH 环境变量(和Windows上的 SYSTEMROOT 和 PATHEXT )从TOX调用到测试环境。如果要向下传递其他环境变量，可以使用 passenv 选项：

[testenv]
passenv = LANG

当您的测试命令执行时，它们将使用与调用tox时相同的lang设置执行。

设置环境变量

1.0 新版功能.

如果需要设置环境变量，如 PYTHONPATH 你可以使用 setenv 指令：

[testenv]
setenv = PYTHONPATH = {toxinidir}/subdir

当您的测试命令执行时，它们将使用PYTHONPATH设置执行，该设置将导致Python也从 subdir 位于您的 tox.ini 文件驻留。

PYTHONHASHED的特殊处理

1.6.2 新版功能.

默认情况下，tox 设置 PYTHONHASHSEED 生成的随机整数的测试命令 tox 被调用。这模拟了默认情况下启用的Python散列随机化 in Python 3.3 。为了帮助重现测试失败，tox显示 PYTHONHASHSEED 在测试输出中。

属性告诉tox使用显式的散列种子值。 --hashseed 命令行选项 tox 。中的每个测试环境覆盖散列种子值。 tox.ini 如下：

[testenv]
setenv = PYTHONHASHSEED = 100

如果要禁用此功能，可以传递命令行选项 --hashseed=noset 什么时候？ tox 被调用。您也可以从 tox.ini 通过设置 PYTHONHASHSEED = 0 如上所述。

与“setup.py test”命令集成

警告

setup.py test 是 deprecated 并将在将来的版本中删除。

忽略命令退出代码

在某些情况下，您可能希望忽略命令退出代码。例如：

[testenv:py27]
commands = coverage erase
       {envbindir}/python setup.py develop
       coverage run -p setup.py test
       coverage combine
       - coverage html
       {envbindir}/flake8 loads

通过使用 - 前缀，类似于 make 方法行，您可以忽略该命令的退出代码。

压缩依赖矩阵

如果您有大量依赖项、Python版本和/或环境，则可以使用 生成性环境列表 和 conditional settings 用简明扼要的形式来表达：

[tox]
envlist = py{36,37,38}-django{22,30}-{sqlite,mysql}

[testenv]
deps =
    django22: Django>=2.2,<2.3
    django30: Django>=3.0,<3.1
    # use PyMySQL if factors "py37" and "mysql" are present in env name
    py38-mysql: PyMySQL
    # use urllib3 if any of "py36" or "py37" are present in env name
    py36,py37: urllib3
    # mocking sqlite on 3.6 and 3.7 if factor "sqlite" is present
    py{36,37}-sqlite: mock

使用生成节名称

假设您有一些二进制包，并且需要同时运行32位和64位测试。您还需要一个环境来为开发人员创建虚拟环境。

[testenv]
basepython =
    py38-x86: python3.8-32
    py38-x64: python3.8-64
commands = pytest

[testenv:py38-{x86,x64}-venv]
usedevelop = true
envdir =
    x86: .venv-x86
    x64: .venv-x64
commands =

阻止虚拟环境中的符号链接

默认情况下，viralenv将使用符号链接指向系统的python文件、模块等。如果您希望复制这些文件(可能是因为您的文件系统无法处理符号链接)，您可以通过设置 alwayscopy 指令在您的环境中：

[testenv]
alwayscopy = True

并行模式

tox 允许并行运行环境：

• 通过使用 --parallel 或 -p 旗帜。打包阶段完成后，tox将在tox环境的并行进程中运行(旋转tox解释器的新实例，但会传递所有主机标志和环境变量)。

• -p 接受指定并行化程度的参数，默认为 auto ：

  • all 要并行运行所有调用的环境，

  • auto 要将其限制为CPU计数，

  • 或者传递一个整数来设置该限制。

• 并行模式在并行运行TOX环境时显示进度微调器，并在完成后立即报告结果，并附加人类可读的持续时间计时。可以通过设置环境变量来禁用此微调器 TOX_PARALLEL_NO_SPINNER 价值观 1 .

• 默认情况下，并行模式仅显示故障环境和标记为 parallel_show_output =True .

• 现在有了环境之间的依赖关系的概念(通过 depends )，TOX将对要运行的环境列表重新排序，以满足这些依赖关系(也按顺序运行)。此外，在并行模式下，将仅调度一个TOX环境在其所有依赖项完成后运行(与其结果无关)。

  警告

  depends 不会将依赖项拉入到运行目标中，例如，如果您选择 py27,py36,coverage 通过 -e tox检测只能检测这三个(即使 coverage 可指定为 depends 其他目标也是如此-例如 py27, py35, py36, py37 ）

• --parallel-live/-o 允许显示标准输出和错误的实时输出，还可以关闭上述报告。

• 注：并行评估禁用标准输入。如果需要标准输入，请使用非并行调用。

最终输出示例：

$ tox -e py27,py36,coverage -p all
✔ OK py36 in 9.533 seconds
✔ OK py27 in 9.96 seconds
✔ OK coverage in 2.0 seconds
___________________________ summary ______________________________________________________
  py27: commands succeeded
  py36: commands succeeded
  coverage: commands succeeded
  congratulations :)

进度条示例，显示旋转微调器、正在运行的环境数及其列表(最多限制为120个字符)：

⠹ [2] py27 | py36

TOX自动调配

如果宿主tox不能满足 minversion 或 requires ，tox现在将在以下位置自动创建虚拟环境 provision_tox_env 它满足这些约束，并将所有调用委托给此元环境。如果您至少有版本，这应该允许自动满足您的TOX环境的约束 3.8.0 tox。

例如，给定：

[tox]
minversion = 3.10.0
requires = tox_venv >= 1.0.0

如果用户在使用tox的情况下运行它 3.8.0 或更高版本安装的tox将自动确保同时满足最低版本和要求约束，方法是在以下位置创建虚拟环境 .tox 文件夹，然后安装到该文件夹中 tox >= 3.10.0 和 tox_venv >= 1.0.0 。之后，所有的tox调用都会被转发到安装在其中的tox .tox\.tox 文件夹(称为META-TOX或自动提供TOX)。

这允许tox使用当前项目的所有插件自动进行自我设置。如果宿主tox满足用 requires 和 minversion 不会执行这样的配置(以避免在不明确需要时的设置成本)。