xdist

Pytest · Reference cheat sheet

📋 Overview

pytest-xdist runs tests in parallel across CPUs or distributed workers. Use -n auto locally; ensure tests are isolated (no shared files/DB rows).

🔧 Core concepts

Each worker is a separate process with its own imports and fixtures (session fixtures run per worker).

💡 Examples

Install & run:

python -m pip install pytest-xdist
pytest -n auto
pytest -n 4 --dist loadscope

Unique resources per worker:

import os
import pytest

@pytest.fixture(scope="session")
def db_name(worker_id):
    if worker_id == "master":
        return "test_db"
    return f"test_db_{worker_id}"

Loadfile for order-sensitive modules:

pytest -n 4 --dist loadfile

Detect xdist:

def test_only_parallel(worker_id):
    assert worker_id.startswith("gw") or worker_id == "master"

⚠️ Pitfalls

• Shared temp paths / ports colliding across workers.
• Session-scoped DB fixtures assuming a single process.
• Flaky tests that only fail under -n auto.
• Coverage needing compatible pytest-cov settings with xdist.
• Using --looponfail in CI (dev-only workflow).

🔗 Related

• Install
• Fixtures
• Coverage
• CLI
• tmp_path
• Plugins