Update docs for new unittest debug modes

kxrob · kxrob · commit a4909a82795f · 2022-11-06T17:27:05.000+01:00
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
@@ -220,6 +220,25 @@ Command-line options
 
    See `Signal Handling`_ for the functions that provide this functionality.
 
+.. cmdoption:: --debug
+
+   On test fail or error the test run terminates immediately with original
+   exception - similar to normal script execution. Useful for seamless external
+   post-mortem handling.
+
+.. cmdoption:: --pdb
+
+   Runs ``pdb.post_mortem()`` upon each error. Short for ``--pm=pdb``
+
+.. cmdoption:: --pm
+
+   Run custom post-mortem debugger (module or class) upon each error.
+   Examples: ``--pm=pywin.debugger``, ``--pm=IPython.terminal.debugger.Pdb``
+
+.. cmdoption:: --trace
+
+   Break at the beginning of each test using :mod:`pdb` or the debugger set by ``--pm``
+
 .. cmdoption:: -f, --failfast
 
    Stop the test run on the first error or failure.
@@ -253,6 +272,9 @@ Command-line options
 .. versionadded:: 3.7
    The command-line option ``-k``.
 
+.. versionadded:: 3.12
+   The command-line options ``--debug``, ``--pdb`` and ``--pm``.
+
 The command line can also be used for test discovery, for running all of the
 tests in a project or just a subset.
 
@@ -2228,7 +2250,8 @@ Loading and running tests
 
 .. function:: main(module='__main__', defaultTest=None, argv=None, testRunner=None, \
                    testLoader=unittest.defaultTestLoader, exit=True, verbosity=1, \
-                   failfast=None, catchbreak=None, buffer=None, warnings=None)
+                   failfast=None, catchbreak=None, buffer=None, warnings=None, \
+                   debug=False)
 
    A command-line program that loads a set of tests from *module* and runs them;
    this is primarily for making test modules conveniently executable.
@@ -2279,6 +2302,12 @@ Loading and running tests
    Calling ``main`` actually returns an instance of the ``TestProgram`` class.
    This stores the result of the tests run as the ``result`` attribute.
 
+   When *debug* is ``True`` (corresponding to ``--debug``) execution terminates
+   with original exception upon the first error. When *debug* is the name of a
+   debugger module or class - for example ":mod:`pdb`" - then post-mortem debugging is
+   run upon each error.
+
+
    .. versionchanged:: 3.1
       The *exit* parameter was added.
 
@@ -2290,6 +2319,9 @@ Loading and running tests
       The *defaultTest* parameter was changed to also accept an iterable of
       test names.
 
+   .. versionchanged:: 3.12
+      The *debug* parameter was added.
+
 
 load_tests Protocol
 ###################
diff --git a/Misc/NEWS.d/next/Library/2022-19-25-17-11-34.gh-issue-62965.ZNAp9W.rst b/Misc/NEWS.d/next/Library/2022-19-25-17-11-34.gh-issue-62965.ZNAp9W.rst
@@ -0,0 +1 @@
+Added ``--debug``, ``--pdb``, ``--pm``, ``--trace`` command line options to :mod:`unittest`.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Added ``--debug``, ``--pdb``, ``--pm``, ``--trace`` command line options to :mod:`unittest`.