Mark Specific Tests as Flaky

The @pytest.mark.flaky decorator allows you to mark individual tests as flaky and configure them to automatically re-run a specified number of times upon failure. This is particularly useful for specific tests that are intermittently failing due to non-deterministic conditions (e.g., network latency, race conditions). That mark also allows to override global settings specified via command-line options.

Basic Usage

To use the @pytest.mark.flaky decorator, include it in your test function and specify the number of retries using the reruns argument:

@pytest.mark.flaky(reruns=3)
def test_example():
    import random
    assert random.choice([True, False])

In this example, test_example will automatically re-run up to 3 times if it fails.

Additional Options

The @pytest.mark.flaky decorator supports the following optional arguments:

reruns_delay

Specify a delay (in seconds) between re-runs.

@pytest.mark.flaky(reruns=5, reruns_delay=2)
def test_example():
    import random
    assert random.choice([True, False])

This will retry the test 5 times with a 2-second pause between attempts.

condition

Re-run the test only if a specified condition is met. The condition can be any expression that evaluates to True or False.

import sys

@pytest.mark.flaky(reruns=3, condition=sys.platform.startswith("win32"))
def test_example():
    import random
    assert random.choice([True, False])

In this example, the test will only be re-run if the operating system is Windows.

only_rerun

Re-run the test only for specific exception types or patterns. That overrides the --only-rerun command-line option.

@pytest.mark.flaky(reruns=5, only_rerun=["AssertionError", "ValueError"])
def test_example():
    raise AssertionError()

rerun_except

Exclude specific exception types or patterns from triggering a re-run. That overrides the --rerun-except command-line option.

@pytest.mark.flaky(reruns=5, rerun_except="AssertionError")
def test_example():
    raise ValueError()