pytest-xdist

The pytest-xdist plugin extends pytest with new test execution modes, the most used being distributing tests across multiple CPUs to speed up test execution:

pytest -n auto

With this call, pytest will spawn a number of workers processes equal to the number of available CPUs, and distribute the tests randomly across them.

Note

Due to how pytest-xdist is implemented, the -s/--capture=no option does not work.

Installation

Install the plugin with:

pip install pytest-xdist

To use psutil for detection of the number of CPUs available, install the psutil extra:

pip install pytest-xdist[psutil]

Features

• Test run Running tests across multiple CPUs: tests can be executed across multiple CPUs or hosts. This allows to speed up development or to use special resources of Sending tests to remote SSH accounts.

• --looponfail: run your tests repeatedly in a subprocess. After each run pytest waits until a file in your project changes and then re-runs the previously failing tests. This is repeated until all tests pass after which again a full run is performed (DEPRECATED).

• Sending tests to remote SSH accounts coverage: you can specify different Python interpreters or different platforms and run tests in parallel on all of them.

  Before running tests remotely, pytest efficiently “rsyncs” your program source code to the remote place. You may specify different Python versions and interpreters. It does not installs/synchronize dependencies however.

  Note: this mode exists mostly for backward compatibility, as modern development relies on continuous integration for multi-platform testing.

Contents:

• Running tests across multiple CPUs
• Running tests in a Python subprocess
• Sending tests to remote SSH accounts
  • Sending tests to remote Socket Servers
  • Running tests on many platforms at once
• When tests crash
• How-tos
  • Identifying the worker process during a test
  • Identifying workers from the system environment
  • Uniquely identifying the current test run
  • Accessing sys.argv from the controller node in workers
  • Specifying test exec environments in an ini file
  • Specifying “rsync” dirs in an ini-file
  • Making session-scoped fixtures execute only once
  • Creating one log file for each worker
• How it works?
  • FAQ
• Known limitations
  • Order and amount of test must be consistent
  • Output (stdout and stderr) from workers
• Changelog
  • pytest-xdist 3.6.1 (2024-04-28)
  • pytest-xdist 3.6.0 (2024-04-19)
  • pytest-xdist 3.5.0 (2023-11-21)
  • pytest-xdist 3.4.0 (2023-11-11)
  • pytest-xdist 3.3.1 (2023-05-19)
  • pytest-xdist 3.3.0 (2023-05-12)
  • pytest-xdist 3.2.1 (2023-03-12)
  • pytest-xdist 3.2.0 (2023-02-07)
  • pytest-xdist 3.1.0 (2022-12-01)
  • pytest-xdist 3.0.2 (2022-10-25)
  • pytest-xdist 2.5.0 (2021-12-10)
  • pytest-xdist 2.4.0 (2021-09-20)
  • pytest-xdist 2.3.0 (2021-06-16)
  • pytest-xdist 2.2.1 (2021-02-09)
  • pytest-xdist 2.2.0 (2020-12-14)
  • pytest-xdist 2.1.0 (2020-08-25)
  • pytest-xdist 2.0.0 (2020-08-12)
  • pytest-xdist 1.34.0 (2020-07-27)
  • pytest-xdist 1.33.0 (2020-07-09)
  • pytest-xdist 1.32.0 (2020-05-03)
  • pytest-xdist 1.31.0 (2019-12-19)
  • pytest-xdist 1.30.0 (2019-10-01)
  • pytest-xdist 1.29.0 (2019-06-14)
  • pytest-xdist 1.28.0 (2019-04-02)
  • pytest-xdist 1.27.0 (2019-02-15)
  • pytest-xdist 1.26.1 (2019-01-28)
  • pytest-xdist 1.26.0 (2019-01-11)
  • pytest-xdist 1.25.0 (2018-12-12)
  • pytest-xdist 1.24.1 (2018-11-09)
  • pytest-xdist 1.24.0 (2018-10-18)
  • pytest-xdist 1.23.2 (2018-09-28)
  • pytest-xdist 1.23.1 (2018-09-25)
  • pytest-xdist 1.23.0 (2018-08-23)
  • pytest-xdist 1.22.5 (2018-07-27)
  • pytest-xdist 1.22.4 (2018-07-27)
  • pytest-xdist 1.22.3 (2018-07-23)
  • pytest-xdist 1.22.2 (2018-02-26)
  • pytest-xdist 1.22.1 (2018-02-19)
  • pytest-xdist 1.22.0 (2018-01-11)
  • pytest-xdist 1.21.0 (2017-12-22)
  • pytest-xdist 1.20.1 (2017-10-05)
  • pytest-xdist 1.20.0 (2017-08-17)
  • pytest-xdist 1.19.1 (2017-08-10)
  • pytest-xdist 1.19.0 (2017-08-09)
  • pytest-xdist 1.18.2 (2017-07-28)
  • pytest-xdist 1.18.1 (2017-07-05)
  • pytest-xdist 1.18.0 (2017-06-26)
  • pytest-xdist 1.17.1 (2017-06-10)