add doc

python · giampaolo · Apr 2, 2023 · Mar 10, 2019 · Mar 10, 2019 · Mar 10, 2019
commit 9beb9310958bd9c3f59563dd12beca2544c5cb97
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
@@ -239,6 +239,10 @@ Command-line options
 
    Show local variables in tracebacks.
 
+.. cmdoption:: --durations
+
+   Show test durations.
+
 .. versionadded:: 3.2
    The command-line options ``-b``, ``-c`` and ``-f`` were added.
 
@@ -248,10 +252,12 @@ Command-line options
 .. versionadded:: 3.7
    The command-line option ``-k``.
 
+.. versionadded:: 3.8
+   The command-line option ``--durations``.
+
 The command line can also be used for test discovery, for running all of the
 tests in a project or just a subset.
 
-
 .. _unittest-test-discovery:
 
 Test Discovery
@@ -1868,6 +1874,13 @@ Loading and running tests
       A list containing :class:`TestCase` instances that were marked as expected
       failures, but succeeded.
 
+   .. attribute:: collectedDurations
+
+      A list containing 2-tuples of :class:`TestCase` instances and floats
+      representing the elapsed time of each test which was run.
+
+      .. versionadded:: 3.8
+
    .. attribute:: shouldStop
 
       Set to ``True`` when the execution of tests should stop by :meth:`stop`.
@@ -2019,16 +2032,26 @@ Loading and running tests
 
       .. versionadded:: 3.4
 
+   .. method:: addDuration(test, elapsed)
+
+      Called when the test case finishes. **elapsed** is the time represented
+      in seconds.
+
+      .. versionadded:: 3.8
 
-.. class:: TextTestResult(stream, descriptions, verbosity)
+.. class:: TextTestResult(stream, descriptions, verbosity, *, durations=None)
 
    A concrete implementation of :class:`TestResult` used by the
    :class:`TextTestRunner`.
+   Subclasses should accept ``**kwargs`` to ensure compatibility as the
+   interface changes.
 
    .. versionadded:: 3.2
       This class was previously named ``_TextTestResult``. The old name still
       exists as an alias but is deprecated.
 
+   .. versionadded:: 3.8
+      Added *durations* argument.
 
 .. data:: defaultTestLoader
 
@@ -2038,7 +2061,7 @@ Loading and running tests
 
 
 .. class:: TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, \
-                          buffer=False, resultclass=None, warnings=None, *, tb_locals=False)
+                          buffer=False, resultclass=None, warnings=None, *, tb_locals=False, durations=None)
 
    A basic test runner implementation that outputs results to a stream. If *stream*
    is ``None``, the default, :data:`sys.stderr` is used as the output stream. This class
@@ -2059,14 +2082,17 @@ Loading and running tests
    *warnings* to ``None``.
 
    .. versionchanged:: 3.2
-      Added the ``warnings`` argument.
+      Added the *warnings* parameter.
 
    .. versionchanged:: 3.2
       The default stream is set to :data:`sys.stderr` at instantiation time rather
       than import time.
 
    .. versionchanged:: 3.5
-      Added the tb_locals parameter.
+      Added the *tb_locals* parameter.
+
+   .. versionchanged:: 3.8
+      Added the *durations* parameter.
 
    .. method:: _makeResult()
 

diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
@@ -353,6 +353,25 @@ unittest
   :meth:`~unittest.TestCase.setUpClass()`.
   (Contributed by Lisa Roach in :issue:`24412`.)
 
+* Added ``--durations`` command line option, showing the slowest test cases and
+  the elapsed time of each individual test::
+
+    python3 -m unittest test_suite --durations=3
+    .....
+    Slowest test durations
+    ----------------------------------------------------------------------
+    0.051s     test_process (test_suite.TestCase)
+    0.209s     test_system (test_suite.TestCase)
+    0.414s     test_memory (test_suite.TestCase)
+
+    (0.000 durations hidden.  Use -v to show these durations.)
+    ----------------------------------------------------------------------
+    Ran 122 tests in 1.385s
+
+    OK (skipped=3)
+
+  (Contributed by Giampaolo Rodola in :issue:`4080`)
+
 venv
 ----
 
@@ -664,6 +683,12 @@ Changes in the Python API
   :exc:`dbm.gnu.error` or :exc:`dbm.ndbm.error`) instead of :exc:`KeyError`.
   (Contributed by Xiang Zhang in :issue:`33106`.)
 
+* :class:`unittest.TextTestRunner` and :class:`unittest.TextTestResult`
+  constructors have a new *durations* keyword argument. Subclasses should take
+  this into account or accept ``**kwargs``.
+  Added :meth:`unittest.TestResult.addDuration` method and
+  :attr:`unittest.TestResult.collectedDurations` attribute.
+  (Contributed by Giampaolo Rodola in :issue:`4080`)
 
 CPython bytecode changes
 ------------------------

diff --git a/Lib/unittest/runner.py b/Lib/unittest/runner.py
@@ -35,6 +35,8 @@ class TextTestResult(result.TestResult):
     separator2 = '-' * 70
 
     def __init__(self, stream, descriptions, verbosity, *, durations=None):
+        """Construct a TextTestResult. Subclasses should accept **kwargs
+        to ensure compatibility as the interface changes."""
         super(TextTestResult, self).__init__(stream, descriptions, verbosity)
         self.stream = stream
         self.showAll = verbosity > 1

diff --git a/Misc/NEWS.d/next/Tests/2019-03-11-05-21-53.bpo-4080.6UVKY1.rst b/Misc/NEWS.d/next/Tests/2019-03-11-05-21-53.bpo-4080.6UVKY1.rst
@@ -0,0 +1,8 @@
+Added ``--durations`` command line option, showing the slowest test cases
+and the elapsed time of each individual test.
+:class:`unittest.TextTestRunner` and :class:`unittest.TextTestResult`
+constructors have a new *durations* keyword argument. Subclasses should take
+this into account or accept ``**kwargs``. Added
+:meth:`unittest.TestResult.addDuration` method and
+:attr:`unittest.TestResult.collectedDurations` attribute. (Contributed by
+Giampaolo Rodola in :issue:`4080`)