Skip to main content

pytest-partition-check

pytest-partition-check verifies that a human-maintained set of pytest node-ID patterns forms a true partition: every pattern selects at least one test, and every test belongs to exactly one pattern.

Why

Repositories often give CI shards different responsibilities. One shard may need Docker, another may use secrets or a special runner, and another may be gated by a workflow condition. Their patterns are a deliberate, human-owned artefact. Pytest, workflow linting, and coverage do not report empty, overlapping, or missing shards.

The closest project is pytest-split. It owns the split: users commit a .test_durations file and run pytest --splits N --group K. Related tools include pytest-shard and pytest-xdist’s distribution modes. This package instead checks hand-maintained node-ID patterns without replacing them.

Usage

The motivating use case reads shard patterns from a GitHub Actions workflow. Install the optional YAML extra and pyprojroot first (pip install pytest-partition-check[yaml] pyprojroot). Adapt the job and matrix key names to your workflow; this repository’s test job is tests and does not expose a dedicated pattern list key, so the example below uses placeholders:

"""Check that CI patterns partition the test suite."""

from pathlib import Path

import pytest
import yaml
from pyprojroot import find_root, has_file
from pytest_partition_check import PartitionError, check_partition

def test_ci_patterns_partition_test_suite() -> None:
    """Check the shard patterns from the CI workflow."""
    repository_root = find_root(
        criterion=has_file(file="pyproject.toml"),
        start=Path(__file__).resolve(),
    )
    workflow = repository_root / ".github" / "workflows" / "test.yml"
    config = yaml.safe_load(workflow.read_text())
    # Replace "tests" / "shard_pattern" with your job and matrix key.
    matrix = config["jobs"]["tests"]["strategy"]["matrix"]
    try:
        check_partition(
            patterns=matrix["shard_pattern"],
            rootdir=repository_root,
            disable_plugins=("pytest-retry", "pytest_beartype"),
            extra_args=("--disable-warnings",),
        )
    except PartitionError as error:
        pytest.fail(reason=str(error))

The pytest plugin offers repeatable --check-partition=PATTERN arguments. Store one pattern per line in a committed file with --partition-patterns-path=PATH or the partition_patterns_path ini option. In plugin mode, forward nested-collection settings with --partition-disable-plugin / partition_disable_plugins and --partition-extra-arg / partition_extra_args (the functional API still uses disable_plugins and extra_args).

A standalone check is also available:

$ pytest-check-partition tests/unit tests/integration

Patterns files support # comments: full-line comments and lines whose first non-whitespace character is # are ignored. The CLI merges positional patterns, --patterns-stdin lines, and --partition-patterns-path entries into one list, for example pytest-check-partition shard_a --partition-patterns-path extra.txt.

Patterns can also be read one per line from standard input, which is useful when extracting a CI matrix from another configuration file:

$ generate-patterns | pytest-check-partition --patterns-stdin

Nested pytest collection

check_partition runs one nested pytest --collect-only session per pattern plus one more for the full-suite baseline (N+1 collections). That cost is intentional so each shard is evaluated the same way CI will run it.

Nested collection warnings are not re-emitted to the caller. Pass extra_args=("--disable-warnings",) when unknown.ini options from disabled plugins would otherwise warn loudly.

Collection runs in-process through pytest.main --collect-only. The package reads the final session.items after collection-modification and deselection hooks. This answers what a shard will actually run, including -m filters and --deselect, rather than reporting raw discovery.

Outer plugins also enter nested runs and can fail or mutate them. In practice, callers commonly disable pytest-retry because it can raise ValueError: no option named 'filtered_exceptions' and disable pytest_beartype to avoid decorating tests during a collection-only run. Disabled plugins may leave unknown ini options, so extra_args=("--disable-warnings",) is usually helpful.

pytest-split, pytest-randomly, and pytest-xdist are disabled by default during nested collection. Configuration addopts are cleared too. In particular, inherited --splits and --group settings would otherwise make the full suite look like one group and create bogus uncollected findings. Put collection filters needed by the check in extra_args explicitly. To opt out of a default plugin disable, reload it later in the nested argv, for example extra_args=("-p", "split", "--splits", "2", "--group", "1").

Nested collection failures raise NestedPytestError, which is part of the public API alongside PartitionError.

Usage and internal pytest failures are raised loudly. Only pytest’s explicit NO_TESTS_COLLECTED result means that a pattern matched nothing.

When not to use this

If your shards are interchangeable and you only want balance, use pytest-split instead. It makes this whole class of bug impossible rather than detecting it. Use this checker when the pattern list is intentionally a human-owned artefact.

License

MIT.

Metadata

Release files for pytest-partition-check 2026.10.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-partition-check 2026.10.11
File Size Uploaded Provenance Actions
pytest_partition_check-2026.10.11.tar.gz 28.7 kB With provenance Details for pytest_partition_check-2026.10.11.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytest-partition-check 2026.10.11
File Interpreter ABI Platform Actions
pytest_partition_check-2026.10.11-py3-none-any.whl Python 3 none any Details for pytest_partition_check-2026.10.11-py3-none-any.whl

Total release size: 39.9 kB

Release files / pytest_partition_check-2026.10.11.tar.gz

Download URL pytest_partition_check-2026.10.11.tar.gz
Size 28.7 kB
Tags Source
SHA-256 checksum
How to use checksums
e50725e81ec09b7462610efb3a1c130df25438cdec9ad46833a1d493b14e4c0c
BLAKE2b-256 checksum
How to use checksums
4097ba4ccc16722bfeb6986bdb139fa5a757cf0e05b41df29adb37714f9c4b12
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

Release files / pytest_partition_check-2026.10.11-py3-none-any.whl

Download URL pytest_partition_check-2026.10.11-py3-none-any.whl
Size 11.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cd3050e0104902214487bf4d50760c3719157085b41ca7d69c20fc24ad342642
BLAKE2b-256 checksum
How to use checksums
e851012299e6e557619b8986290c2fc9fbe73ed7a2704e1de2e7f2b581f6c027
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

Security for pytest-partition-check 2026.10.11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pytest_partition_check-2026.10.11.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page