基本用法

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中未包含的工具,例如 makebash 或者其他人。若要避免警告,可以使用 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 = -cconstraints.txt

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

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

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

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

使用不同的默认PyPI URL

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

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

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

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

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

或者,在以下情况下的配置 PIP_INDEX_URL 可以从环境中覆盖:

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

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

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

[tox]
setenv =
    PIP_EXTRA_INDEX_URL = https://mypypiserver.org

[testenv]
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 网址。

进一步自定义安装

1.6 新版功能.

默认情况下,tox使用 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上的 SYSTEMROOTPATHEXT )从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 testdeprecated 并将在将来的版本中删除。

忽略命令退出代码

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

[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 =

并行模式

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不能满足 minversionrequires ,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.0tox_venv >= 1.0.0 。之后,所有的tox调用都会被转发到安装在其中的tox .tox\.tox 文件夹(称为META-TOX或自动提供TOX)。

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