pytest-shard

0.1.2 · maintenance · verified Sat Apr 11

pytest-shard is a pytest plugin (version 0.1.2) designed to parallelize test execution across multiple machines by sharding tests based on a hash of their test names. It enables fine-grained parallelism at the individual test case level, making it suitable for various continuous integration (CI) services. The library appears to be in a maintenance phase, with the last PyPI update in December 2020.

Warnings

gotcha pytest-shard does not take into account the run time of tests when sharding, which can lead to suboptimal load balancing and uneven test execution times across shards. This may result in some CI jobs finishing significantly later than others, despite an even numerical distribution of tests.
Fix: Manually balance test durations across files/modules if even time distribution is critical. Consider alternative sharding mechanisms or CI-specific tools that track test durations for more sophisticated load balancing.
gotcha Sharding is based on a hash of the test name. Renaming tests or significantly changing their structure can alter their hash, causing them to move to a different shard. This can lead to unexpected test distribution changes in CI, potentially causing certain tests to be rerun on different machines or requiring manual re-evaluation of shard contents.
Fix: Be aware that test renames will re-shard tests. If consistent sharding across minor changes is critical, consider using more stable test identifiers or a different sharding strategy. Avoid frequent, large-scale renames without understanding the impact on sharding.
gotcha The `--shard-id` command-line option in pytest-shard is 0-indexed (e.g., `--shard-id=0` for the first shard). Users configuring CI environments should ensure their environment variables (like `CIRCLE_NODE_INDEX` or `TRAVIS_JOB_NUMBER`) are correctly mapped to this 0-indexed scheme to avoid skipping shards or encountering out-of-bounds errors.
Fix: Ensure CI environment variables providing the shard index are 0-based. If a variable is 1-based (e.g., `TRAVIS_JOB_NUMBER`), adjust it (e.g., `--shard-id=$((${TRAVIS_JOB_NUMBER} - 1))`) when passing to pytest.

Install

pip install pytest-shard Install latest version

Imports

pytest-shard plugin
```
No direct Python import needed; it's a pytest plugin automatically discovered.
```
pytest-shard integrates as a plugin and is enabled via command-line arguments to pytest, rather than explicit Python import statements in test files.

Quickstart

After installation, pytest-shard is enabled by passing `--shard-id` and `--num-shards` arguments to the `pytest` command. `--shard-id` specifies the index of the current shard (0-indexed), and `--num-shards` specifies the total number of shards. This is typically configured in CI pipelines where tests are distributed across parallel jobs.

# Example: Shard tests across two machines
# On machine 1:
pytest --shard-id=0 --num-shards=2

# On machine 2:
pytest --shard-id=1 --num-shards=2

# Example for CircleCI:
pytest --shard-id=${CIRCLE_NODE_INDEX} --num-shards=${CIRCLE_NODE_TOTAL}

view raw JSON →