New --all-reruns-need-to-pass argument

CHANGES.rst

@@ -4,7 +4,9 @@ Changelog
 16.4 (unreleased)
 -----------------
 
-- Nothing changed yet.
+- Added the ``pytest_rerunfailures_rerun_policy`` hook: plugins can return a
+  ``RerunPolicy`` to give a specific failure class its own rerun count /
+  all-reruns-need-to-pass mode, without changing how other failures are rerun.
 
 
 16.3 (2026-05-22)

README.rst

@@ -236,6 +236,31 @@ 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.
 
+Per-failure rerun policy (hook)
+-------------------------------
+
+Plugins can give a *specific failure class* its own rerun count and semantics via the
+``pytest_rerunfailures_rerun_policy`` hook, without changing how other failures are
+rerun. The hook is called once per test, on its first failing report, and returns a
+``RerunPolicy`` (or ``None`` for the default behavior):
+
+.. code-block:: python
+
+    # conftest.py
+    from pytest_rerunfailures import RerunPolicy
+
+    def pytest_rerunfailures_rerun_policy(item, report, call):
+        # e.g. give transient provider/infra errors one rerun, pass on recovery —
+        # while other failures keep the global --reruns / --all-reruns-need-to-pass
+        # behavior.
+        exc = call.excinfo.value if call.excinfo else None
+        if isinstance(exc, ConnectionError):
+            return RerunPolicy(reruns=1, all_reruns_need_to_pass=False)
+        return None
+
+``RerunPolicy`` fields left ``None`` keep the plugin's default for that item. The policy
+is fixed at the item's first failure and applies to its whole rerun sequence.
+
 Output
 ------
 

pyproject.toml

@@ -50,6 +50,10 @@ entry-points.pytest11.rerunfailures = "pytest_rerunfailures"
 [tool.setuptools.dynamic]
 readme = { file = [ "HEADER.rst", "README.rst", "CHANGES.rst" ] }
 
+[tool.setuptools]
+package-dir = { "" = "src" }
+py-modules = [ "pytest_rerunfailures", "pytest_rerunfailures_newhooks" ]
+
 [tool.ruff]
 fix = true
 lint.select = [

src/pytest_rerunfailures.py

@@ -10,6 +10,7 @@
 import traceback
 import warnings
 from contextlib import suppress
+from dataclasses import dataclass
 
 import pytest
 from _pytest.outcomes import fail
@@ -46,6 +47,32 @@ def works_with_current_xdist():
 RERUNS_DELAY_DESC = "add time (seconds) delay between reruns."
 
 
+@dataclass(frozen=True)
+class RerunPolicy:
+    """Per-failure rerun policy returned by ``pytest_rerunfailures_rerun_policy``.
+
+    Any field left ``None`` keeps the plugin's default for that item.
+
+    Attributes:
+        reruns: Rerun count for this failure (overrides ``--reruns`` / the marker).
+        all_reruns_need_to_pass: Override all-reruns-need-to-pass for this failure.
+    """
+
+    reruns: int | None = None
+    all_reruns_need_to_pass: bool | None = None
+
+
+def pytest_addhooks(pluginmanager):
+    """Register this plugin's own hookspecs (see ``pytest_rerunfailures_newhooks``).
+
+    The specs live in a dedicated module so ``add_hookspecs`` sees only them, not this
+    module's own hook implementations.
+    """
+    import pytest_rerunfailures_newhooks
+
+    pluginmanager.add_hookspecs(pytest_rerunfailures_newhooks)
+
+
 # command line options
 def pytest_addoption(parser):
     group = parser.getgroup(
@@ -111,6 +138,16 @@ def pytest_addoption(parser):
         dest="fail_on_flaky",
         help="Fail the test run with exit code 7 if a flaky test passes on a rerun.",
     )
+    group._addoption(
+        "--all-reruns-need-to-pass",
+        action="store_true",
+        dest="all_reruns_need_to_pass",
+        default=False,
+        help=(
+            "If enabled, after an initial failure, all reruns must pass "
+            "for the test to succeed."
+        ),
+    )
     group._addoption(
         "--rerun-show-tracebacks",
         action="store_true",
@@ -124,6 +161,11 @@ def pytest_addoption(parser):
     arg_type = "string"
     parser.addini("reruns", RERUNS_DESC, type=arg_type)
     parser.addini("reruns_delay", RERUNS_DELAY_DESC, type=arg_type)
+    parser.addini(
+        "all_reruns_need_to_pass",
+        "If enabled, all reruns must pass after initial failure",
+        type=arg_type,
+    )
 
 
 # making sure the options make sense
@@ -205,6 +247,33 @@ def get_reruns_delay(item):
     return delay
 
 
+def get_all_reruns_need_to_pass(item):
+    """Get whether all reruns need to pass from marker, config, or ini."""
+    rerun_marker = _get_marker(item)
+
+    # Check marker kwargs first
+    if rerun_marker is not None and "all_reruns_need_to_pass" in rerun_marker.kwargs:
+        return rerun_marker.kwargs["all_reruns_need_to_pass"]
+
+    # Check command-line option
+    all_need_pass = item.session.config.getvalue("all_reruns_need_to_pass")
+    if all_need_pass is not None:
+        return all_need_pass
+
+    # Check ini value
+    try:
+        all_need_pass = item.session.config.getini("all_reruns_need_to_pass")
+        if all_need_pass:
+            # Parse string values like "True", "true", "1", etc.
+            if isinstance(all_need_pass, str):
+                return all_need_pass.lower() in ("true", "1", "yes", "on")
+            return bool(all_need_pass)
+    except (TypeError, ValueError):
+        pass
+
+    return False
+
+
 def get_reruns_condition(item):
     rerun_marker = _get_marker(item)
 
@@ -375,9 +444,10 @@ def pytest_configure(config):
     # add flaky marker
     config.addinivalue_line(
         "markers",
-        "flaky(reruns=1, reruns_delay=0): mark test to re-run up "
-        "to 'reruns' times. Add a delay of 'reruns_delay' seconds "
-        "between re-runs.",
+        "flaky(reruns=1, reruns_delay=0, all_reruns_need_to_pass=False): "
+        "mark test to re-run up to 'reruns' times. Add a delay of "
+        "'reruns_delay' seconds between re-runs. If "
+        "'all_reruns_need_to_pass' is True, all reruns must pass.",
     )
 
     if config.pluginmanager.hasplugin("xdist") and HAS_PYTEST_HANDLECRASHITEM:
@@ -599,6 +669,13 @@ def pytest_runtest_makereport(item, call):
         item, result, call.excinfo
     )
 
+    # On the first failure, ask plugins for a per-failure rerun policy so the protocol
+    # can give this failure class its own rerun count / semantics.
+    if result.failed and not hasattr(item, "_rerunfailures_policy"):
+        item._rerunfailures_policy = item.ihook.pytest_rerunfailures_rerun_policy(
+            item=item, report=result, call=call
+        )
+
 
 def pytest_runtest_protocol(item, nextitem):
     """
@@ -617,6 +694,7 @@ def pytest_runtest_protocol(item, nextitem):
     # first item if necessary
     check_options(item.session.config)
     delay = get_reruns_delay(item)
+    all_reruns_need_to_pass = get_all_reruns_need_to_pass(item)
     parallel = not is_master(item.config)
     db = item.session.config.failures_db
     item.execution_count = db.get_test_failures(item.nodeid)
@@ -625,31 +703,106 @@ def pytest_runtest_protocol(item, nextitem):
     if item.execution_count > reruns:
         return True
 
+    # Track rerun results when all reruns need to pass
+    initial_failure_occurred = False
+    rerun_results = []  # Track result of each rerun (True=passed, False=failed)
+    policy_applied = False
+
     need_to_run = True
     while need_to_run:
         item.execution_count += 1
         item.ihook.pytest_runtest_logstart(nodeid=item.nodeid, location=item.location)
         reports = runtestprotocol(item, nextitem=nextitem, log=False)
 
+        # Apply a per-failure rerun policy (pytest_rerunfailures_rerun_policy) once the
+        # first attempt has run and makereport has classified its failure. Lets a plugin
+        # override the rerun count / all-reruns mode for THIS item, without changing how
+        # other failures are rerun.
+        if not policy_applied:
+            policy = getattr(item, "_rerunfailures_policy", None)
+            if policy is not None:
+                policy_applied = True
+                if policy.reruns is not None:
+                    reruns = policy.reruns
+                    db.set_test_reruns(item.nodeid, reruns)
+                if policy.all_reruns_need_to_pass is not None:
+                    all_reruns_need_to_pass = policy.all_reruns_need_to_pass
+
         for report in reports:  # 3 reports: setup, call, teardown
             report.rerun = item.execution_count - 1
-            if _should_not_rerun(item, report, reruns):
-                # last run or no failure detected, log normally
-                item.ihook.pytest_runtest_logreport(report=report)
+
+            # Track initial failure for all_reruns_need_to_pass mode
+            if (
+                all_reruns_need_to_pass
+                and report.when == "call"
+                and report.failed
+                and item.execution_count == 1
+            ):
+                initial_failure_occurred = True
+
+            # Track rerun results (after initial failure) - only track call phase
+            if (
+                all_reruns_need_to_pass
+                and initial_failure_occurred
+                and item.execution_count > 1
+                and report.when == "call"
+            ):
+                rerun_results.append(
+                    not report.failed
+                )  # True if passed, False if failed
+
+            # In all_reruns_need_to_pass mode with initial failure,
+            # override normal behavior
+            if all_reruns_need_to_pass and initial_failure_occurred:
+                # execution_count starts at 1, so:
+                # - execution_count==1: initial run (failed)
+                # - execution_count==2..reruns+1: reruns (must run all of them)
+                is_last_rerun = item.execution_count > reruns
+
+                if is_last_rerun:
+                    # Last run, check if all reruns passed
+                    if any(not r for r in rerun_results):
+                        # At least one rerun failed, mark final outcome as failed
+                        if report.when == "call":
+                            report.outcome = "failed"
+                    # Log the final report
+                    item.ihook.pytest_runtest_logreport(report=report)
+                else:
+                    # Not the last rerun yet
+                    # Only trigger rerun after processing the call phase
+                    if report.when == "call":
+                        report.outcome = "rerun"
+                        time.sleep(delay)
+                        if not parallel or works_with_current_xdist():
+                            item.ihook.pytest_runtest_logreport(report=report)
+
+                        _remove_cached_results_from_failed_fixtures(item)
+                        _remove_failed_setup_state_from_session(item)
+                        break  # trigger rerun
+                    else:
+                        # For setup/teardown, just log normally
+                        item.ihook.pytest_runtest_logreport(report=report)
             else:
-                # failure detected and reruns not exhausted, since i < reruns
-                report.outcome = "rerun"
-                time.sleep(delay)
+                # Normal rerun behavior
+                should_not_rerun = _should_not_rerun(item, report, reruns)
 
-                if not parallel or works_with_current_xdist():
-                    # will rerun test, log intermediate result
+                if should_not_rerun:
+                    # last run or no failure detected, log normally
                     item.ihook.pytest_runtest_logreport(report=report)
+                else:
+                    # failure detected and reruns not exhausted
+                    report.outcome = "rerun"
+                    time.sleep(delay)
+
+                    if not parallel or works_with_current_xdist():
+                        # will rerun test, log intermediate result
+                        item.ihook.pytest_runtest_logreport(report=report)
 
-                # cleanin item's cashed results from any level of setups
-                _remove_cached_results_from_failed_fixtures(item)
-                _remove_failed_setup_state_from_session(item)
+                    # cleanin item's cashed results from any level of setups
+                    _remove_cached_results_from_failed_fixtures(item)
+                    _remove_failed_setup_state_from_session(item)
 
-                break  # trigger rerun
+                    break  # trigger rerun
         else:
             need_to_run = False
 

src/pytest_rerunfailures_newhooks.py

@@ -0,0 +1,30 @@
+"""Hook specifications added by the smith fork of pytest-rerunfailures.
+
+Kept in a dedicated module so ``PluginManager.add_hookspecs`` registers only these
+specs and not the plugin's own ``pytest_*`` hook implementations (pytest treats any
+``pytest_``-prefixed function in a namespace as a hookspec).
+"""
+
+import pytest
+
+
+@pytest.hookspec(firstresult=True)
+def pytest_rerunfailures_rerun_policy(item, report, call):
+    """Return a ``RerunPolicy`` for a test's first failure, or ``None`` for default.
+
+    Consulted once per test, on its first failing report (``.when`` may be ``"setup"``,
+    ``"call"``, or ``"teardown"``). The returned policy is locked to the item's WHOLE rerun
+    sequence -- it is not recomputed on later attempts, so a differently-classed failure on
+    a rerun inherits this policy (the rerun count / mode is fixed by the first failure). Lets
+    a plugin give a specific failure class (e.g. provider-infra errors) its own rerun count /
+    semantics, without affecting how other failures are rerun. The first non-None result wins.
+
+    Args:
+        item: The test item that failed.
+        report: The first failing ``TestReport`` (``.when`` is ``"setup"``, ``"call"``,
+            or ``"teardown"``).
+        call: The ``CallInfo`` (``call.excinfo`` carries the exception).
+
+    Returns:
+        A ``pytest_rerunfailures.RerunPolicy``, or ``None`` for default behavior.
+    """