Install & Compatibility
Where this runs
tested against v1.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 31.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.000s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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`.
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
Debug
Known issues
breakingVersion 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.fixUpgrade 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.
affects: <1.1.0
breakingAs 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.fixUpgrade to a supported Python version (e.g., Python 3.10+ for current `pytest` releases) if you are using recent `pytest` versions.
affects: pytest>=8.0.0, pytest-test-groups versions compatible with affected 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`.fixUnderstand 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.
affects: All versions
gotchaWhen 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.fixAlways provide the `--test-group-random-seed=<INTEGER>` argument when running tests in groups, particularly in CI, to ensure reproducible test grouping.
affects: All versions (especially 1.0.2+ which introduced the seed option)
Upgrade
Version history
1.2.1latest on PyPI · released May 8, 2025
Audit
Dependencies
pytestrequiredThis is a plugin for the pytest testing framework. Version 1.1.0 and later require a modern version of pytest (e.g., >=4.0).