repository·master·Indexed 19 days ago
https://github.com/pytest-dev/pytest-rerunfailuresA pytest plugin designed to eliminate intermittent test failures by automatically re-running tests that fail. It provides CLI options like --reruns, --reruns-delay, and --only-rerun, as well as the @pytest.mark.flaky decorator for fine-grained control over retry counts, delays, and conditions. The plugin supports exponential backoff, filtering by exception regex, and recovery from hard crashes (segfaults) when used with pytest-xdist.
When re-run counts are specified in multiple places, the following priority order applies (from highest to lowest):
@pytest.mark.flaky(reruns=X)--reruns Xreruns = X in pyproject.toml or pytest.iniNote: The --force-reruns CLI flag overrides all of the above. If --reruns-mode=append is used, the marker count and the global setting become additive instead of following this priority.
Use the @pytest.mark.flaky decorator to mark individual tests for automatic re-runs upon failure. This is useful for handling non-deterministic tests (e.g., race conditions or network latency). Settings applied via this decorator override global command-line options.
@pytest.mark.flaky(reruns=3)
def test_example():
import random
assert random.choice([True, False])To limit retries to specific error types, use the --only-rerun option with a regular expression. This allows you to target specific failures while ignoring others.
pytest --reruns 3 --only-rerun AssertionErrorIf tests trigger a hard crash (e.g., a segfault), pytest-rerunfailures can recover and rerun them if you meet these conditions:
pytest-xdist is installed.-n flag (pytest-xdist).To ensure code style and formatting consistency, use pre-commit. This framework manages multi-language hooks that run automatically during every commit. You can also trigger these checks via tox -e linting.
$ pip install --user pre-commit
$ pre-commit installTo prevent immediate retries (useful for waiting on external resources to stabilize), use the --reruns-delay option to specify the number of seconds to wait between each retry attempt.
pytest --reruns 3 --reruns-delay 2Command-line arguments take precedence over settings defined in pytest.ini. If you have defaults configured in your ini file but need different behavior for a specific run, use the --reruns and --reruns-delay flags.
pytest --reruns 5 --reruns-delay 1.5The project uses tox to automate testing and environment setup. tox will automatically create virtual environments (using virtualenv) to run the specified test suites. Use tox -e linting to run style checks or specify a Python version (e.g., py312) to run tests.
$ pip install tox
$ tox -e linting,py312Install pytest-rerunfailures using pip.
Prerequisites:
Optional for hard crash recovery:
$ pip install pytest-rerunfailures--reruns CLI option followed by the maximum number of retry attempts allowed. For example, pytest --reruns 3 will execute the test suite and retry any failed tests up to 3 times.pytest --reruns 3The plugin determines how many times a test should be rerun by combining the @flaky marker settings with global settings (CLI or .ini). This behavior is controlled by the --reruns-mode option:
strict (default): The marker takes priority. If a test is marked with @flaky(reruns=5), it will rerun 5 times, even if the global --reruns is set to 10.append: The counts are additive. If the global --reruns is 2 and the test is marked with @flaky(reruns=3), the test will rerun a total of 5 times.You can set default retry behaviors in your pytest.ini file to avoid specifying command-line arguments every time you run tests. The plugin supports two primary configuration keys under the [pytest] section: reruns and reruns_delay.
[pytest]
reruns = 3
reruns_delay = 2.0