1. 项目概述为什么我们需要一个“测试神器”如果你写过一段时间的Python代码尤其是需要兼容多个Python版本比如2.7和3.x并存的老项目或者需要确保代码在3.7到3.11上都能跑或者你的项目依赖了不同版本的第三方库比如Django 2.2和Django 4.2那你一定对搭建测试环境的繁琐深有体会。手动创建虚拟环境、挨个安装依赖、切换解释器、运行测试命令……这套流程重复几次不仅效率低下还极易出错。更头疼的是团队协作时如何保证每个人本地跑测试的环境都是一致的tox就是为了解决这些痛点而生的。简单来说tox是一个命令行工具它允许你定义一份配置文件tox.ini在里面写明你想在哪些Python环境下比如py37py310pypy3运行哪些命令比如安装依赖、运行pytest、检查代码风格。你只需要执行一条tox命令它就会自动为你创建这些虚拟环境按顺序执行所有定义好的任务并给出清晰的报告。它把“跨环境测试”这个复杂任务变成了一个可重复、自动化、标准化的流程。我最初接触tox是在一个开源项目里当时被它“一键搞定所有测试环境”的能力震撼了从此就成了我项目中的标配工具。2. tox核心概念与工作流拆解要玩转tox得先理解它的几个核心概念这能帮你更好地规划你的测试矩阵。2.1 核心四要素envlist deps commands skipsdisttox的核心逻辑围绕着tox.ini配置文件展开其中几个关键部分决定了它的行为。1. 环境列表 (envlist):这是你测试矩阵的“总纲”。它定义了你要创建和运行哪些测试环境。环境名有约定俗成的规则比如py37代表使用Python 3.7解释器py310代表Python 3.10。你也可以定义组合环境比如py{37310}-django{2232}tox会自动展开成py37-django22py37-django32py310-django22py310-django32四个独立环境。envlist是你控制测试范围和粒度的主要手段。2. 依赖项 (deps):指定在这个测试环境中需要安装哪些额外的Python包。这通常包括你的项目依赖通过-r requirements.txt或-r pyproject.toml指定以及测试框架本身如pytestpytest-cov。deps的安装发生在虚拟环境创建之后项目包安装之前。3. 命令序列 (commands):这是每个测试环境最终要执行的任务列表。最常见的命令就是运行测试例如pytest tests/。但你也可以在这里运行代码风格检查flake8 .、类型检查mypy .、安全扫描bandit -r .等等。commands是按顺序执行的任何一个命令返回非零退出码该环境的测试就会被标记为失败。4. 跳过构建 (skipsdist):这是一个优化选项。默认情况下tox会先为你的项目构建一个源码分发包sdist然后在每个测试环境中安装这个分发包。这对于测试打包过程本身很有用。但如果你只想快速运行测试不关心打包设置skipsdist true可以跳过构建步骤直接在当前源码目录下安装依赖并运行命令速度会快很多。2.2 tox的工作流从命令到报告当你运行tox时背后发生了一系列自动化操作解析配置tox读取项目根目录下的tox.ini或pyproject.toml中的[tool.tox]部分理解你要测试哪些环境envlist。环境创建对于envlist中的每一个环境例如py310tox会在指定的位置默认是.tox/目录下创建一个独立的虚拟环境命名为.tox/py310。依赖安装在创建好的虚拟环境中tox会安装你在deps中列出的所有包。项目安装接着tox会将你的项目本身安装到这个虚拟环境中。默认模式是构建sdist再安装如果设置了skipsdist则会以“可编辑模式”pip install -e .直接安装当前代码。执行命令最后tox在对应的虚拟环境中依次执行commands中定义的命令。生成报告所有环境运行完毕后tox会在终端输出一份清晰的摘要报告列出每个环境的运行状态成功/失败和耗时。详细的日志则保存在每个环境对应的.tox/log子目录下。这个流程确保了每个测试环境都是全新的、隔离的并且完全由配置文件定义实现了测试的高度可重复性。3. 从零开始编写你的第一个tox.ini理论说再多不如动手实践。让我们从一个最简单的项目开始一步步搭建tox配置。假设我们有一个名为mycalculator的小项目结构如下mycalculator/ ├── src/ │ └── mycalculator/ │ ├── __init__.py │ └── calculator.py ├── tests/ │ ├── __init__.py │ └── test_calculator.py ├── requirements.txt └── pyproject.toml (或 setup.py)3.1 基础配置搭建首先在项目根目录创建tox.ini文件[tox] envlist py39 py310 py311 skipsdist true [testenv] deps pytest pytest-cov commands pytest tests/ -v --covsrc/mycalculator --cov-reportterm-missing逐行解析[tox]: 这是tox的全局配置节。envlist py39 py310 py311: 定义我们要在Python 3.9 3.10 3.11三个版本上运行测试。确保你的系统已经安装了这些版本的Python解释器。skipsdist true: 为了快速测试跳过源码包构建。[testenv]: 这是所有测试环境的通用配置节。下面定义的deps和commands会应用到envlist中的每一个环境。deps pytest pytest-cov: 每个测试环境都需要安装pytest和覆盖率插件。commands pytest tests/ ...: 在每个环境中运行的命令。这里我们运行pytest启用详细模式(-v)计算src/mycalculator目录的代码覆盖率(--cov)并在终端输出缺失覆盖率的报告(--cov-reportterm-missing)。现在在终端进入项目目录直接运行tox。你会看到tox开始依次创建三个虚拟环境.tox/py39.tox/py310.tox/py311安装依赖运行测试并最终输出汇总报告。3.2 进阶配置多环境与条件依赖真实项目往往更复杂。比如你的项目支持两个主要的第三方库版本并且需要在多个Python版本上测试兼容性。这时就需要用到因子Factors和环境特定配置。[tox] envlist py{39310311}-django{3242} py{310311}-fastapi lint [testenv] deps django{3242}: Django3.23.3 django{3242}: django{3242} fastapi: fastapi0.95.0 fastapi: uvicorn[standard] commands django{3242}: python manage.py test fastapi: pytest tests/ -v lint: flake8 src/ lint: mypy src/ [testenv:lint] deps flake8 mypy types-requests # 为mypy提供requests库的类型存根 skipsdist true配置解读复杂的envlist:py{39310311}-django{3242}: 会展开成6个环境py39-django32py39-django42py310-django32py310-django42py311-django32py311-django42。这构成了一个完整的Django版本兼容性测试矩阵。py{310311}-fastapi: 展开成2个环境测试在Python 3.10和3.11上对FastAPI的支持。lint: 一个独立的代码检查环境。条件依赖与命令:语法如django{3242}: Django3.23.3。这是一个条件依赖意思是只有当环境名中包含django32或django42这个因子时才安装Django3.23.3这个包。注意这里用了两个条件行来精确控制版本第一行是一个范围限制第二行django{3242}: django{3242}则会根据环境名具体安装django32或django42包假设这些版本包存在于你的索引中。更常见的做法是直接指定具体版本如django32: Django3.2.*。命令也支持条件语法。django{3242}: python manage.py test只会在Django环境中运行Django的测试命令而fastapi: pytest tests/ -v只在FastAPI环境中运行pytest。独立的环境配置节:[testenv:lint]专门为名为lint的环境定义配置。它会覆盖或合并[testenv]中的通用设置。这里我们为代码检查单独指定了依赖flake8 mypy和命令并且设置了skipsdist true因为lint检查不需要安装项目本身。实操心得依赖管理的技巧在deps中管理复杂依赖时一个常见的坑是条件判断的优先级和冲突。tox的解析顺序是从上到下。如果有多个条件匹配同一个环境所有匹配的依赖行都会被安装。为了避免版本冲突对于互斥的选项比如Django 3.2和4.2最好使用精确版本号并通过环境因子来区分而不是使用范围。另外将基础、共通的依赖如pytest放在无条件的行里将特定环境的依赖放在条件行里可以使配置更清晰。4. 深度实战集成现代Python开发工作流tox的强大之处在于它能无缝融入CI/CD流水线并与其他开发工具协同工作。下面我们看几个实战场景。4.1 与poetry/pdm的协同现代Python项目越来越多地使用pyproject.toml和Poetry或PDM来管理依赖和构建。tox可以很好地与它们配合。场景一使用Poetry锁定依赖如果你用Poetry你希望tox环境使用poetry.lock文件来确保依赖版本完全一致。[tox] envlist py310 py311 isolated_build true # 重要让tox使用pyproject.toml的构建后端 [testenv] usedevelop false # 关键使用 poetry export 来生成 requirements.txt deps poetry commands_pre # 在安装项目前先使用poetry导出依赖并安装 poetry export --without-hashes -f requirements.txt -o requirements.txt pip install -r requirements.txt commands pip install -e . # 然后以可编辑模式安装当前项目 pytest这里commands_pre是一个特殊的钩子它在deps安装之后commands执行之前运行。我们利用它调用poetry export生成一个确定性的requirements.txt然后用pip安装。这比让tox直接解析pyproject.toml更可靠尤其是当你的项目包含私有仓库或特殊索引时。场景二直接使用PDMPDM本身提供了pdm run命令来在执行命令时自动管理虚拟环境。但为了在CI中统一使用tox可以这样配置[tox] envlist py310 py311 [testenv] setenv PDM_IGNORE_SAVED_PYTHON 1 # 让PDM忽略保存的Python路径使用tox创建的env deps pdm commands # 使用PDM安装当前项目及其所有依赖包括开发依赖 pdm install --no-self pdm run pytestsetenv用于设置环境变量。这里我们告诉PDM使用当前激活的Python环境即tox创建的虚拟环境。pdm install --no-self会安装pyproject.toml中定义的所有依赖但跳过项目包本身因为我们要用当前源码。最后用pdm run来执行pytest。4.2 在GitHub Actions中运行tox将tox集成到GitHub Actions中可以实现每次推送代码或发起拉取请求时自动进行全矩阵测试。# .github/workflows/test.yml name: Test with tox on: [push pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: # 这里与tox的envlist保持同步或者让tox自己决定 python-version: [3.9 3.10 3.11] steps: - uses: actions/checkoutv3 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-pythonv4 with: python-version: ${{ matrix.python-version }} - name: Install tox run: pip install tox - name: Run tox for Python ${{ matrix.python-version }} run: tox -e py$(echo ${{ matrix.python-version }} | tr -d .) # 例如当python-version为3.10时运行 tox -e py310这个工作流为每个Python版本启动一个独立的Job并行运行测试可以大大缩短整体反馈时间。注意这里我们用了策略矩阵来定义Python版本并在run步骤中动态构造tox的环境名py310。你也可以简化成直接运行tox让tox根据tox.ini中的envlist自行管理所有环境但并行度就由tox控制了。注意事项CI环境下的缓存优化在CI中运行tox每次都要从头创建虚拟环境和安装依赖非常耗时。可以利用GitHub Actions的缓存机制来加速。常见的做法是缓存~/.cache/pip目录和tox的虚拟环境目录.tox/。但缓存.tox/需要小心因为不同Python版本、不同操作系统下的环境可能不兼容。一个更安全的策略是只缓存pip的下载包并利用tox的--recreate标志在依赖发生变更时强制重建环境。许多CI平台也提供了预置了多种Python版本和系统依赖的Docker镜像使用这些镜像作为基础能进一步减少环境准备时间。5. 高级技巧与疑难排坑实录即使熟悉了基础配置在实际使用中你还是会遇到一些“坑”。下面是我总结的几个常见问题和进阶技巧。5.1 环境变量与配置传递测试有时需要依赖环境变量比如数据库连接字符串、API密钥当然测试用的应该是假密钥。tox提供了几种方式在tox.ini中设置[testenv] setenv DATABASE_URL sqlite://:memory: API_KEY test-key-123这些变量会在该环境执行命令时生效。通过命令行传递tox -- MY_VARvalue在--之后传递的参数会被设置为环境变量。在commands中你可以通过{env:MY_VAR}来引用它。使用passenv继承主机环境变量[testenv] passenv CI TRAVIS JENKINS_URL # 传递这些特定的主机环境变量这在CI环境中非常有用可以让测试感知到是在CI中运行。5.2 处理平台特异性依赖有些依赖只在特定操作系统上存在或者需要不同的安装方式。tox支持基于平台的条件判断。[testenv] deps # 所有平台都需要的通用依赖 pytest # Windows平台特定依赖 platform_system Windows: pywin32 # Linux平台特定依赖例如需要系统库的Python绑定 platform_system Linux: python-dev # 这是一个示例实际包名可能不同 # 通过环境标记指定依赖文件 {env:EXTRA_DEPS:} # 如果环境变量EXTRA_DEPS存在则安装它指定的内容 commands # 示例在非Windows平台运行一个需要bash的脚本 platform_system ! Windows: bash ./scripts/setup-test-fixtures.sh pytest这里使用了platform_system这个替换substitution它会在运行时被替换为实际的操作系统名称如WindowsLinuxDarwin。5.3 常见问题排查FAQQ1: 运行tox时报错InterpreterNotFound: python3.8A:这表示tox在你的系统路径中找不到名为python3.8的解释器。你需要确认该版本Python已安装。可以使用pyenv、conda或官方安装包来管理多个Python版本。告诉tox解释器的具体路径。可以在tox.ini中全局设置或通过环境变量指定[tox] envlist py38 [testenv] basepython /usr/local/bin/python3.8 # 或使用 pyenv 的路径更通用的做法是使用pyenv等工具并确保python3.8命令在终端中可用。Q2: 依赖安装速度慢每次运行都要重新下载安装包。A:可以充分利用pip的缓存和tox的--recreate策略。pip默认会缓存下载的包通常在~/.cache/pip。确保缓存目录存在且可写。在tox.ini中配置pip使用缓存并禁用索引检查可以加速[testenv] setenv PIP_DOWNLOAD_CACHE {toxworkdir}/.pip-cache # 使用tox工作目录下的缓存 install_command pip install {opts} {packages} --cache-dir {env:PIP_DOWNLOAD_CACHE} --disable-pip-version-check不要轻易使用tox -r或tox --recreate这会导致完全重建环境。只有当deps或项目依赖发生变更时才需要重建。Q3: 如何只运行某一个或某几个特定的测试环境A:使用-e选项。例如tox -e py310只运行py310环境。tox -e py310-django42lint运行py310-django42和lint两个环境。tox -e py3运行所有以py3开头的环境如py310py311。Q4: 测试命令失败了如何进入tox创建的虚拟环境进行调试A:tox提供了--notest和-a选项。tox -e py310 --notest为py310环境创建虚拟环境并安装所有依赖但不运行commands中的命令。之后你可以手动激活这个环境进行调试source .tox/py310/bin/activate # Linux/macOS # 或 .tox\py310\Scripts\activate # Windowstox -a列出所有在tox.ini中定义的环境方便你查看。Q5: 项目结构复杂源码不在根目录tox找不到要安装的包。A:使用tox.ini中的[tox]节下的changedir和package_root配置或者在[testenv]节下使用changedir来改变命令执行的工作目录。但更标准的做法是正确配置你的pyproject.toml使用[tool.setuptools]或[tool.poetry]来声明包的位置tox会遵循这些元数据。5.4 性能调优与最佳实践并行执行使用tox -p auto或tox -p 4可以让tox并行运行多个测试环境充分利用多核CPU。这在环境多、测试快的情况下提速明显。合理使用skipsdist和usedevelopskipsdist trueusedevelop false最快但不测试打包过程。适合纯代码测试。skipsdist false默认测试完整的构建和安装流程最全面但最慢。usedevelop true以开发模式安装pip install -e .修改代码后无需重新安装即可测试适合开发迭代但可能掩盖一些与安装路径相关的问题。环境复用与清理tox默认会复用已存在的虚拟环境。如果怀疑环境状态有问题比如残留了上次测试的脏数据可以使用tox -r重建。定期清理旧的、不用的环境直接删除.tox/目录下的子文件夹可以节省磁盘空间。配置文件拆分对于极其复杂的项目可以考虑将tox配置拆分到多个ini文件中或者使用tox -c other.ini来指定不同的配置文件针对不同的任务如单元测试、集成测试、文档构建进行分离。
Python跨环境测试神器tox：从核心概念到CI/CD集成实战
发布时间：2026/7/6 4:44:02
1. 项目概述为什么我们需要一个“测试神器”如果你写过一段时间的Python代码尤其是需要兼容多个Python版本比如2.7和3.x并存的老项目或者需要确保代码在3.7到3.11上都能跑或者你的项目依赖了不同版本的第三方库比如Django 2.2和Django 4.2那你一定对搭建测试环境的繁琐深有体会。手动创建虚拟环境、挨个安装依赖、切换解释器、运行测试命令……这套流程重复几次不仅效率低下还极易出错。更头疼的是团队协作时如何保证每个人本地跑测试的环境都是一致的tox就是为了解决这些痛点而生的。简单来说tox是一个命令行工具它允许你定义一份配置文件tox.ini在里面写明你想在哪些Python环境下比如py37py310pypy3运行哪些命令比如安装依赖、运行pytest、检查代码风格。你只需要执行一条tox命令它就会自动为你创建这些虚拟环境按顺序执行所有定义好的任务并给出清晰的报告。它把“跨环境测试”这个复杂任务变成了一个可重复、自动化、标准化的流程。我最初接触tox是在一个开源项目里当时被它“一键搞定所有测试环境”的能力震撼了从此就成了我项目中的标配工具。2. tox核心概念与工作流拆解要玩转tox得先理解它的几个核心概念这能帮你更好地规划你的测试矩阵。2.1 核心四要素envlist deps commands skipsdisttox的核心逻辑围绕着tox.ini配置文件展开其中几个关键部分决定了它的行为。1. 环境列表 (envlist):这是你测试矩阵的“总纲”。它定义了你要创建和运行哪些测试环境。环境名有约定俗成的规则比如py37代表使用Python 3.7解释器py310代表Python 3.10。你也可以定义组合环境比如py{37310}-django{2232}tox会自动展开成py37-django22py37-django32py310-django22py310-django32四个独立环境。envlist是你控制测试范围和粒度的主要手段。2. 依赖项 (deps):指定在这个测试环境中需要安装哪些额外的Python包。这通常包括你的项目依赖通过-r requirements.txt或-r pyproject.toml指定以及测试框架本身如pytestpytest-cov。deps的安装发生在虚拟环境创建之后项目包安装之前。3. 命令序列 (commands):这是每个测试环境最终要执行的任务列表。最常见的命令就是运行测试例如pytest tests/。但你也可以在这里运行代码风格检查flake8 .、类型检查mypy .、安全扫描bandit -r .等等。commands是按顺序执行的任何一个命令返回非零退出码该环境的测试就会被标记为失败。4. 跳过构建 (skipsdist):这是一个优化选项。默认情况下tox会先为你的项目构建一个源码分发包sdist然后在每个测试环境中安装这个分发包。这对于测试打包过程本身很有用。但如果你只想快速运行测试不关心打包设置skipsdist true可以跳过构建步骤直接在当前源码目录下安装依赖并运行命令速度会快很多。2.2 tox的工作流从命令到报告当你运行tox时背后发生了一系列自动化操作解析配置tox读取项目根目录下的tox.ini或pyproject.toml中的[tool.tox]部分理解你要测试哪些环境envlist。环境创建对于envlist中的每一个环境例如py310tox会在指定的位置默认是.tox/目录下创建一个独立的虚拟环境命名为.tox/py310。依赖安装在创建好的虚拟环境中tox会安装你在deps中列出的所有包。项目安装接着tox会将你的项目本身安装到这个虚拟环境中。默认模式是构建sdist再安装如果设置了skipsdist则会以“可编辑模式”pip install -e .直接安装当前代码。执行命令最后tox在对应的虚拟环境中依次执行commands中定义的命令。生成报告所有环境运行完毕后tox会在终端输出一份清晰的摘要报告列出每个环境的运行状态成功/失败和耗时。详细的日志则保存在每个环境对应的.tox/log子目录下。这个流程确保了每个测试环境都是全新的、隔离的并且完全由配置文件定义实现了测试的高度可重复性。3. 从零开始编写你的第一个tox.ini理论说再多不如动手实践。让我们从一个最简单的项目开始一步步搭建tox配置。假设我们有一个名为mycalculator的小项目结构如下mycalculator/ ├── src/ │ └── mycalculator/ │ ├── __init__.py │ └── calculator.py ├── tests/ │ ├── __init__.py │ └── test_calculator.py ├── requirements.txt └── pyproject.toml (或 setup.py)3.1 基础配置搭建首先在项目根目录创建tox.ini文件[tox] envlist py39 py310 py311 skipsdist true [testenv] deps pytest pytest-cov commands pytest tests/ -v --covsrc/mycalculator --cov-reportterm-missing逐行解析[tox]: 这是tox的全局配置节。envlist py39 py310 py311: 定义我们要在Python 3.9 3.10 3.11三个版本上运行测试。确保你的系统已经安装了这些版本的Python解释器。skipsdist true: 为了快速测试跳过源码包构建。[testenv]: 这是所有测试环境的通用配置节。下面定义的deps和commands会应用到envlist中的每一个环境。deps pytest pytest-cov: 每个测试环境都需要安装pytest和覆盖率插件。commands pytest tests/ ...: 在每个环境中运行的命令。这里我们运行pytest启用详细模式(-v)计算src/mycalculator目录的代码覆盖率(--cov)并在终端输出缺失覆盖率的报告(--cov-reportterm-missing)。现在在终端进入项目目录直接运行tox。你会看到tox开始依次创建三个虚拟环境.tox/py39.tox/py310.tox/py311安装依赖运行测试并最终输出汇总报告。3.2 进阶配置多环境与条件依赖真实项目往往更复杂。比如你的项目支持两个主要的第三方库版本并且需要在多个Python版本上测试兼容性。这时就需要用到因子Factors和环境特定配置。[tox] envlist py{39310311}-django{3242} py{310311}-fastapi lint [testenv] deps django{3242}: Django3.23.3 django{3242}: django{3242} fastapi: fastapi0.95.0 fastapi: uvicorn[standard] commands django{3242}: python manage.py test fastapi: pytest tests/ -v lint: flake8 src/ lint: mypy src/ [testenv:lint] deps flake8 mypy types-requests # 为mypy提供requests库的类型存根 skipsdist true配置解读复杂的envlist:py{39310311}-django{3242}: 会展开成6个环境py39-django32py39-django42py310-django32py310-django42py311-django32py311-django42。这构成了一个完整的Django版本兼容性测试矩阵。py{310311}-fastapi: 展开成2个环境测试在Python 3.10和3.11上对FastAPI的支持。lint: 一个独立的代码检查环境。条件依赖与命令:语法如django{3242}: Django3.23.3。这是一个条件依赖意思是只有当环境名中包含django32或django42这个因子时才安装Django3.23.3这个包。注意这里用了两个条件行来精确控制版本第一行是一个范围限制第二行django{3242}: django{3242}则会根据环境名具体安装django32或django42包假设这些版本包存在于你的索引中。更常见的做法是直接指定具体版本如django32: Django3.2.*。命令也支持条件语法。django{3242}: python manage.py test只会在Django环境中运行Django的测试命令而fastapi: pytest tests/ -v只在FastAPI环境中运行pytest。独立的环境配置节:[testenv:lint]专门为名为lint的环境定义配置。它会覆盖或合并[testenv]中的通用设置。这里我们为代码检查单独指定了依赖flake8 mypy和命令并且设置了skipsdist true因为lint检查不需要安装项目本身。实操心得依赖管理的技巧在deps中管理复杂依赖时一个常见的坑是条件判断的优先级和冲突。tox的解析顺序是从上到下。如果有多个条件匹配同一个环境所有匹配的依赖行都会被安装。为了避免版本冲突对于互斥的选项比如Django 3.2和4.2最好使用精确版本号并通过环境因子来区分而不是使用范围。另外将基础、共通的依赖如pytest放在无条件的行里将特定环境的依赖放在条件行里可以使配置更清晰。4. 深度实战集成现代Python开发工作流tox的强大之处在于它能无缝融入CI/CD流水线并与其他开发工具协同工作。下面我们看几个实战场景。4.1 与poetry/pdm的协同现代Python项目越来越多地使用pyproject.toml和Poetry或PDM来管理依赖和构建。tox可以很好地与它们配合。场景一使用Poetry锁定依赖如果你用Poetry你希望tox环境使用poetry.lock文件来确保依赖版本完全一致。[tox] envlist py310 py311 isolated_build true # 重要让tox使用pyproject.toml的构建后端 [testenv] usedevelop false # 关键使用 poetry export 来生成 requirements.txt deps poetry commands_pre # 在安装项目前先使用poetry导出依赖并安装 poetry export --without-hashes -f requirements.txt -o requirements.txt pip install -r requirements.txt commands pip install -e . # 然后以可编辑模式安装当前项目 pytest这里commands_pre是一个特殊的钩子它在deps安装之后commands执行之前运行。我们利用它调用poetry export生成一个确定性的requirements.txt然后用pip安装。这比让tox直接解析pyproject.toml更可靠尤其是当你的项目包含私有仓库或特殊索引时。场景二直接使用PDMPDM本身提供了pdm run命令来在执行命令时自动管理虚拟环境。但为了在CI中统一使用tox可以这样配置[tox] envlist py310 py311 [testenv] setenv PDM_IGNORE_SAVED_PYTHON 1 # 让PDM忽略保存的Python路径使用tox创建的env deps pdm commands # 使用PDM安装当前项目及其所有依赖包括开发依赖 pdm install --no-self pdm run pytestsetenv用于设置环境变量。这里我们告诉PDM使用当前激活的Python环境即tox创建的虚拟环境。pdm install --no-self会安装pyproject.toml中定义的所有依赖但跳过项目包本身因为我们要用当前源码。最后用pdm run来执行pytest。4.2 在GitHub Actions中运行tox将tox集成到GitHub Actions中可以实现每次推送代码或发起拉取请求时自动进行全矩阵测试。# .github/workflows/test.yml name: Test with tox on: [push pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: # 这里与tox的envlist保持同步或者让tox自己决定 python-version: [3.9 3.10 3.11] steps: - uses: actions/checkoutv3 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-pythonv4 with: python-version: ${{ matrix.python-version }} - name: Install tox run: pip install tox - name: Run tox for Python ${{ matrix.python-version }} run: tox -e py$(echo ${{ matrix.python-version }} | tr -d .) # 例如当python-version为3.10时运行 tox -e py310这个工作流为每个Python版本启动一个独立的Job并行运行测试可以大大缩短整体反馈时间。注意这里我们用了策略矩阵来定义Python版本并在run步骤中动态构造tox的环境名py310。你也可以简化成直接运行tox让tox根据tox.ini中的envlist自行管理所有环境但并行度就由tox控制了。注意事项CI环境下的缓存优化在CI中运行tox每次都要从头创建虚拟环境和安装依赖非常耗时。可以利用GitHub Actions的缓存机制来加速。常见的做法是缓存~/.cache/pip目录和tox的虚拟环境目录.tox/。但缓存.tox/需要小心因为不同Python版本、不同操作系统下的环境可能不兼容。一个更安全的策略是只缓存pip的下载包并利用tox的--recreate标志在依赖发生变更时强制重建环境。许多CI平台也提供了预置了多种Python版本和系统依赖的Docker镜像使用这些镜像作为基础能进一步减少环境准备时间。5. 高级技巧与疑难排坑实录即使熟悉了基础配置在实际使用中你还是会遇到一些“坑”。下面是我总结的几个常见问题和进阶技巧。5.1 环境变量与配置传递测试有时需要依赖环境变量比如数据库连接字符串、API密钥当然测试用的应该是假密钥。tox提供了几种方式在tox.ini中设置[testenv] setenv DATABASE_URL sqlite://:memory: API_KEY test-key-123这些变量会在该环境执行命令时生效。通过命令行传递tox -- MY_VARvalue在--之后传递的参数会被设置为环境变量。在commands中你可以通过{env:MY_VAR}来引用它。使用passenv继承主机环境变量[testenv] passenv CI TRAVIS JENKINS_URL # 传递这些特定的主机环境变量这在CI环境中非常有用可以让测试感知到是在CI中运行。5.2 处理平台特异性依赖有些依赖只在特定操作系统上存在或者需要不同的安装方式。tox支持基于平台的条件判断。[testenv] deps # 所有平台都需要的通用依赖 pytest # Windows平台特定依赖 platform_system Windows: pywin32 # Linux平台特定依赖例如需要系统库的Python绑定 platform_system Linux: python-dev # 这是一个示例实际包名可能不同 # 通过环境标记指定依赖文件 {env:EXTRA_DEPS:} # 如果环境变量EXTRA_DEPS存在则安装它指定的内容 commands # 示例在非Windows平台运行一个需要bash的脚本 platform_system ! Windows: bash ./scripts/setup-test-fixtures.sh pytest这里使用了platform_system这个替换substitution它会在运行时被替换为实际的操作系统名称如WindowsLinuxDarwin。5.3 常见问题排查FAQQ1: 运行tox时报错InterpreterNotFound: python3.8A:这表示tox在你的系统路径中找不到名为python3.8的解释器。你需要确认该版本Python已安装。可以使用pyenv、conda或官方安装包来管理多个Python版本。告诉tox解释器的具体路径。可以在tox.ini中全局设置或通过环境变量指定[tox] envlist py38 [testenv] basepython /usr/local/bin/python3.8 # 或使用 pyenv 的路径更通用的做法是使用pyenv等工具并确保python3.8命令在终端中可用。Q2: 依赖安装速度慢每次运行都要重新下载安装包。A:可以充分利用pip的缓存和tox的--recreate策略。pip默认会缓存下载的包通常在~/.cache/pip。确保缓存目录存在且可写。在tox.ini中配置pip使用缓存并禁用索引检查可以加速[testenv] setenv PIP_DOWNLOAD_CACHE {toxworkdir}/.pip-cache # 使用tox工作目录下的缓存 install_command pip install {opts} {packages} --cache-dir {env:PIP_DOWNLOAD_CACHE} --disable-pip-version-check不要轻易使用tox -r或tox --recreate这会导致完全重建环境。只有当deps或项目依赖发生变更时才需要重建。Q3: 如何只运行某一个或某几个特定的测试环境A:使用-e选项。例如tox -e py310只运行py310环境。tox -e py310-django42lint运行py310-django42和lint两个环境。tox -e py3运行所有以py3开头的环境如py310py311。Q4: 测试命令失败了如何进入tox创建的虚拟环境进行调试A:tox提供了--notest和-a选项。tox -e py310 --notest为py310环境创建虚拟环境并安装所有依赖但不运行commands中的命令。之后你可以手动激活这个环境进行调试source .tox/py310/bin/activate # Linux/macOS # 或 .tox\py310\Scripts\activate # Windowstox -a列出所有在tox.ini中定义的环境方便你查看。Q5: 项目结构复杂源码不在根目录tox找不到要安装的包。A:使用tox.ini中的[tox]节下的changedir和package_root配置或者在[testenv]节下使用changedir来改变命令执行的工作目录。但更标准的做法是正确配置你的pyproject.toml使用[tool.setuptools]或[tool.poetry]来声明包的位置tox会遵循这些元数据。5.4 性能调优与最佳实践并行执行使用tox -p auto或tox -p 4可以让tox并行运行多个测试环境充分利用多核CPU。这在环境多、测试快的情况下提速明显。合理使用skipsdist和usedevelopskipsdist trueusedevelop false最快但不测试打包过程。适合纯代码测试。skipsdist false默认测试完整的构建和安装流程最全面但最慢。usedevelop true以开发模式安装pip install -e .修改代码后无需重新安装即可测试适合开发迭代但可能掩盖一些与安装路径相关的问题。环境复用与清理tox默认会复用已存在的虚拟环境。如果怀疑环境状态有问题比如残留了上次测试的脏数据可以使用tox -r重建。定期清理旧的、不用的环境直接删除.tox/目录下的子文件夹可以节省磁盘空间。配置文件拆分对于极其复杂的项目可以考虑将tox配置拆分到多个ini文件中或者使用tox -c other.ini来指定不同的配置文件针对不同的任务如单元测试、集成测试、文档构建进行分离。
