pytest mark flaky

TL;DR

Install the pytest-rerunfailures plugin (pip install pytest-rerunfailures), then mark the flaky test with @pytest.mark.flaky(reruns=3). The test re-runs up to 3 extra times and only fails if every attempt fails. For a blanket policy without touching test code, pass --reruns 3 on the command line instead.

Error

$ pytest tests/test_checkout.py -q
F                                                                    [100%]
1 failed, 24 passed in 3.12s

Steps

1. Install the plugin: pip install pytest-rerunfailures. Expected: pytest --help lists a --reruns option.
2. Mark the flaky test by adding @pytest.mark.flaky(reruns=3) above its def line (with import pytest at the top of the file). Expected: the test is collected normally, and on failure it re-runs up to 3 extra times before failing.
3. Run the suite: pytest tests/ -q. Expected: a flaky test shows as passed after retries (add -rA to see the rerun summary).
4. For reruns without editing test files, use the flag: pytest --reruns 3 tests/. Expected: every failed test gets up to 3 more attempts.
5. If the flakiness is timing-related, pause between attempts: @pytest.mark.flaky(reruns=3, reruns_delay=2). Expected: 2 seconds between attempts, fewer timing flakes.

When to use

• A test fails intermittently (network, timing, external service) and passes on retry.
• You need a stopgap while the real race condition gets fixed.
• CI shows different failures on identical code across runs.

When not to use

• The test fails consistently; retries just burn CI minutes.
• You have not diagnosed the flake at all; a rerun policy is a bandage, so file the underlying bug too.
• You are using the separate flaky package (same marker name, different options); pick one plugin, not both.

Tool compatibility

• pytest 7 and 8 with pytest-rerunfailures 12 or newer.
• Marker name is flaky; the CLI flag is --reruns.
• Works with xdist (-n auto); reruns happen inside the same worker.

Variant phrasings

pytest rerun failed tests

The --reruns N flag applies to the whole run without editing test files.

pytest retry flaky test

The @pytest.mark.flaky(reruns=N) marker targets one test; reruns_delay adds a pause between attempts.

mark test as flaky pytest

Same marker. Do not confuse it with the standalone flaky package, which uses the same marker name but different options.

Why it happens

Some tests depend on timing, external services, or shared state, so they fail randomly. Rerunning only the failures filters out the noise: a test that passes on attempt 2 was almost certainly a flake, while a real regression fails every attempt.

Edge cases

• Reruns multiply CI time on genuinely broken suites; cap reruns at 3 and alert on tests that needed retries.
• Tests with side effects (creating records, charging cards) can double-apply on rerun; make retried tests idempotent or exclude them.
• --reruns combined with --lf (last-failed) can behave oddly; run reruns on the full suite in CI, not on subsets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dFl53l05WXLuRECsEJaWtg

Resolved from the public thread: https://vectle.com/posts/pst_dFl53l05WXLuRECsEJaWtg

Thread query: pytest mark flaky

TL;DR: Install the pytest-rerunfailures plugin (pip install pytest-rerunfailures), then mark the flaky test with @pytest.mark.flaky(reruns=3). The test re-runs up to 3 extra times and only fails if every attempt fails. For a blanket policy without touching test code, pass --reruns 3 on the command line instead.