Document and test flaky(reruns=0) opting a test out of reruns

README.rst

@@ -192,6 +192,20 @@ test to run:
       import random
       assert random.choice([True, False])
 
+To disable re-runs for a single test while keeping global re-runs enabled,
+use ``reruns=0``. Since the marker takes priority over the global setting,
+this test will not be re-run even when ``--reruns`` is passed:
+
+.. code-block:: python
+
+  @pytest.mark.flaky(reruns=0)
+  def test_example():
+      assert foo() == bar()
+
+Note that ``--force-reruns`` still overrides the marker, and with
+``--reruns-mode=append`` the marker count is added to the global count, so
+``reruns=0`` does not opt the test out in that mode.
+
 Note that when teardown fails, two reports are generated for the case, one for
 the test case and the other for the teardown error.
 

changes/187.doc.rst

@@ -0,0 +1,3 @@
+Document that ``@pytest.mark.flaky(reruns=0)`` disables re-runs for a single
+test even when ``--reruns`` is set globally (the marker takes priority over
+the global setting).

tests/test_pytest_rerunfailures.py

@@ -617,6 +617,42 @@ def test_pass():
     assert_outcomes(result, passed=1, rerun=2)
 
 
+def test_flaky_marker_with_zero_reruns_disables_rerun(testdir):
+    testdir.makepyfile(
+        f"""
+        import pytest
+        @pytest.mark.flaky(reruns=0)
+        def test_fail():
+            {temporary_failure()}"""
+    )
+    result = testdir.runpytest("--reruns", "5")
+    assert_outcomes(result, passed=0, failed=1, rerun=0)
+
+
+def test_flaky_marker_with_zero_reruns_append_mode_still_reruns(testdir):
+    testdir.makepyfile(
+        f"""
+        import pytest
+        @pytest.mark.flaky(reruns=0)
+        def test_fail():
+            {temporary_failure()}"""
+    )
+    result = testdir.runpytest("--reruns", "1", "--reruns-mode", "append")
+    assert_outcomes(result, passed=1, rerun=1)
+
+
+def test_flaky_marker_with_zero_reruns_does_not_disable_force_reruns(testdir):
+    testdir.makepyfile(
+        f"""
+        import pytest
+        @pytest.mark.flaky(reruns=0)
+        def test_fail():
+            {temporary_failure()}"""
+    )
+    result = testdir.runpytest("--force-reruns", "1")
+    assert_outcomes(result, passed=1, rerun=1)
+
+
 def test_no_extra_test_summary_for_reruns_by_default(testdir):
     testdir.makepyfile(
         f"""