pytest-test-groups

1.2.1 · active · verified Fri Apr 10

pytest-test-groups is a Pytest plugin (current version 1.2.1) designed to split a test run into equally sized groups, allowing users to execute a subset of their tests. This is particularly useful in Continuous Integration (CI) environments for parallelizing test execution. The library maintains an active development status with periodic releases to support newer Python and Pytest versions.

Warnings

breaking Version 1.1.0 dropped support for Python 2.x and bumped the minimum required version of Pytest. Users on older Python or Pytest versions should use an earlier `pytest-test-groups` release.
Fix: Upgrade to Python 3.8+ and ensure Pytest is updated to a compatible version (e.g., `pytest>=4.0`). Consider pinning `pytest-test-groups<1.1.0` if unable to upgrade Python or Pytest.
breaking As a pytest plugin, `pytest-test-groups` inherits compatibility requirements from `pytest`. Major `pytest` releases (e.g., `pytest` 8.0.0 and 9.0.0) have dropped support for older Python versions (Python 3.8 in `pytest` 8, Python 3.9 in `pytest` 9). Ensure your Python environment is compatible with your installed `pytest` version.
Fix: Upgrade to a supported Python version (e.g., Python 3.10+ for current `pytest` releases) if you are using recent `pytest` versions.
gotcha `pytest-test-groups` divides *all collected tests* into groups based on their execution order or file path. It does not use `pytest.mark` decorators for custom, named test groups. If you need to run specific logical groups of tests (e.g., 'sanity', 'regression'), consider using `pytest.mark` with `-m` flags instead of or in conjunction with `pytest-test-groups`.
Fix: Understand that `pytest-test-groups` provides a mechanism for splitting all tests into arbitrary, equally-sized buckets for parallelization, not for semantic grouping. Use `pytest.mark` for semantic grouping.
gotcha When using randomized test grouping (which can be the default or explicitly enabled), not specifying a `--test-group-random-seed` can lead to inconsistent group assignments between different test runs. This can complicate debugging or CI retries where the same tests need to be run in the same group.
Fix: Always provide the `--test-group-random-seed=<INTEGER>` argument when running tests in groups, particularly in CI, to ensure reproducible test grouping.

Install

pip install pytest-test-groups Install stable version

Imports

pytest-test-groups
```
This plugin primarily extends pytest via command-line arguments and hooks; direct Python imports by end-users are not typically needed for its core functionality.
```
The functionality is integrated directly into the `pytest` command-line interface. There are no common Python symbols users need to import from `pytest_test_groups`.

Quickstart

Create a test file and run pytest with the `--test-group-count` and `--test-group-id` arguments to execute a specific subset of tests. Optionally, use `--test-group-random-seed` for reproducible random grouping.

# Save as test_example.py
import pytest

def test_alpha():
    assert True

def test_beta():
    assert True

def test_gamma():
    assert True

def test_delta():
    assert True

def test_epsilon():
    assert True

# To run group 1 of 2:
# pytest --test-group-count=2 --test-group-id=1

# To run group 2 of 2:
# pytest --test-group-count=2 --test-group-id=2

# To ensure consistent grouping across runs, especially with random selection:
# pytest --test-group-count=2 --test-group-id=1 --test-group-random-seed=123

view raw JSON →