开始免费使用
当前位置：首页 > Python > pytest-xdist 分布式执行高级用法：参数详解与分组策略

pytest-xdist 分布式执行高级用法：参数详解与分组策略

清欢
清欢
发布时间：2026-10-15| 4人浏览过
原创

本文深入解析 pytest-xdist 插件的高级用法，涵盖使用 -n 参数调用多核资源，以及 --dist 命令参数的四种分发模式：load、loadscope、loadfile 和 loadgroup。重点介绍如何通过 xdist_group 标记实现测试用例的灵活分组，确保特定测试在同一 Worker 中运行，适用于需要共享 Fixture 或状态的场景。

pytest-xdist 并行执行基础

若需利用多个 CPU 核心加速测试执行，可启用 -n 参数（或 --numprocesses）。例如，指定使用 8 个核心来运行测试用例。

pytest -n 8

--dist 分发模式详解

通过添加 -n auto 参数，pytest-xdist 可自动检测并利用计算机的所有可用核心来执行测试。测试分发算法可通过 --dist 命令参数进行定制，具体选项如下。

  • --dist load（默认模式）：系统将随机将测试用例分配给各个 CPU 核心。此模式不保证测试的执行顺序，适用于无状态依赖的独立测试。
  • --dist loadscope：针对测试函数，按模块进行分组；针对测试方法，按类进行分组。每个组作为一个整体分配给可用的 Worker 进程。这确保了组内所有测试均在同一进程中运行，对于依赖模块级或类级 Fixture 的场景尤为有用。当同时存在类级和模块级分组时，类级分组优先级更高。
  • --dist loadfile：测试用例按其所在文件进行分组。每个文件作为一个整体分配给可用的 Worker。这保证了同一文件中的所有测试都在同一个辅助进程中运行，有助于保持文件内的执行上下文一致。
  • --dist loadgroup：测试用例根据 xdist_group 标记进行分组。每个组作为一个整体分配给执行器。这确保了所有具有相同 xdist_group 名称的测试都在同一个 Worker 中运行，适用于需要跨文件共享状态或资源的测试场景。
@pytest.mark.xdist_group(name="group1")
def test1():
    pass

class TestA:
    @pytest.mark.xdist_group("group1")
    def test2():
        pass-

例如，标记为 group1 的 test1 和 TestA::test2 将在同一个 Worker 中运行。未添加 xdist_group 标记的测试则按默认的 --dist=load 模式正常执行。

  • --dist no：这是 pytest 的正常执行模式，即串行运行测试，不进行任何分发处理。

xdist_group 分组实战示例

以下示例展示了项目目录结构及具体测试文件内容。

xdist_test.py

import logging
import pytest
class TestXdist(object):
    @pytest.mark.xdist_group("group1")
    def test_one(self):
        logging.info("1")
        assert True
    @pytest.mark.xdist_group("group1")
    def test_two(self):
        logging.info("2")
        assert True
    @pytest.mark.xdist_group("group2")
    def test_three(self):
        logging.info("3")
        assert True
    @pytest.mark.xdist_group("group2")
    def test_four(self):
        logging.info("4")
        assert True

xdist_dummy_test.py

import logging
import pytest
class TestXdist(object):
    @pytest.mark.run(order=1)
    @pytest.mark.xdist_group("group1")
    def test_dummy_one(self):
        logging.info("d1")
        assert True
    @pytest.mark.xdist_group("group1")
    @pytest.mark.run(order=2)
    def test_dummy_two(self):
        logging.info("d2")
        assert True
    @pytest.mark.run(order=3)
    @pytest.mark.xdist_group("group2")
    def test_dummy_three(self):
        logging.info("d3")
        assert True
    @pytest.mark.xdist_group("group2")
    @pytest.mark.run(order=4)
    def test_dummy_four(self):
        logging.info("d4")
        assert True
(venv) ➜  pytest pytest -n auto --dist loadscope
=========================================================================== test session starts ===========================================================================
platform darwin -- Python 3.8.9, pytest-7.1.2, pluggy-1.0.0
rootdir: /Users/spock/PycharmProjects/pytest, configfile: pytest.ini
plugins: xdist-2.5.0, forked-1.4.0, ordering-0.6
[gw0] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw1] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw2] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw3] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw4] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw5] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw6] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw7] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
gw0 [8] / gw1 [8] / gw2 [8] / gw3 [8] / gw4 [8] / gw5 [8] / gw6 [8] / gw7 [8]
scheduling tests via LoadScopeScheduling

test2/xdist_dummy_test.py::TestXdist::test_dummy_one 
test/xdist_test.py::TestXdist::test_one 
[gw0] [ 12%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_one 
[gw1] [ 25%] PASSED test/xdist_test.py::TestXdist::test_one 
test2/xdist_dummy_test.py::TestXdist::test_dummy_two 
test/xdist_test.py::TestXdist::test_two 
[gw1] [ 37%] PASSED test/xdist_test.py::TestXdist::test_two 
test/xdist_test.py::TestXdist::test_three 
[gw0] [ 50%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_two 
test2/xdist_dummy_test.py::TestXdist::test_dummy_three 
[gw1] [ 62%] PASSED test/xdist_test.py::TestXdist::test_three 
test/xdist_test.py::TestXdist::test_four 
[gw0] [ 75%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_three 
test2/xdist_dummy_test.py::TestXdist::test_dummy_four 
[gw1] [ 87%] PASSED test/xdist_test.py::TestXdist::test_four 
[gw0] [100%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_four
============================================================================ 8 passed in 0.40s ============================================================================
(venv) ➜  pytest pytest -n auto --dist loadfile 
=========================================================================== test session starts ===========================================================================
platform darwin -- Python 3.8.9, pytest-7.1.2, pluggy-1.0.0
rootdir: /Users/spock/PycharmProjects/pytest, configfile: pytest.ini
plugins: xdist-2.5.0, forked-1.4.0, ordering-0.6
[gw0] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw1] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw2] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw3] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw4] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw5] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw6] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw7] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
gw0 [8] / gw1 [8] / gw2 [8] / gw3 [8] / gw4 [8] / gw5 [8] / gw6 [8] / gw7 [8]
scheduling tests via LoadFileScheduling

test/xdist_test.py::TestXdist::test_one 
test2/xdist_dummy_test.py::TestXdist::test_dummy_one 
[gw1] [ 12%] PASSED test/xdist_test.py::TestXdist::test_one 
[gw0] [ 25%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_one 
test/xdist_test.py::TestXdist::test_two 
test2/xdist_dummy_test.py::TestXdist::test_dummy_two 
[gw1] [ 37%] PASSED test/xdist_test.py::TestXdist::test_two 
[gw0] [ 50%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_two 
test2/xdist_dummy_test.py::TestXdist::test_dummy_three 
test/xdist_test.py::TestXdist::test_three 
[gw1] [ 62%] PASSED test/xdist_test.py::TestXdist::test_three 
[gw0] [ 75%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_three 
test2/xdist_dummy_test.py::TestXdist::test_dummy_four 
test/xdist_test.py::TestXdist::test_four 
[gw1] [ 87%] PASSED test/xdist_test.py::TestXdist::test_four 
[gw0] [100%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_four 

============================================================================ 8 passed in 0.38s ============================================================================
(venv) ➜  pytest pytest -n auto --dist loadgroup
=========================================================================== test session starts ===========================================================================
platform darwin -- Python 3.8.9, pytest-7.1.2, pluggy-1.0.0
rootdir: /Users/spock/PycharmProjects/pytest, configfile: pytest.ini
plugins: xdist-2.5.0, forked-1.4.0, ordering-0.6
[gw0] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw1] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw2] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw3] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw4] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw5] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw6] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
[gw7] Python 3.8.9 (default, May 17 2022, 12:55:41)  -- [Clang 13.1.6 (clang-1316.0.21.2.5)]
gw0 [8] / gw1 [8] / gw2 [8] / gw3 [8] / gw4 [8] / gw5 [8] / gw6 [8] / gw7 [8]
scheduling tests via LoadGroupScheduling

test2/xdist_dummy_test.py::TestXdist::test_dummy_three@group2 
test2/xdist_dummy_test.py::TestXdist::test_dummy_one@group1 
[gw1] [ 12%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_three@group2 
test2/xdist_dummy_test.py::TestXdist::test_dummy_four@group2 
[gw0] [ 25%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_one@group1 
[gw1] [ 37%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_four@group2 
test2/xdist_dummy_test.py::TestXdist::test_dummy_two@group1 
[gw0] [ 50%] PASSED test2/xdist_dummy_test.py::TestXdist::test_dummy_two@group1 
test/xdist_test.py::TestXdist::test_three@group2 
[gw1] [ 62%] PASSED test/xdist_test.py::TestXdist::test_three@group2 
test/xdist_test.py::TestXdist::test_four@group2 
[gw1] [ 75%] PASSED test/xdist_test.py::TestXdist::test_four@group2 
test/xdist_test.py::TestXdist::test_one@group1 
[gw0] [ 87%] PASSED test/xdist_test.py::TestXdist::test_one@group1 
test/xdist_test.py::TestXdist::test_two@group1 
[gw0] [100%] PASSED test/xdist_test.py::TestXdist::test_two@group1 

============================================================================ 8 passed in 0.40s ============================================================================

以上就是关于 pytest-xdist 分布式执行插件高级用法的详细介绍。如需了解更多相关内容，建议查阅本站往期文章或继续浏览后续章节，感谢支持。

相关文章

相关标签: Python pytest

免责声明：本文内容仅供参考，不代表本站观点。转载或引用请注明出处。

作者最新文章

全部文章

Python 相关产品和应用

全部下载
PythonSelenium
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

Python机器学习
scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Python代码质量
Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Python代码质量
Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

Pythonpytest
pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

PythonFastAPI
FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架，支持类型提示和自动接口文档。

PythonFlask
Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

PythonDjango
Django

Django

6.1.2 · Windows

成熟的 Python Web 框架，适合构建内容站点和业务系统。

PythonSpyder
Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

PythonSciPy
SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。