pytest-split

0.11.0 · active · verified Mon Apr 06

Pytest plugin (version 0.11.0) which splits the test suite into equally sized sub-suites based on test execution time. This enables faster and more balanced parallelization of tests in CI/CD environments. It is actively maintained with a consistent release cadence, often including support for new Python and Pytest versions.

Warnings

breaking Support for older Python versions has been progressively removed. Version 0.11.0 dropped support for Python 3.8 and 3.9. Version 0.9.0 dropped support for Python 3.7. Ensure your environment uses Python 3.10 or newer (up to 3.14).
Fix: Upgrade to a supported Python version (>=3.10) or pin pytest-split to an older version compatible with your Python environment.
breaking Older versions of pytest-split (prior to 0.8.1) might use deprecated pytest APIs, potentially causing issues or warnings with newer pytest releases. Ensure you are on a recent version to maintain compatibility.
Fix: Upgrade to pytest-split>=0.8.1 to ensure compatibility with updated pytest APIs.
gotcha When using test-order randomization plugins (e.g., `pytest-randomly`, `pytest-random-order`) with the default `duration_based_chunks` splitting algorithm, tests might be selected in multiple groups or not at all. This algorithm is incompatible with such plugins.
Fix: If using randomization plugins, switch to the `least_duration` algorithm (`--splitting-algorithm least_duration`) or ensure a global random seed is computed and used for all groups via `--random-order-seed`.
gotcha While `pytest-split` can handle new/removed tests by assuming average execution times, major changes to your test suite (many new/removed/renamed tests) can lead to unbalanced splits over time. The `.test_durations` file should be periodically updated.
Fix: Regularly re-run `pytest --store-durations` after significant changes to your test suite to update the `.test_durations` file and ensure optimal, balanced test splitting.
deprecated The format of the `.test_durations` file changed in version 0.4.0. While not explicitly stated as a breaking change for existing files, it might affect custom parsing logic if you relied on the older format.
Fix: If you have custom tooling that processes the `.test_durations` file and are on an older version, be aware of potential format changes when upgrading. It's best to regenerate the file with `pytest --store-durations` after upgrading.

Install

pip install pytest-split Install stable version

Quickstart

First, run pytest with the `--store-durations` flag to collect and save the execution times of your tests into a `.test_durations` file. This file should be committed to your repository. Then, use the `--splits N --group X` flags to divide your test suite into `N` groups and execute only the tests belonging to group `X`. This is typically used in CI/CD pipelines to parallelize test execution across multiple jobs.

# 1. Store test durations from a complete test suite run
pytest --store-durations

# This creates a .test_durations file in the current directory.
# It should be committed to your repository.

# 2. Split and run a specific group of tests (e.g., group 1 of 3 total splits)
pytest --splits 3 --group 1

view raw JSON →