State leakage in session-scoped fixtures during parallel execution

Answer

Use a file‑based lock (e.g., the filelock library) around the setup code inside a session‑scoped fixture so that only one worker performs the global initialization.

Explanation

When pytest‑xdist runs with -n N, it spawns N worker processes. Each worker gets its own pytest session, so a fixture marked scope="session" is instantiated once per worker, not once for the whole test run. This can cause multiple workers to try to initialise the same external resource concurrently, leading to race conditions or state leakage.

Confirmed facts

• pytest‑xdist creates separate worker processes, each with its own Python interpreter and pytest state.
• The worker_id fixture is unique for every active worker (including the special value master for the main process).
• A file lock held by one process blocks others until the lock is released, providing a simple cross‑process mutex.

Steps to implement a single global setup

1. Add the filelock package to your test dependencies (pip install filelock).
2. Create a temporary directory that is visible to all workers (e.g., {tmpdir}/xdist_lock or a fixed path under the project root).
3. Write a session‑scoped fixture that acquires a lock on a file in that directory, performs the expensive setup while the lock is held, yields the resource, and releases the lock after the test session ends.
4. Use the fixture in your tests exactly as you would any other session‑scoped fixture.

import pytest
from filelock import FileLock, Timeout

@pytest.fixture(scope="session")
def global_db():
    lock_path = "/tmp/pytest_xdist_db_lock.lock"
    lock = FileLock(lock_path, timeout=30)
    try:
        # Only the first worker that obtains the lock runs the setup
        with lock.acquire():
            # ---- expensive one‑time setup ----
            db = create_database()   # replace with your actual setup
            yield db
            # ---- teardown (runs after all workers finish) ----
            db.dispose()
    except Timeout:
        # If a worker cannot get the lock within the timeout, fail fast
        pytest.fail("Could not acquire lock for global setup")

If your external resource can be safely initialised by more than one process at the same time, please confirm whether you prefer per‑worker isolation instead of a single global setup.