How to Use pytest‑rerunfailures to Rerun Flaky Tests

Introduction pytest‑rerunfailures is a useful plugin that automatically reruns test cases that fail on the first run, helping to stabilize flaky tests.

1. Installation Install the plugin via pip: pip install pytest-rerunfailures

2. Basic Usage Run tests with the -r option to specify the number of reruns, e.g., pytest -r 3 This will rerun each failing test up to three times.

3. Example Test File A sample test_example.py demonstrates several test cases, including a probabilistic failure in test_multiply :

import random

def test_add():
    assert 1 + 1 == 2

def test_subtract():
    assert 2 - 1 == 1

def test_multiply():
    # probabilistic failure
    if random.random() > 0.8:
        raise AssertionError("Multiply failed randomly")
    assert 2 * 3 == 6

def test_divide():
    assert 6 / 3 == 2

def test_power():
    assert 2 ** 3 == 8

Run the tests with reruns: pytest -r 3 test_example.py

Sample output shows which tests were rerun and the final summary.

4. Configuration File You can set the default rerun count in pytest.ini (or .pylintrc ) like this:

# ini
[pytest]
addopts = -r 3

This makes every pytest invocation automatically apply the rerun policy.

5. Advanced Usage

5.1 Custom rerun condition – only rerun failures matching a pattern: pytest -r 3 --rerunfailures-match="AssertionError"

5.2 Rerun a specific test case: pytest -r 3 test_example.py::test_multiply

5.3 Custom rerun count via environment variable: pytest -r $RERUN_COUNT test_example.py or set the variable first: export RERUN_COUNT=3 pytest test_example.py

6. Using the @pytest.mark.flaky Decorator The plugin also provides a flaky marker to annotate flaky tests directly:

import random
import pytest

@pytest.mark.flaky(reruns=3)
def test_multiply():
    if random.random() > 0.8:
        raise AssertionError("Multiply failed randomly")
    assert 2 * 3 == 6

Run the suite normally with pytest test_example.py ; the marked test will be rerun automatically.

Conclusion The article covered installation, basic and advanced usage, configuration, and the flaky decorator for pytest‑rerunfailures, providing a comprehensive reference for improving test reliability in Python projects.