pytest-repeat

0.9.4 · active · verified Thu Apr 09

pytest-repeat is a pytest plugin that allows you to repeat tests a specified number of times, either globally via command-line options or per test item using markers. This can be useful for stress testing, identifying flaky tests, or observing behavior under repeated execution. The current version is 0.9.4, and it generally follows pytest's release cycle, with updates typically coinciding with or following major pytest releases.

Warnings

gotcha Fixture teardown and setup behavior with `repeat-scope` can be counter-intuitive. By default (`--repeat-scope=function`), all fixtures including 'function' scoped ones are torn down and re-setup for each test repeat. However, if you set `--repeat-scope` to `module` or `session`, fixtures scoped at that level (or higher) will only be setup once for the entire block of repeats within that scope, not per individual repeat. This can lead to state leakage if tests or higher-scoped fixtures modify shared resources that are not properly reset between repeats.
Fix: Be explicit about fixture scopes and `repeat-scope`. If state isolation is crucial between repeats, ensure `function`-scoped fixtures handle cleanup, or use `pytest.fixture(autouse=True)` with proper teardown logic if higher scopes are needed. Consider `pytest-xdist` for true isolation across parallel runs instead of repeats for certain scenarios.
gotcha Tests that are not idempotent and modify global state or mutable shared objects can produce inconsistent results when repeated. Each repeat runs within the same Python process and memory space (unless `pytest-xdist` is used), meaning side effects from previous repeats can affect subsequent ones.
Fix: Ensure tests are isolated. Use fixtures for setting up and tearing down state, making sure any modifications are reverted or unique for each test run (or repeat). Avoid global variables where possible, or reset them rigorously in `setup_function` / `teardown_function` or `autouse` fixtures.
gotcha The default `repeat-scope` is `function`. This means if you use `--count=N` without explicitly setting `--repeat-scope`, *every* test item (including setup/teardown for `function`-scoped fixtures) will be repeated `N` times independently. This might not be the desired behavior if you want to repeat an entire module or session as a block without re-running module/session scoped fixtures repeatedly.
Fix: If you intend to repeat an entire module or session as a block, use `--repeat-scope=module` or `--repeat-scope=session` respectively, in conjunction with `--count`. This ensures that higher-scoped fixtures are only run once per the chosen repeat scope.

Install

pip install pytest-repeat Install stable version

Quickstart

To use pytest-repeat, simply install it. You can repeat all collected tests using the `--count` CLI option, or apply `pytest.mark.repeat(count=N)` to individual test functions or classes. The example demonstrates both a test marked for repetition and a global CLI usage comment. Note the `counter` variable to illustrate how state can persist or need careful management across repeats.

import pytest

# test_example.py
counter = 0

@pytest.mark.repeat(count=2)
def test_something_flaky():
    global counter
    counter += 1
    print(f"\nRunning test_something_flaky, repeat count: {counter}")
    assert counter < 3 # This will pass on first repeat, fail on second if not reset

def test_another_one():
    assert True

# To run via CLI:
# pytest --count=3 test_example.py -v
# (This would repeat both tests 3 times)
# 
# To run with marker (as above):
# pytest test_example.py -v

view raw JSON →