pytest-forked

1.6.0 · active · verified Thu Apr 09

pytest-forked is a pytest plugin that runs tests in isolated forked subprocesses, preventing global state pollution and ensuring test independence. As of version 1.6.0, it supports modern Python (3.7+) and pytest versions, offering a crucial tool for test isolation. It generally follows pytest's release cadence for compatibility updates.

Warnings

breaking Python 2.7, 3.4, and 3.5 are no longer supported. Ensure your project uses Python 3.7 or newer to use pytest-forked >= 1.4.0.
Fix: Upgrade your Python environment to 3.7 or higher.
breaking Compatibility with older pytest versions is dropped. For example, pytest-forked v1.3.0 added support for pytest 6, and v1.2.0 fixed support for pytest 5.4.0+. Using older pytest-forked versions with new pytest, or vice-versa, can lead to unexpected behavior.
Fix: Ensure your pytest-forked and pytest versions are compatible. Refer to release notes on GitHub for specific version matrices. Generally, use the latest stable versions of both.
gotcha Forking can cause issues with shared resources (e.g., database connections, file handles) if not managed carefully. Resources opened before the fork might become invalid or problematic in child processes. Certain libraries or frameworks may not be 'fork-safe'.
Fix: Re-initialize shared resources within each test, or use fixtures with `scope='function'` that are executed after the fork. Avoid opening global resources in `conftest.py` setup code if they are not fork-safe.
gotcha Limited support for the `pytest.mark.xfail` marker. While improved in newer versions (v1.2.0+), some edge cases or specific interactions with `xfail` might not behave as expected under forked processes.
Fix: Upgrade to pytest-forked v1.2.0 or newer for improved `xfail` support. Thoroughly test `xfail` marked tests when using forked processes to confirm expected behavior.

Install

pip install pytest-forked Install stable version

Quickstart

pytest-forked is typically activated via command-line arguments or `pytest.ini` configuration, not by direct Python imports. This example demonstrates how tests benefit from isolation when `--forked` is used, preventing global state changes in one test from affecting another.

# test_isolation.py
import pytest

# A module-level variable to simulate global state
_global_resource_id = 0

def setup_module():
    global _global_resource_id
    _global_resource_id = 100 # This setup runs once per module

def test_isolated_resource_access():
    # Each forked test process gets its own copy of the global state
    # if it's set up before the fork, or a fresh state if set up within the test.
    assert _global_resource_id == 100

    # Simulate modifying a global resource
    global _global_resource_id
    _global_resource_id += 1
    assert _global_resource_id == 101

def test_another_isolated_resource_access():
    # This test, when forked, should start with the original _global_resource_id from setup_module,
    # not affected by modifications in test_isolated_resource_access.
    assert _global_resource_id == 100

# To run these tests with forked isolation:
# 1. Save the code above as test_isolation.py
# 2. Run from your terminal:
#    pytest --forked test_isolation.py

view raw JSON →