pytest-rerunfailures is a plugin for pytest that re-runs tests to eliminate intermittent failures.

You will need the following prerequisites in order to use pytest-rerunfailures:

• Python 3.10+ or PyPy3
• pytest 8.1 or newer

This plugin can recover from a hard crash with the following optional prerequisites:

• pytest-xdist 2.3.0 or newer

This package is currently tested against the last 5 minor pytest releases. In case you work with an older version of pytest you should consider updating or use one of the earlier versions of this package.

To install pytest-rerunfailures:

If one or more tests trigger a hard crash (for example: segfault), this plugin will ordinarily be unable to rerun the test. However, if a compatible version of pytest-xdist is installed, and the tests are run within pytest-xdist using the -n flag, this plugin will be able to rerun crashed tests, assuming the workers and controller are on the same LAN (this assumption is valid for almost all cases because most of the time the workers and controller are on the same computer). If this assumption is not the case, then this functionality may not operate.

To re-run all test failures, use the --reruns command line option with the maximum number of times you'd like the tests to run:

Failed fixture or setup_class will also be re-executed.

To add a delay time between re-runs use the --reruns-delay command line option with the amount of seconds that you would like wait before the next test re-run is launched:

To re-run only those failures that match a certain list of expressions, use the --only-rerun flag and pass it a regular expression. For example, the following would only rerun those errors that match AssertionError:

Passing the flag multiple times accumulates the arguments, so the following would only rerun those errors that match AssertionError or ValueError:

To re-run only those failures that do not match a certain list of expressions, use the --rerun-except flag and pass it a regular expression. For example, the following would only rerun errors other than that match AssertionError:

Passing the flag multiple times accumulates the arguments, so the following would only rerun those errors that does not match with AssertionError or OSError:

To mark individual tests as flaky, and have them automatically re-run when they fail, add the flaky mark with the maximum number of times you'd like the test to run:

Note that when teardown fails, two reports are generated for the case, one for the test case and the other for the teardown error.

You can also specify the re-run delay time in the marker:

You can also specify an optional condition in the re-run marker:

Exception filtering can be accomplished by specifying regular expressions for only_rerun and rerun_except. They override the --only-rerun and --rerun-except command line arguments, respectively.

Arguments can be a single string:

Or a list of strings:

Exception classes are also accepted and match any subclass:

You can use @pytest.mark.flaky(condition) similarly as @pytest.mark.skipif(condition), see pytest-mark-skipif

Note that the test will re-run for any condition that is truthy.

To force a specific re-run count globally, irrespective of the number of re-runs specified in test markers, pass --force-reruns:

By default the marker count takes strict priority over the global --reruns setting. To make them additive instead, pass --reruns-mode=append. With append, a test decorated with @pytest.mark.flaky(reruns=2) run with --reruns 4 will be re-run up to 2 + 4 = 6 times:

By default only the final attempt of a flaky test produces a traceback, so failures from earlier attempts (including those of tests that ultimately pass after a rerun) are silently discarded. To inspect them, pass --rerun-show-tracebacks:

Each retried attempt's traceback is appended to the rerun test summary info section. The section is emitted automatically when the flag is set, so -rR is not required.

Here's an example of the output provided by the plugin when run with --reruns 2 and -r aR:

test_report.py RRF ================================== FAILURES ================================== __________________________________ test_fail _________________________________ def test_fail(): > assert False E assert False test_report.py:9: AssertionError ============================ rerun test summary info ========================= RERUN test_report.py::test_fail RERUN test_report.py::test_fail ============================ short test summary info ========================= FAIL test_report.py::test_fail ======================= 1 failed, 2 rerun in 0.02 seconds ====================

Note that output will show all re-runs. Tests that fail on all the re-runs will be marked as failed.

• This plugin is not compatible with pytest-xdist's --looponfail flag.
• This plugin is not compatible with the core --pdb flag.
• This plugin is not compatible with the plugin flaky, you can only have pytest-rerunfailures or flaky but not both.

You can specify arguments in three places. So if you set the number of reruns in all three, which one takes priority?

• Top priority is the marker, such as @pytest.mark.flaky(reruns=1)
• Second priority is what's specified on the command line, like --reruns=2
• Last priority is the pyproject.toml (or pytest.ini) file setting, like reruns = 3

Additionally, all three can be overridden by passing --force-reruns argument on the command line. Passing --reruns-mode=append makes the marker count and the global --reruns / reruns ini setting additive instead of strict.

• Issue Tracker
• Code

• Test execution count can be retrieved from the execution_count attribute in test item's object. Example:

  @hookimpl(tryfirst=True) def pytest_runtest_makereport(item, call): print(item.execution_count)