pytest-cream

Intelligent test orchestration for pytest. Splits tests by duration and runs them efficiently - long tests sequentially, short tests in parallel.

Installation

pip install pytest-cream

Quick Start

# Initialize: fetch tests and install dependencies
pytest-cream init --repo owner/project

# Profile: collect test durations
pytest-cream profile

# Run: execute with intelligent orchestration
pytest-cream run

The workspace is saved to .pytest-cream.json after init, so subsequent commands just work.

Common Options

# Run only fast tests (skip slow ones)
pytest-cream run --short-only

# Limit number of tests
pytest-cream run --limit 50

# Adjust threshold for long/short split (default: 0.5s)
pytest-cream run --threshold 0.3

# Set parallel workers (default: 4)
pytest-cream run --workers 8

# Exclude test patterns
pytest-cream run --exclude-tests "test_integration/,test_slow.py"

# Combine options
pytest-cream run --short-only --limit 30 --workers 8

How It Works

1. profile runs all tests and records their durations
2. run splits tests by duration threshold
3. Long tests run sequentially (cache warming)
4. Short tests run in parallel (pytest-xdist)

Commands

init

Fetch tests from a repository and install dependencies.

pytest-cream init --repo owner/project [--branch main] [--ws path]

Uses current directory by default. Warns if directory is not empty.

profile

Run tests and collect duration statistics.

pytest-cream profile [--ws path] [--python python3.11]

run

Execute tests with intelligent orchestration.

pytest-cream run [OPTIONS]
  --threshold FLOAT    Duration threshold for long/short split (default: 0.5)
  --workers INT        Parallel workers for short tests (default: 4)
  --short-only         Skip long tests
  --limit INT          Maximum number of tests to run
  --exclude-tests STR  Comma-separated patterns to exclude
  --ws PATH            Workspace directory
  --python PATH        Python executable

filter

Analyze and filter tests by duration.

pytest-cream filter --ws path --threshold 0.5

fetch

Fetch tests from repository (without installing dependencies).

pytest-cream fetch --repo owner/project --ws path

Configuration

• Config file: .pytest-cream.json (created in current directory)
• Workspace: Current directory by default
• Python: Auto-detected from workspace .venv or system Python
• Package manager: Uses uv by default, falls back to pip

Examples

# Development workflow - quick feedback
pytest-cream init --repo psf/requests
pytest-cream profile
pytest-cream run --short-only --limit 30

# CI pipeline - full suite
pytest-cream run --threshold 1.0 --workers 16

# Custom installation
pytest-cream init --repo owner/project --install-cmd "pip install -e .[dev]"

# Use pip instead of uv
pytest-cream init --repo owner/project --use-pip

Requirements

• Python 3.10+
• pytest
• pytest-xdist (for parallel execution)
• uv (optional, for faster installs)

License

MIT