pytest-rerunfailures

16.1 · active · verified Sun Mar 29

pytest-rerunfailures is a plugin for pytest that re-runs failed or intermittently failing tests to eliminate flaky failures, improving the reliability of CI/CD pipelines. It is actively maintained with frequent releases, typically every few months, adding new features and ensuring compatibility with the latest Python and pytest versions.

Warnings

breaking Dropped support for older Python and pytest versions in recent releases. Version 16.1 requires Python 3.10+, and version 16.0 requires pytest 8.0+.
Fix: Upgrade your Python environment to 3.10+ and pytest to 8.0+ before upgrading to `pytest-rerunfailures` 16.0 or newer.
gotcha Incompatible with `pytest-xdist`'s `--looponfail` flag, `pytest`'s core `--pdb` flag, and the `flaky` plugin. Do not use `pytest-rerunfailures` simultaneously with these. Also, explicitly incompatible with `pytest-rerunclassfailures`.
Fix: Choose one rerun/flakiness plugin or strategy. If using `pytest-xdist`, ensure you are not using `--looponfail`. Avoid using `--pdb` with reruns.
gotcha The order of precedence for setting rerun counts is: `@pytest.mark.flaky()` decorator > command-line `--reruns` option > `pytest.ini`/`pyproject.toml` configuration. The `--force-reruns` command-line option can override all other settings.
Fix: Be mindful of where you define your rerun counts. If you find unexpected rerun behavior, check if a higher-priority setting is overriding your intended configuration.
gotcha Recovery from hard crashes (e.g., segfaults) using `pytest-xdist` (via the `-n` flag) requires `pytest-xdist >= 2.3.0` and assumes workers and controller are on the same local area network (LAN). This functionality may not operate if this assumption is not met.
Fix: Ensure `pytest-xdist` is updated to a compatible version and that your test execution environment for parallel runs aligns with the LAN assumption for crash recovery.
gotcha When a teardown function fails, `pytest-rerunfailures` will generate two reports: one for the test case itself and another for the teardown error. This can sometimes be confusing in the test output.
Fix: Be aware of this reporting behavior when debugging tests where teardown issues might occur. The separate reports help pinpoint whether the failure was in the test logic or the cleanup.

Install

pip install pytest-rerunfailures Install stable version

Imports

pytest
```
import pytest
```
Used for marking tests as flaky via `@pytest.mark.flaky()`. The plugin itself is activated via pytest's discovery mechanism, not direct imports.

Quickstart

To enable `pytest-rerunfailures`, simply install it. You can configure reruns via command-line options (`pytest --reruns N`), a `pytest.mark.flaky` decorator on individual tests, or globally in `pytest.ini`/`pyproject.toml`. Adding `--reruns-delay N` introduces a pause between retries.

import pytest
import random

def test_flaky_example():
    # This test will randomly fail, demonstrating rerunfailures
    if random.choice([True, False, False]): # Higher chance to fail initially
        pytest.fail("Simulated flaky failure")

# To run with reruns: pytest --reruns 3 your_test_file.py
# To mark a specific test as flaky:
@pytest.mark.flaky(reruns=2, reruns_delay=1)
def test_another_flaky_example():
    if random.choice([True, False]):
        pytest.fail("Another flaky failure")

# Example of pytest.ini configuration (add to a file named pytest.ini in your project root):
# [pytest]
# reruns = 2
# reruns_delay = 1
# You can then run: pytest

view raw JSON →