tox 配置规范¶

配置发现¶

目前，TOX支持按以下优先顺序排列的三个配置位置：

pyproject.toml,
tox.ini,
setup.cfg .

就配置格式而言，目前我们只支持标准 ConfigParser “ini-style”格式(计划很快添加一个纯TOML格式)。 tox.ini 和 setup.cfg 都是这样的文件。请注意， setup.cfg 要求内容位于 tox:tox 和 testenv 节，否则将被忽略。 pyproject.toml 另一方面是TOML格式。但是，您可以内联 ini-style 格式下的格式 tool.tox.legacy_tox_ini 键作为多行字符串。

在下面您可以找到 ini-style 格式，但您可能想略读一些 tox配置和使用示例首先，请将本页作为参考。

tox 全局设置¶

全局设置在 tox 部分内容为：

[tox]
minversion = 3.4.0

minversion¶

定义运行所需的最低TOX版本；如果主机的TOX版本低于此版本，则该工具将创建一个环境，并为其提供满足以下条件的TOX版本 provision_tox_env .

在 3.23.0 版更改.

方法调用tox时， --no-provision 标志，则不会尝试提供，取而代之的是毒理测试失败。

requires(PEP-508一览表)¶

3.2.0 新版功能.

指定需要与tox安装同时存在的python包，才能启动tox版本(必须 PEP-508 符合)。使用此选项指定插件要求(或的版本 virtualenv -确定默认值 pip ， setuptools 和 wheel TOX环境开始的版本)。如果未指定这些依赖项，则tox将创建 provision_tox_env 这样他们就会感到满意，并将所有调用委托给该环境。

[tox]
requires = tox-pipenv
           setuptools >= 30.0.0

在 3.23.0 版更改.

方法调用tox时， --no-provision 标志，则不会尝试提供，取而代之的是毒理测试失败。

provision_tox_env=.tox(字符串)¶

3.8.0 新版功能.

用于调配具有内部指定的所有依赖项的TOX的虚拟环境的名称 requires 和 minversion .

在 3.23.0 版更改.

方法调用tox时， --no-provision 标志，则不会尝试提供，取而代之的是毒理测试失败。

toxworkdir={toxinidir}/.tox(路径)¶: 如果不存在，将创建用于生成其环境的TOX目录。

temp_dir={toxworkdir}/.tmp(路径)¶: 3.5.0 新版功能.

放置TOX临时文件的目录。例如：我们在此目录中为项目包创建硬链接(如果可能，否则创建新副本)。这确保了TOX在并行运行时正常工作(因为每个会话都有自己的项目包副本-例如源代码分发)。

skipsdist=false(TRUE|FALSE)¶: 指示是否执行打包操作的标志。将其设置为 true 当为应用程序而不是库使用TOX时。

setupdir={toxinidir}(路径)¶: 指示打包根文件所在的位置(历史上 setup.py 对于 setuptools )。这将是执行打包时的工作目录。

distdir={toxworkdir}/dist(路径)¶: 打包的源代码分发版应放入的目录。注意，这是在每次打包调用开始时清除的。

sdistsrc={toxworkdir}/dist(路径)¶: 不要构建包，而是使用此路径下可用的最新包。您可以通过命令行标志覆盖它 --installpkg .

distshare={homedir}/.tox/distshare(路径)¶: 要将打包的源代码分发移到的文件夹，则不会在打包调用之间清除此文件夹。关于Jenkins(EXISTS JENKINS_URL 或 HUDSON_URL 环境变量)默认路径为 {{toxworkdir}}/distshare .

envlist(逗号分隔值)¶

确定符合以下条件的环境列表 tox 将按此顺序对发生的事件进行操作(如果找到任何事件，则不会进行进一步查找)：

命令行选项 -eENVLIST
环境变量 TOXENV
tox.ini file's envlist

3.4.0 新版功能: 可以通过操作系统环境变量进一步过滤在TOX调用期间运行的哪些TOX环境 TOX_SKIP_ENV 正则表达式(例如 py27.* 方法不要评估以关键字开头的环境 py27 )。跳过的环境将记录在第二级详细级别。

skip_missing_interpreters=config(配置 |true| 假)¶: 1.7.2 新版功能.

设置为 true 会强迫 tox 以返回成功，即使缺少某些指定的环境也是如此。这对于某些CI系统或在开发人员盒上运行时非常有用，在开发人员盒上，您可能只安装了所有受支持解释器的子集，但不想因此将构建标记为失败。不出所料，如果在调用时传递，命令行开关始终覆盖此设置。将其设置为 config 表示从配置文件中读取值。

ignore_basepython_conflict=false(TRUE|FALSE)¶

3.1.0 新版功能.

tox允许通过以下方式设置环境的python版本 basepython 设置。如果没有设置，TOX可以从环境名称设置默认值(例如 py37 暗示Python3.7)。在这一点上，将python版本与环境名称进行匹配已成为意料之中的事情，当某些配置不这样做时，这会导致意外。为了帮助用户保持理智，只要环境名称版本与预期不符，就会发出警告。在未来的TOX版本中，此警告将成为错误。

此外，通过将此标志设置为，我们允许硬实施此规则(并绕过警告 true 。在这种情况下，我们忽略 basepython 而是始终使用从Python名称隐含的基本Python。这允许您配置 basepython 而不会影响具有隐含的基本python版本的环境。

isolated_build=false(TRUE|FALSE)¶: 3.3.0 新版功能.

激活隔离生成环境。TOX将使用虚拟环境从源代码树构建源代码分发。对于生成工具和参数，请使用 pyproject.toml 中指定的文件 PEP-517 和 PEP-518 。要指定虚拟环境Python版本定义，请使用 isolated_build_env 配置节。

isolated_build_env=.package(字符串)¶: 3.3.0 新版功能.

用于从源树创建源分发的虚拟环境的名称。

Jenkins覆盖¶

可以重写 Jenkins 实例(检测是通过检查 JENKINS_URL 环境变量)通过使用 tox:jenkins 章节：

[tox:jenkins]
commands = ...  # override settings for the jenkins context

tox 环境¶

测试环境在 testenv 部门和个人 testenv:NAME 横断面，其中 NAME 是特定环境的名称。

[testenv]
commands = ...

[testenv:NAME]
commands = ...

在顶层定义的设置 testenv 节由各个环境自动继承，除非被覆盖。测试环境名称可以由字母数字字符和短划线组成，例如： py38-django30 。名称将在短划线上拆分成多个因子，意思是 py38-django30 将分为两个因素： py38 和 django30 . tox 定义了许多默认因子，这些因子对应于Python的各种版本和实现，并为 basepython ：

pyNM: configures basepython = pythonN.M
pyN: configures basepython = pythonN
py: configures basepython = python
pypyN: configures basepython = pypyN
pypy: configures basepython = pypy
jythonN: configures basepython = jythonN
jython: configures basepython = jython

It is also possible to define what's know as generative names, where an individual section maps to multiple environments. For example, py{37,38}-django{30,31} would generate four environments, each consisting of two factors: py37-django30 (py37, django30), py37-django31 (py37, django31), py38-django30 (py38, django30), and py38-django31 (py38, django31). Combined, these features provide the ability to write very concise tox.ini files. This is discussed further in below.

tox 环境设置¶

可以放入的完整设置列表 testenv* 章节：

basepython(名称或路径)¶: 将用于创建虚拟环境的Python解释器的名称或路径，这实际上决定了我们将创建虚拟隔离环境的Python。使用此选项可以指定tox环境的python版本。如果未指定，将使用虚拟环境因素(例如名称部分)自动设置一个。例如, py37 方法 python3.7 ， py3 方法 python3 和 py 方法 python . provision_tox_env 环境不会从 toxenv 部分。

在 3.1 版更改: 解析此值后，如果解释器报告的版本号与名称中隐含的版本号不同，则默认情况下将打印一条警告。但是，如果 ignore_basepython_conflict 则忽略该值，并且我们强制 basepython 从因子名称中隐含。

commands(ARGVLIST)¶

要调用进行测试的命令。仅在以下情况下执行 commands_pre 成功。

每行都解释为一个命令；但是，可以通过以行结尾来将命令拆分到多行 \ 性格。

命令将以顺序方式逐个执行，直到其中一个失败(其退出代码为非零)或所有命令都成功。可以忽略命令的退出代码(这意味着即使它们不存在，也始终被视为成功)，方法是在命令前面加上破折号 (- )-这类似于 make 食谱系列奏效了。只有当所有命令(这些+SETUP+TEARDOWN)都成功时，环境的结果才被认为是成功的(通过忽略退出代码 - 或成功退出码值为零)。

笔记: 虚拟环境二进制路径( bin 文件夹)被放在操作系统的前面 PATH ，这意味着命令将首先尝试从虚拟环境内部解析为可执行文件，并且只有在虚拟环境外部才会尝试解析为可执行文件。因此， python 翻译为虚拟环境 python (具有与 basepython ） pip 翻译为虚拟环境 pip .
笔记: 可以使用内联脚本，但是请注意，这些脚本是从项目根目录中发现的，不受 changedir (这仅影响运行时当前工作目录)。要使此行为显式，我们建议您通过前缀将内联脚本设置为绝对路径 {{toxinidir}} ，而不是 path/to/my_script 首选 {{toxinidir}}{{/}}path{{/}}to{{/}}my_script 。如果您的内联脚本依赖于平台，请参阅平台规格关于如何根据平台选择不同的脚本。

commands_pre(ARGVLIST)¶: 3.4 新版功能.

在运行之前要运行的命令 commands 。所有评估和配置逻辑均适用于 commands .

commands_post(ARGVLIST)¶: 3.4 新版功能.

运行后要运行的命令 commands 。执行，而不考虑两者的结果 commands 和 commands_pre 。所有评估和配置逻辑均适用于 commands .

install_command=python -m pip install {opts} {packages}(ARGV)¶: 1.6 新版功能.

确定用于将软件包安装到虚拟环境中的命令；测试中的软件包及其依赖项(使用定义 deps )。必须包含替换密钥 {{packages}} 它将被要安装的程序包替换。你也应该接受 {{opts}} 如果您使用的是pip--它将包含索引服务器选项，如 --pre (配置为 pip_pre )和潜在的索引选项(来自已弃用的 indexserver 选择权。

注解

您还可以将任意命令提供给 install_command 。请注意，这些命令可以在支持的操作系统上执行。在执行shell脚本时，我们建议不要直接指定脚本，而是将其作为参数传递给相应的shell(例如，首选 bash script.sh 完毕 script.sh )。

list_dependencies_command=python -m pip freeze(ARGV)¶: 2.4 新版功能.

这个 list_dependencies_command 设置用于列出安装到虚拟环境中的软件包。

ignore_errors=false(TRUE|FALSE)¶

2.0 新版功能.

如果 false ，则一个命令的非零退出代码将中止该环境的命令执行。如果 true ，则一个命令的非零退出代码将被忽略，并将执行其他命令。总体状态将是“命令失败”，也就是说，如果任何命令失败，TOX将退出非零状态。

请注意，此设置类似于 -k 或 --keep-going GNU make选项。

请注意，在TOX 2.0中，与处理来自命令的错误相关的TOX的默认行为发生了变化。默认情况下，TOX<2.0会忽略错误。默认情况下，tox>=2.0将在出现错误时中止，这在CI和命令执行工具中更安全、更典型，因为如果安装某些必备组件失败，则运行测试没有意义，如果测试失败，则尝试部署也没有意义。

pip_pre=false(TRUE|FALSE)¶

1.9 新版功能.

如果 true ，添加 --pre 到 opts 传递给 install_command .如果 install_command 使用pip，这将导致它安装没有指定版本的任何依赖项的最新可用预发布。如果 false ，pip将仅安装未固定依赖项的最终版本。

路过 --pre tox的命令行选项将强制执行此操作 true 对所有的提斯腾夫人来说。

如果您的 install_command 不使用pip。

allowlist_externals(多行列表)¶: 3.18 新版功能.

每一行都指定一个命令名(采用glob样式模式格式)，该命令名可在 commands 部分，而不触发“未安装在Virtualenv中”警告。示例：如果您使用Unix make 对于运行测试，您可以列出 allowlist_externals=make 或 allowlist_externals=/usr/bin/make 如果你想要更精确的话。如果您不想在任何情况下使用tox发出警告，只需使用 allowlist_externals=* 它将与所有命令匹配(不推荐)。

注解

whitelist_externals 与具有相同的含义和用法 allowlist_externals 但它现在已被弃用。

changedir={toxinidir}(路径)¶: 执行测试命令时更改当前工作目录。

注解

如果该目录尚不存在，则会创建该目录。

deps(多行列表)¶

环境依赖项-安装到环境中(请参见 install_command )在环境创建之后的项目之前。每行一个依赖项(文件、URL或包名)。一定是 PEP-508 顺从的。所有安装程序命令都使用 toxinidir 作为当前工作目录。

[testenv]
deps =
    pytest
    pytest-cov >= 3.5
    pywin32 >=1.0 ; sys_platform == 'win32'
    octomachinery==0.0.13  # pyup: < 0.1.0 # disable feature updates

在 2.3 版更改.

现在不建议使用索引服务器，也不鼓励使用索引服务器。

在 3.9 版更改.

在与依赖项相同的行上注释支持。将内容提供给安装工具时，我们将从第一个注释标记中剥离内容(包括 (# )前面有一个或多个空格。例如，如果依赖项是 octomachinery==0.0.13 # pyup: < 0.1.0 # disable feature updates 它将会变成公正的 octomachinery==0.0.13 .

platform(REGEX)¶: 2.0 新版功能.

Testenv可以定义一个新的 platform 设置为正则表达式。如果定义了非空表达式，并且该表达式与 sys.platform string将跳过整个测试环境，并且不会执行任何命令。正在运行 tox -e <platform_name> 将针对特定平台运行命令并跳过睡觉。

setenv(多行列表)¶

0.9 新版功能.

每行都包含一个name=value环境变量设置，它将用于所有测试命令调用以及将sdist包安装到虚拟环境中。

请注意，在更新PATH变量时，可以考虑使用变量替换当前值并处理路径分隔符。

[testenv]
setenv   =
    PYTHONPATH = {env:PYTHONPATH}{:}{toxinidir}

3.20 新版功能.

支持评论。以以下字符开头的行 # 被忽略。

支持环境文件。以 file| 包含要加载的环境文件的路径。环境文件中的规则与 setenv (相同的更换和注释支持)。

passenv(空格分隔-全局名称)¶

2.0 新版功能.

执行测试命令时应从tox调用环境复制到测试环境的通配符环境变量名列表。如果指定的环境变量在tox调用环境中不存在，它将被忽略。您可以使用 * 和 ? 将多个环境变量与一个名称匹配。环境变量名列表不区分大小写，所有大小写匹配的变量都将被传递。例如，传递 A 都会通过 A 和 a .

一些变量总是被传递以确保标准库函数或工具(如pip)的基本功能。在除Windows之外的所有平台上，这也不区分大小写：

在所有平台上通过： CURL_CA_BUNDLE ， PATH ， LANG ， LANGUAGE ， LD_LIBRARY_PATH ， PIP_INDEX_URL ， PIP_EXTRA_INDEX_URL ， REQUESTS_CA_BUNDLE ， SSL_CERT_FILE ， HTTP_PROXY ， HTTPS_PROXY ， NO_PROXY
窗户： SYSTEMDRIVE ， SYSTEMROOT ， PATHEXT ， TEMP ， TMP
NUMBER_OF_PROCESSORS, USERPROFILE, MSYSTEM, PROGRAMFILES, PROGRAMFILES(X86), PROGRAMDATA
其他(例如UNIX、MacOS)： TMPDIR

属性覆盖这些变量。 setenv 选择权。

如果定义了 TOX_TESTENV_PASSENV 环境变量(在tox调用环境中)可以定义其他空格分隔的变量名，这些变量名将传递给测试命令环境。

在 2.7 版更改: PYTHONPATH 如果显式定义，将传递给下一代。如果 PYTHONPATH 存在于主机环境中，但 not 声明于 passenv 将发出警告。

recreate=false(TRUE|FALSE)¶: 如果此选项为true，请始终重新创建虚拟环境。如果此选项为FALSE， tox 的解决机制将用于确定是否重新创建环境。

downloadcache(路径)¶: IGNORED --由于pip-8在默认情况下具有缓存，因此现在忽略此选项。请将其从您的配置中删除，因为将来的 tox 版本可能会在其上发出声音。

sitepackages=false(TRUE|FALSE)¶

设置为 true 如果您想要创建也可以访问全局安装的软件包的虚拟环境。

警告

如果命令行工具也是全局安装的，则必须确保使用安装在viralenv中的工具，方法是使用 python -m <command line tool> (如果该工具支持)或 {{envbindir}}/<command line tool> .

如果您忘记这样做，您将收到如下警告：：

WARNING: test command found but not installed in testenv
    cmd: /path/to/parent/interpreter/bin/<some command>
    env: /foo/bar/.tox/python
Maybe you forgot to specify a dependency? See also the allowlist_externals envconfig setting.

alwayscopy=false(TRUE|FALSE)¶

设置为 true 如果您希望viralenv始终复制文件而不是符号链接。

这在硬链接不起作用的情况下很有用(例如，使用Windows来宾在VMS中运行)。

download=false(TRUE|FALSE)¶: 3.10 新版功能.

设置为 true 如果您希望viralenv将pip/round/setuptools升级到最新版本。如果(且仅当)您想要选择特定版本(不一定是最新版本)，则可以添加例如 VIRTUALENV_PIP=20.3.3 敬你的setenv。

args_are_paths=true(TRUE|FALSE)¶: 处理传递给的位置参数 tox 作为文件系统路径，并且-如果它们存在于文件系统上-根据 changedir 。由于文件系统上存在检查，默认值为true，尝试重写通常是安全的。

envtmpdir={envdir}/tmp(路径)¶: 为viralenv定义一个临时目录，该目录将在每次调用测试命令组之前清除。

envlogdir={envdir}/log(路径)¶: 定义用于记录的目录，tox将在该目录中放置工具调用的日志。

indexserver(URL)¶

0.9 新版功能.

(已弃用，将在未来版本中删除)使用 setenv 要配置PIP_INDEX_URL环境变量，请参见下面的内容。

多行 name = URL Python包服务器的定义。属性，可以为依赖项指定替代索引服务器。 :indexservername:depname 图案。这个 default indexserver定义确定未限定作用域的依赖项和sdist安装的安装位置。示例：

[tox]
indexserver =
    default = https://mypypi.org

将使tox从此PyPI索引服务器安装所有依赖项(包括安装项目sdist包时)。

建议使用以下方式设置自定义索引服务器URL setenv ：

[testenv]
setenv =
    PIP_INDEX_URL = {env:PIP_INDEX_URL:https://pypi.org/simple/}

这将确保所需的索引服务器用于虚拟环境创建，并允许使用环境变量覆盖索引服务器URL。

envdir={toxworkdir}/{envname}(路径)¶: 1.5 新版功能.

用户可以设置环境的具体路径。如果路径不是绝对路径，它将被视为相对于 {{toxinidir}} .

usedevelop=false(TRUE|FALSE)¶: 1.6 新版功能.

在开发模式下使用“setup.py Development”安装当前包，而不是从 sdist 包裹。(这使用pip的 -e 选项，因此如果您指定了自定义 install_command 这不支持 -e )。请注意，只有在将setupTools与setup.py一起使用时，才会检测到构建/安装过程的更改(包括依赖项的更改)。

skip_install=false(TRUE|FALSE)¶: 1.9 新版功能.

请勿安装当前软件包。当您需要Virtualenv管理，但不想将当前软件包安装到该环境中时，可以使用此功能。

ignore_outcome=false(TRUE|FALSE)¶: 2.2 新版功能.

如果设置为TRUE，则此测试的失败结果不会导致 tox 测试失败，只会产生警告。

extras(多行列表)¶: 2.4 新版功能.

要随sdist或developer安装一起安装的“附加”列表。例如, extras = testing 等于 [testing] 在一个 pip install 指挥部。如果出现以下情况，则不会安装这些组件 skip_install 是 true .

description=no description(单行文本)¶: 环境的简短描述，这将用于在列出任何详细级别高于零的命令行的环境时向用户解释环境。

parallel_show_output=false（布尔）¶: 3.7.0 新版功能.

如果设置为True，则在并行模式下运行时将始终显示输出内容。

depends(逗号分隔值)¶: 3.7.0 新版功能.

这取决于tox环境。在运行此环境之前，TOX将尝试运行所有相关环境。格式与 envlist (允许使用因子)。

警告

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

suicide_timeout=0.0（浮动）¶: 3.15.2 新版功能.

当通过Ctrl+C发送中断或使用SIGTERM终止tox进程时，会向所有前台进程发送SIGINT。这个 suicide_timeout 在从TOX接收(在某些情况下是重复的)SIGINT之前，为正在运行的进程提供清理和退出的时间。

interrupt_timeout=0.3（浮动）¶: 3.15.0 新版功能.

当tox被中断时，它将信号传播到子进程 suicide_timeout 几秒钟。如果进程在以下情况下仍未退出 interrupt_timeout 几秒钟后，它就会发送SIGTERM信号。

terminate_timeout=0.2（浮动）¶: 3.15.0 新版功能.

当毒理中断时，在等待之后 interrupt_timeout 秒后，它将信号传播到子进程，等待 interrupt_timeout 秒，向它发送SIGTERM，等待 terminate_timeout 秒，如果它还没有退出，则向它发送SIGKILL。

替代品¶

任何 key=value 在ini文件中的设置可以通过 {{...}} 字符串替换模式。

属性可以省略大括号。 \ 字符(如果需要)，例如：：

commands = echo "\{posargs\}" = {posargs}

请注意一些替换(例如 posargs, env) may have addition values attached to it, via the : character (e.g. `` Poargs``-默认值， env - key). Such substitutions cannot have a space after the : character (e.g. `` {posargs：Magic}``位于ini配置内的行首(这将被解析为阶乘 {{posargs ，具有价值魔力)。

全球可用的替代¶

{toxinidir}: 所在的目录 tox.ini 位于

{toxworkdir}: 创建虚拟环境的目录和用于打包的子目录所在的目录。
{temp_dir}: TOX临时文件所在的目录。

3.16.1 新版功能.
{homedir}: 用户主目录路径。
{distdir}: 将在其中创建sdist软件包的目录
{distshare}: (已弃用)sdist软件包将复制到的目录，以便其他进程或tox运行可以访问它们。
{:}: 特定于操作系统的路径分隔符 (: 在尼克斯家族上， ; 在Windows上)。可用于 setenv ，当目标变量为PATH变量时(例如PATH或PYTHONPATH)。
{/}: 操作系统特定的目录分隔符 (/ 在尼克斯家族上， \\ 在Windows上)。用于从预设路径派生文件名，作为需要 \\ 在Windows上。例如： {{distdir}}{{/}}file.txt 。当使用用Python编写的命令时，通常不需要它。

环境变量替换¶

如果您指定如下替换字符串：：

{env:KEY}

则该值将被检索为 os.environ['KEY'] 如果环境变量不存在，则引发错误。

使用默认值替换环境变量¶

如果您指定如下替换字符串：：

{env:KEY:DEFAULTVALUE}

则该值将被检索为 os.environ['KEY'] 如果环境变量不存在，则替换为DEFAULTVALUE。

如果您指定如下替换字符串：：

{env:KEY:}

则该值将被检索为 os.environ['KEY'] 如果环境变量不存在，则替换为空字符串。

替换也可以嵌套。在这种情况下，它们从最里面的表达式开始展开：：

{env:KEY:{env:DEFAULT_OF_KEY}}

上面的示例大致相当于 os.environ.get('KEY', os.environ['DEFAULT_OF_KEY'])

交互式外壳替换¶

3.4.0 新版功能.

只有当tox在交互式shell(标准输入)中运行时，才可以注入配置值：：

{tty:ON_VALUE:OFF_VALUE}

第一个值是当交互式终端可用时要注入的值，第二个值是当交互式终端不可用时要使用的值。后者是可选的。这样做的一个很好的用例是，例如，将 --pdb 最热的旗帜。

命令中位置参数的替换¶

1.0 新版功能.

如果您指定如下替换字符串：：

{posargs:DEFAULTS}

然后，该值将被提供给tox命令的位置参数替换：

tox arg1 arg2

在本例中，位置参数部分将替换为 arg1 arg2 。如果未指定位置参数，则将使用默认值的值。如果DEFAULTS包含其他替换字符串，如 {{env:*}} ，它们将被解释。，

使用替身 -- 如果您还想将选项传递给基础测试命令，例如：：

tox -- --opt1 ARG1

将使 --opt1 ARG1 出现在所有测试命令中，其中 [] 或 {{posargs}} 已指定。缺省情况下(请参见 args_are_paths 设置)， tox 如果每个位置参数是相对路径并且存在于文件系统上，则将其重写为相对于 changedir 设置。

以前版本的tox支持 [.*] 使用默认值表示位置参数的模式。此格式已弃用。使用 {{posargs:DEFAULTS}} 来指定那些。

替换其他节中的值¶

1.4 新版功能.

其他部分的值可以通过以下方式引用：

{[sectionname]valuename}

您可以使用它来避免重复的配置值。您可以将默认值放在一个节中，然后在其他节中引用它们，以避免重复相同的值：

[base]
deps =
    pytest
    mock
    pytest-xdist

[testenv:dulwich]
deps =
    dulwich
    {[base]deps}

[testenv:mercurial]
deps =
    mercurial
    {[base]deps}

生成环境，条件设置¶

1.8 新版功能.

假设您想要针对python2.7、python3.6以及依赖项的几个版本(比如Django 1.5和Django 1.6)测试包。你可以写下2个字就可以做到这一点。 2 = 4 ``[testenv: ]``节，然后在 envlist .

但是，更好的方法如下所示：

[tox]
envlist = {py27,py36}-django{15,16}

[testenv]
deps =
    pytest
    django15: Django>=1.5,<1.6
    django16: Django>=1.6,<1.7
    py36: unittest2
commands = pytest

这使用了两个新的TOX-1.8设备：

生成性环境列表声明，其中每个环境名称由环境部分或“因素”组成
“因素”特定设置

让我们一步一步地来看这个。

生成性环境列表¶

envlist = {py36,py27}-django{15,16}

这是bash样式的语法，将创建 2*2=4 类似于以下内容的环境名称：：

py27-django15
py27-django16
py36-django15
py36-django16

您仍然可以将环境与生成的环境一起显式列出：

envlist = {py27,py36}-django{15,16}, docs, flake

请记住，内空格字符(换行符除外) {{}} 被剥离，因此以下行定义了相同的环境名称：

envlist = {py27,py36}-django{ 15, 16 }, docs, flake

注解

为了帮助理解变量将如何生成分段值，您可以要求tox使用一个新选项显示它们的扩展：：

$ tox -l
py27-django15
py27-django16
py36-django15
py36-django16
docs
flake

生成节名¶

3.15 新版功能.

使用类似的语法，可以生成节：：

[testenv:py{27,36}-flake]

这等效于定义不同的部分：

$ tox -a
py27-flake
py36-flake

当您需要与默认环境不同的环境，但仍希望利用因子条件设置时，它非常有用。

因素和因素条件设置¶

如前所述，由连字符分隔的环境名称部分称为因子，可用于有条件地设置值。在列表设置中，如 deps 或 commands 您可以自由混合可选行和无条件行：

[testenv]
deps =
    pytest
    django15: Django>=1.5,<1.6
    django16: Django>=1.6,<1.7
    py36: unittest2

逐行阅读：

pytest 将无条件地包括在内，
Django>=1.5,<1.6 将包括在包含以下内容的环境中 django15 因素，
Django>=1.6,<1.7 同样依赖于 django16 因素，
unittest2 将为Python 3.6环境加载。

TOX提供了许多与Python解释器版本相对应的默认因子。上面的条件设置将导致 python3.6 或 python2.7 用作基本 Python ，例如 python3.6 如果当前环境包含 py36 因素。

注解

配置 basepython 对于使用默认因子的环境，将导致警告。配置 ignore_basepython_conflict 如果您希望显式忽略这些冲突，则允许您定义全局 basepython 适用于所有环境除了那些有违约因素的人。

复杂因素条件¶

有时，您需要为几个因素指定同一行，或者为多个因素的组合创建特殊情况。下面是你是如何做到这一点的：

[tox]
envlist = py{27,34,36}-django{15,16}-{sqlite,mysql}

[testenv]
deps =
    py34-mysql: PyMySQL     # use if both py34 and mysql are in the env name
    py27,py36: urllib3      # use if either py36 or py27 are in the env name
    py{27,36}-sqlite: mock  # mocking sqlite in python 2.x & 3.6
    !py34-sqlite: mock      # mocking sqlite, except in python 3.4
    sqlite-!py34: mock      # (same as the line above)
    !py34-!py36: enum34     # use if neither py34 nor py36 are in the env name

先看一下第一个 deps 排队。它展示了如何通过将组合因子连接在一起，来为组合因子特例。此特定行声明 PyMySQL 将为Python 3.4、MySQL环境加载，例如 py34-django15-mysql 和 py34-django16-mysql .

第二行显示了如何对几个因素使用相同的设置-通过用逗号分隔列出它们。不仅可以列出简单的因素，还可以列出它们的组合，如 py27-sqlite,py36-sqlite .

其余的行都具有相同的效果，并且使用条件相当于 py27-sqlite,py36-sqlite 。添加它们只是为了帮助演示以下内容：

因子表达式如何以与envlist中相同的方式展开
如何通过在否定因子前面加上前缀来使用否定因子条件 !
将各因子连在一起的顺序无关紧要

注解

因子不会根据环境名称进行子字符串匹配，而是每个带连字符的表达式都被拆分为 - 如果它的所有非否定因素，并且没有一个它的否定因素也是环境的因素，则该条件被认为对该环境成立。

例如，环境 py36-mysql-!dev ：

将由表达式匹配 py36 ， py36-mysql 或 mysql-py36 ，
但不是 py2 ， py36-sql 或 py36-mysql-dev .

因子和值替换是兼容的¶

可以将值替换和因子表达式混合使用。例如：：

[tox]
envlist = py27,py36,coverage

[testenv]
deps =
    flake8
    coverage: coverage

[testenv:py27]
deps =
    {[testenv]deps}
    pytest

使用以前的配置，它将安装：

flake8 和 pytest 用于以下项目的包 py27 环境。
flake8 用于以下项目的包 py36 环境。
flake8 和 coverage 用于以下项目的包 coverage 环境。

高级设置¶

处理长度较长的解释器指令¶

对于支持可执行文本文件(带有分隔符的脚本)的系统，系统将尝试解析解释器指令，以确定要在目标文本文件上执行的程序。什么时候 tox 在长度较大的文件容器中准备虚拟环境(例如，使用Jenkins Pipeline)，则系统可能无法调用定义超出系统限制的解释器的Shebang脚本(例如，Linux的限制为128； BINPRM_BUF_SIZE )。若要解决受解释器指令限制的环境，用户可以通过定义 TOX_LIMITED_SHEBANG 调用前的环境变量 tox ：：

export TOX_LIMITED_SHEBANG=1

启用解决方法后，所有由tox调用的文本文件可执行文件都将由其解释器指令解析并显式执行 tox .

环境变量¶

TOX将处理以下环境变量：

TOX_DISCOVER 对于python发现，首先尝试以下路径下的python可执行文件
TOXENV 看见 envlist 。
TOX_LIMITED_SHEBANG 看见处理长度较长的解释器指令。
TOX_PARALLEL_NO_SPINNER 看见并行模式。
_TOX_PARALLEL_ENV 让tox知道它是在并行模式下调用的。
TOX_PROVISION 仅供内部使用。
TOX_REPORTER_TIMESTAMP 当设置为时，启用显示每条输出线自毒素启动以来的增量 1 。
TOX_SKIP_ENV 看见 envlist 。
TOX_TESTENV_PASSENV 看见 passenv 。

注入的环境变量¶

TOX将注入以下环境变量，您可以使用这些变量来测试您的命令是否在TOX内运行：

3.4 新版功能.

TOX_WORK_DIR env var设置为tox工作目录
TOX_ENV_NAME 设置为当前运行的tox环境名称。
TOX_ENV_DIR 设置为当前的 tox 环境工作目录。
TOX_PACKAGE 打包阶段结果路径(对于检查和断言构建的包本身很有用)。
TOX_PARALLEL_ENV 设置为当前运行的TOX环境名称，仅当在并行模式下运行时。

笔记: 这适用于所有tox env(也是隔离打包)和所有调用的外部命令(例如install命令-pip)。

其他规则及备注¶

path 规格：如果指定了 path 是相对路径，它将被视为相对于 toxinidir ，配置文件所在的目录。

CLI¶

tox¶

tox 选项

usage: tox [--version] [-h] [--help-ini] [-v] [-q] [--showconfig] [-l] [-a] [-c CONFIGFILE] [-e envlist] [--devenv ENVDIR] [--notest] [--sdistonly] [--skip-pkg-install] [-p [VAL]] [-o]
           [--parallel--safe-build] [--installpkg PATH] [--develop] [-i URL] [--pre] [-r] [--result-json PATH] [--discover PATH [PATH ...]] [--hashseed SEED] [--force-dep REQ]
           [--sitepackages] [--alwayscopy] [--no-provision [REQUIRES_JSON]] [-s [val]] [--workdir PATH]
           [args [args ...]]

args¶: 可用于命令位置替换的其他参数

--version¶: 向标准输出报告版本信息。

-h, --help¶: 显示有关选项的帮助

--help-ini, --hi¶: 显示有关ini-name的帮助

-v, --verbose¶: 增加报告输出的详细程度。-vv模式关闭软件包安装的输出重定向，高于级别2的详细程度标志将传递给pip(少了两个级别)。

-q, --quiet¶: 逐渐静默报告输出。

--showconfig¶: 显示实时配置(默认情况下为所有环境，仅有-l默认目标，具体通过TOXENV/-e)

-l, --listenvs¶: 显示测试环境列表(如果详细，请提供说明)

-a, --listenvs-all¶: 显示所有已定义环境的列表(如果详细，请提供说明)

-c <configfile>¶: 包含‘tox.ini’文件的配置文件名或目录。

-e <envlist>¶: 针对指定环境工作(全部选择全部)。

--devenv <envdir>¶: 根据由指定的环境的TOX配置在ENVDIR中设置开发环境 -e (-e默认为py)。

--notest¶: 跳过调用测试命令。

--sdistonly¶: 仅执行sdist打包活动。

--skip-pkg-install¶: 跳过此运行的包安装

-p <val>, --parallel <val>¶: 并行运行tox环境，参数控制限制：ALL、AUTO或MISSING参数-CPU计数，某个正数，0关闭

-o, --parallel-live¶: 在运行环境时连接到标准输出

--parallel--safe-build¶: (已弃用)确保两个tox版本可以并行运行(使用tox工作目录中扩展名为.lock的锁定文件)

--installpkg <path>¶: 使用指定的软件包安装到venv中，而不是创建sdist。

--develop¶: 通过‘pip-e’使用‘setup.py developer’在venv中安装软件包。

-i <url>, --index-url <url>¶: 设置indexserver url(如果URL的格式为name=url，请专门设置‘name’indexserver的url)

--pre¶: 安装依赖项的预发布和开发版本。这将把--pre选项传递给install_command(默认情况下是pip)。

-r, --recreate¶: 强制重新创建虚拟环境

--result-json <path>¶: 编写一个json文件，其中包含有关所有命令和结果的详细信息。

--discover <path>¶: 对于python发现，首先尝试以下路径下的python可执行文件

--hashseed <seed>¶: 在运行命令之前，将PYTHONHASHSEED设置为种子。默认为范围内的随机整数 [1,4294967295] （ [11024] 在Windows上)。传递“noset”会抑制此行为。

--force-dep <req>¶: 在配置虚拟环境时强制其中一个依赖项的特定版本。请求示例‘pytest<2.7’或‘Django>=1.6’。

--sitepackages¶: 在所有环境中将Sitepackages设置覆盖为True

--alwayscopy¶: 在所有环境中将始终检查设置覆盖为True

--no-provision <requires_json>¶: 不执行调配，但会失败，如果提供了路径，则将调配元数据作为JSON写入到该路径

-s, --skip-missing-interpreters¶: 不要通过缺少解释器的测试：{config，true，false}选项

--workdir <path>¶: tox 工作目录

home	examples
install	changelog
config	issues[gh]
support	plugins/hooks

tox 配置规范¶

配置发现¶

tox 全局设置¶

Jenkins覆盖¶

tox 环境¶

tox 环境设置¶

替代品¶

全球可用的替代¶

环境变量替换¶

使用默认值替换环境变量¶

交互式外壳替换¶

命令中位置参数的替换¶

替换其他节中的值¶

生成环境，条件设置¶

生成性环境列表¶

生成节名¶

因素和因素条件设置¶

复杂因素条件¶

因子和值替换是兼容的¶

高级设置¶

处理长度较长的解释器指令¶

环境变量¶

注入的环境变量¶

其他规则及备注¶

CLI¶

tox¶

quicklinks

Table of Contents

Related Topics

tox 配置规范¶

配置发现¶

tox 全局设置¶

Jenkins覆盖¶

tox 环境¶

tox 环境设置¶

替代品¶

全球可用的替代¶

对Virtualenv相关部分的替换¶

环境变量替换¶

使用默认值替换环境变量¶

交互式外壳替换¶

命令中位置参数的替换¶

替换其他节中的值¶

生成环境，条件设置¶

生成性环境列表¶

生成节名¶

因素和因素条件设置¶

复杂因素条件¶

因子和值替换是兼容的¶

高级设置¶

处理长度较长的解释器指令¶

环境变量¶

注入的环境变量¶

其他规则及备注¶

CLI¶

tox¶