## 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

```text
$ 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