From b681e27ab803c272e227c855255ecc950a1df9bc Mon Sep 17 00:00:00 2001 From: Badri Vishal Pandey Date: Tue, 27 Oct 2026 17:51:55 +0530 Subject: [PATCH] docs: explain bisecting failing tests --- testing/run-write-tests.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 405d10f039..adf5b22451 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -89,6 +89,25 @@ verbose mode (using ``-v``), so that individual failures are detailed: .\python.bat -m test -v test_abc +If a test module has several tests and only some of them fail, you can use the +``test.bisect_cmd`` helper to narrow down which tests reproduce the failure. +The helper repeatedly runs random subsets of the tests, so the failure should +be reproducible for the bisection to be useful. From the root of the checkout, +run it with the test module name and any test-runner arguments needed to +reproduce the failure:: + + ./python -m test.bisect_cmd test_abc + +By default, bisection stops when one failing test remains or after 100 +iterations. Use ``-n`` to stop with a larger number of tests, ``-N`` to change +the iteration limit, or ``-o`` to write the current failing test list to a +file:: + + ./python -m test.bisect_cmd -n 2 -N 200 -o failing-tests.txt test_abc + +The helper is part of the CPython test suite and is available in a built +checkout; see ``./python -m test.bisect_cmd -h`` for all options. + To run a single test case, use the ``unittest`` module, providing the import path to the test case: