Welcome to pytest-portion’s documentation!

pytest-portion is a pytest plugin that allows you to easily run a specific subset of your test suite. This is particularly useful for parallelizing CI builds without complex orchestration.

Usage

The plugin provides two primary modes of operation.

1. Test-Level Slicing (Default)

By default, the plugin collects all tests and then slices the collected items.

# Run the first half of all collected tests
pytest --portion 1/2

# Run tests in a specific percentage range
pytest --portion 0.5:1.0

2. File-Level Slicing

If you have a very large number of test files, collection itself can be slow. Use --portion-files to slice the list of files before pytest starts looking inside them.

# Portion the files to accelerate collection
pytest --portion 1/2 --portion-files

How it Works

Comparison

Mode

Behavior

Default

Collects everything, then deselects tests. Best for even distribution of parametrized tests.

Portion Files

Scans the directory, slices the file list, and ignores files not in the portion. Best for speeding up collection in huge repos.

Configuration

The --portion argument accepts two formats:

  • Fractional: i/n (where i is the 1-indexed slice number and n is total slices).

  • Percentage: start:end (where start and end are floats between 0 and 1).

Contents:

Indices and tables