pytest-split-tests

1.1.0 verified Fri May 01 auth: no python

A Pytest plugin for running a subset of your tests by splitting them into equally sized groups. Useful for parallel test execution across CI runners. Version 1.1.0 is the latest, forked from pytest-test-groups.

pip install pytest-split-tests

Common errors

error ModuleNotFoundError: No module named 'pytest_split_tests' ↓

cause The package is installed but the plugin is not discovered because pytest is run without the correct version or the plugin is not installed in the same environment.

fix

Ensure pytest is installed in the same environment: pip install pytest pytest-split-tests

error Error: --group requires --groups to be specified. ↓

cause The --group argument is used without providing --groups.

fix

Use --group=<N> --groups=<TOTAL> together.

error AttributeError: module 'pytest' has no attribute 'register_assert_rewrite' ↓

cause Incompatible pytest version (likely too old).

fix

Upgrade pytest: pip install --upgrade pytest

Warnings

breaking pytest-split-tests does not support Python 2; requires Python 3.6+. ↓

fix Upgrade to Python 3.6+.

deprecated The original project pytest-test-groups is unmaintained; pytest-split-tests is the active fork. ↓

fix Use pytest-split-tests instead of pytest-test-groups.

gotcha By default, --grouped-by is set to 'name' which may not distribute tests evenly across groups. Use --grouped-by=file for better distribution. ↓

fix Add '--grouped-by=file' to pytest command.

gotcha The plugin requires the --groups argument to be set; if omitted, all tests run (no splitting). This can cause silent unexpected behavior. ↓

fix Always specify --groups when using --group.

Imports

pytest_split_tests
wrong
```
from pytest_split_tests import something
```
correct
```
import pytest_split_tests
```
The plugin is auto-discovered; no explicit import needed. Importing is only for accessing internal helpers, not standard usage.

Quickstart

Run tests in group 1 of 4 groups, grouped by file, with loadscope distribution.

pytest --group=1 --groups=4 --grouped-by=file --dist=loadscope