pytest-circleci-parallelized

0.1.0 verified Fri May 01 auth: no python

A pytest plugin to automatically split test execution across CircleCI parallel containers. Currently at v0.1.0, it distributes tests by timings or file path hash. Low release cadence; last release was initial.

pip install pytest-circleci-parallelized

Common errors

error UsageError: --circleci-parallelize requires CIRCLE_NODE_TOTAL and CIRCLE_NODE_INDEX to be set ↓

cause Plugin checks environment variables; missing when not running on CircleCI or in a non-parallel job.

fix

Set environment variables manually for testing: export CIRCLE_NODE_TOTAL=2; export CIRCLE_NODE_INDEX=0. Or run pytest without --circleci-parallelize.

error No tests were found ↓

cause Plugin may not collect tests if file patterns don't match or if test path is not detected.

fix

Check that test files follow pytest naming conventions (test_*.py) and are in the current directory. Run pytest --collect-only first.

Warnings

gotcha Plugin requires CircleCI environment variables (CIRCLE_NODE_TOTAL and CIRCLE_NODE_INDEX). If running locally, these won't be set and the plugin will fail or do nothing. ↓

fix Only use in CircleCI parallel containers. For local testing, mock environment variables or run without the --circleci-parallelize flag.

gotcha The plugin may not distribute tests evenly if timings data is missing. It falls back to file path hashing which can be unbalanced. ↓

fix Run without timings first to generate JUnit XML, then supply --store-timings to collect data.

deprecated Requires Python 2.7 or 3.4+ (not 3.0-3.3). No support for Python 3.13+ tested. ↓

fix Ensure Python version >=2.7, !=3.0-3.3.

Imports

pytest
```
import pytest
```
Plugin auto-registers via conftest; no direct import needed.

Quickstart

Install the plugin and run pytest with --circleci-parallelize flag in a CircleCI job with parallelism > 1.

# Ensure CIRCLE_NODE_TOTAL and CIRCLE_NODE_INDEX are set
# In CircleCI config, set parallelism > 1
# Then run:
#   pip install pytest-circleci-parallelized
#   pytest --circleci-parallelize