Fixed #34210 -- Added unittest's durations option to the test runner.

8 files changed, 110 insertions, 5 deletions

diff --git a/django/test/runner.py b/django/test/runner.py
index fc14efee11..3a30674b61 100644
--- a/django/test/runner.py
+++ b/django/test/runner.py
@@ -29,6 +29,7 @@ from django.test.utils import setup_test_environment
 from django.test.utils import teardown_databases as _teardown_databases
 from django.test.utils import teardown_test_environment
 from django.utils.datastructures import OrderedSet
+from django.utils.version import PY312
 
 try:
     import ipdb as pdb
@@ -285,6 +286,10 @@ failure and get a correct traceback.
         super().stopTest(test)
         self.events.append(("stopTest", self.test_index))
 
+    def addDuration(self, test, elapsed):
+        super().addDuration(test, elapsed)
+        self.events.append(("addDuration", self.test_index, elapsed))
+
     def addError(self, test, err):
         self.check_picklable(test, err)
         self.events.append(("addError", self.test_index, err))
@@ -655,6 +660,7 @@ class DiscoverRunner:
         timing=False,
         shuffle=False,
         logger=None,
+        durations=None,
         **kwargs,
     ):
         self.pattern = pattern
@@ -692,6 +698,7 @@ class DiscoverRunner:
         self.shuffle = shuffle
         self._shuffler = None
         self.logger = logger
+        self.durations = durations
 
     @classmethod
     def add_arguments(cls, parser):
@@ -791,6 +798,15 @@ class DiscoverRunner:
                 "unittest -k option."
             ),
         )
+        if PY312:
+            parser.add_argument(
+                "--durations",
+                dest="durations",
+                type=int,
+                default=None,
+                metavar="N",
+                help="Show the N slowest test cases (N=0 for all).",
+            )
 
     @property
     def shuffle_seed(self):
@@ -953,12 +969,15 @@ class DiscoverRunner:
             return PDBDebugResult
 
     def get_test_runner_kwargs(self):
-        return {
+        kwargs = {
             "failfast": self.failfast,
             "resultclass": self.get_resultclass(),
             "verbosity": self.verbosity,
             "buffer": self.buffer,
         }
+        if PY312:
+            kwargs["durations"] = self.durations
+        return kwargs
 
     def run_checks(self, databases):
         # Checks are run after database creation since some checks require
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index cc448055f4..c3349f364b 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -1559,6 +1559,16 @@ tests, which allows it to print a traceback if the interpreter crashes. Pass
 
 Outputs timings, including database setup and total run time.
 
+.. django-admin-option:: --durations N
+
+.. versionadded:: 5.0
+
+Shows the N slowest test cases (N=0 for all).
+
+.. admonition:: Python 3.12 and later
+
+    This feature is only available for Python 3.12 and later.
+
 ``testserver``
 --------------
 
diff --git a/docs/releases/5.0.txt b/docs/releases/5.0.txt
index 28814f141f..fcb8091545 100644
--- a/docs/releases/5.0.txt
+++ b/docs/releases/5.0.txt
@@ -476,6 +476,9 @@ Tests
 
 * :class:`~django.test.AsyncClient` now supports the ``follow`` parameter.
 
+* The new :option:`test --durations` option allows showing the duration of the
+  slowest tests on Python 3.12+.
+
 URLs
 ~~~~
 
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index 14a45931ba..54b9d7d133 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -533,7 +533,7 @@ behavior. This class defines the ``run_tests()`` entry point, plus a
 selection of other methods that are used by ``run_tests()`` to set up, execute
 and tear down the test suite.
 
-.. class:: DiscoverRunner(pattern='test*.py', top_level=None, verbosity=1, interactive=True, failfast=False, keepdb=False, reverse=False, debug_mode=False, debug_sql=False, parallel=0, tags=None, exclude_tags=None, test_name_patterns=None, pdb=False, buffer=False, enable_faulthandler=True, timing=True, shuffle=False, logger=None, **kwargs)
+.. class:: DiscoverRunner(pattern='test*.py', top_level=None, verbosity=1, interactive=True, failfast=False, keepdb=False, reverse=False, debug_mode=False, debug_sql=False, parallel=0, tags=None, exclude_tags=None, test_name_patterns=None, pdb=False, buffer=False, enable_faulthandler=True, timing=True, shuffle=False, logger=None, durations=None, **kwargs)
 
     ``DiscoverRunner`` will search for tests in any file matching ``pattern``.
 
@@ -613,6 +613,10 @@ and tear down the test suite.
     the console. The logger object will respect its logging level rather than
     the ``verbosity``.
 
+    ``durations`` will show a list of the N slowest test cases. Setting this
+    option to ``0`` will result in the duration for all tests being shown.
+    Requires Python 3.12+.
+
     Django may, from time to time, extend the capabilities of the test runner
     by adding new arguments. The ``**kwargs`` declaration allows for this
     expansion. If you subclass ``DiscoverRunner`` or write your own test
@@ -623,6 +627,10 @@ and tear down the test suite.
     custom arguments by calling ``parser.add_argument()`` inside the method, so
     that the :djadmin:`test` command will be able to use those arguments.
 
+    .. versionadded:: 5.0
+
+        The ``durations`` argument was added.
+
 Attributes
 ~~~~~~~~~~
 
diff --git a/tests/runtests.py b/tests/runtests.py
index a3550c553c..543344854c 100755
--- a/tests/runtests.py
+++ b/tests/runtests.py
@@ -33,6 +33,7 @@ else:
         RemovedInDjango60Warning,
     )
     from django.utils.log import DEFAULT_LOGGING
+    from django.utils.version import PY312
 
 try:
     import MySQLdb
@@ -380,6 +381,7 @@ def django_tests(
     buffer,
     timing,
     shuffle,
+    durations=None,
 ):
     if parallel in {0, "auto"}:
         max_parallel = get_max_test_processes()
@@ -425,6 +427,7 @@ def django_tests(
         buffer=buffer,
         timing=timing,
         shuffle=shuffle,
+        durations=durations,
     )
     failures = test_runner.run_tests(test_labels)
     teardown_run_tests(state)
@@ -688,6 +691,15 @@ if __name__ == "__main__":
             "Same as unittest -k option. Can be used multiple times."
         ),
     )
+    if PY312:
+        parser.add_argument(
+            "--durations",
+            dest="durations",
+            type=int,
+            default=None,
+            metavar="N",
+            help="Show the N slowest test cases (N=0 for all).",
+        )
 
     options = parser.parse_args()
 
@@ -785,6 +797,7 @@ if __name__ == "__main__":
                 options.buffer,
                 options.timing,
                 options.shuffle,
+                getattr(options, "durations", None),
             )
         time_keeper.print_results()
         if failures:
diff --git a/tests/test_runner/test_discover_runner.py b/tests/test_runner/test_discover_runner.py
index bca9037492..5fc35b7bf2 100644
--- a/tests/test_runner/test_discover_runner.py
+++ b/tests/test_runner/test_discover_runner.py
@@ -16,6 +16,7 @@ from django.test.utils import (
     captured_stderr,
     captured_stdout,
 )
+from django.utils.version import PY312
 
 
 @contextmanager
@@ -765,6 +766,22 @@ class DiscoverRunnerTests(SimpleTestCase):
                 failures = runner.suite_result(suite, result)
                 self.assertEqual(failures, expected_failures)
 
+    @unittest.skipUnless(PY312, "unittest --durations option requires Python 3.12")
+    def test_durations(self):
+        with captured_stderr() as stderr, captured_stdout():
+            runner = DiscoverRunner(durations=10)
+            suite = runner.build_suite(["test_runner_apps.simple.tests.SimpleCase1"])
+            runner.run_suite(suite)
+        self.assertIn("Slowest test durations", stderr.getvalue())
+
+    @unittest.skipUnless(PY312, "unittest --durations option requires Python 3.12")
+    def test_durations_debug_sql(self):
+        with captured_stderr() as stderr, captured_stdout():
+            runner = DiscoverRunner(durations=10, debug_sql=True)
+            suite = runner.build_suite(["test_runner_apps.simple.SimpleCase1"])
+            runner.run_suite(suite)
+        self.assertIn("Slowest test durations", stderr.getvalue())
+
 
 class DiscoverRunnerGetDatabasesTests(SimpleTestCase):
     runner = DiscoverRunner(verbosity=2)
diff --git a/tests/test_runner/test_parallel.py b/tests/test_runner/test_parallel.py
index eea9e4de74..e83f53bf4e 100644
--- a/tests/test_runner/test_parallel.py
+++ b/tests/test_runner/test_parallel.py
@@ -4,7 +4,7 @@ import unittest
 
 from django.test import SimpleTestCase
 from django.test.runner import RemoteTestResult
-from django.utils.version import PY311
+from django.utils.version import PY311, PY312
 
 try:
     import tblib.pickling_support
@@ -118,7 +118,11 @@ class RemoteTestResultTest(SimpleTestCase):
         subtest_test.run(result=result)
 
         events = result.events
-        self.assertEqual(len(events), 4)
+        # addDurations added in Python 3.12.
+        if PY312:
+            self.assertEqual(len(events), 5)
+        else:
+            self.assertEqual(len(events), 4)
         self.assertIs(result.wasSuccessful(), False)
 
         event = events[1]
@@ -133,3 +137,9 @@ class RemoteTestResultTest(SimpleTestCase):
 
         event = events[2]
         self.assertEqual(repr(event[3][1]), "AssertionError('2 != 1')")
+
+    @unittest.skipUnless(PY312, "unittest --durations option requires Python 3.12")
+    def test_add_duration(self):
+        result = RemoteTestResult()
+        result.addDuration(None, 2.3)
+        self.assertEqual(result.collectedDurations, [("None", 2.3)])
diff --git a/tests/test_runner/tests.py b/tests/test_runner/tests.py
index 0643bf93a1..25b7f40e99 100644
--- a/tests/test_runner/tests.py
+++ b/tests/test_runner/tests.py
@@ -14,7 +14,7 @@ from django import db
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
 from django.core.management import call_command
-from django.core.management.base import SystemCheckError
+from django.core.management.base import CommandError, SystemCheckError
 from django.test import SimpleTestCase, TransactionTestCase, skipUnlessDBFeature
 from django.test.runner import (
     DiscoverRunner,
@@ -31,6 +31,7 @@ from django.test.utils import (
     get_unique_databases_and_mirrors,
     iter_test_cases,
 )
+from django.utils.version import PY312
 
 from .models import B, Person, Through
 
@@ -451,6 +452,8 @@ class MockTestRunner:
     def __init__(self, *args, **kwargs):
         if parallel := kwargs.get("parallel"):
             sys.stderr.write(f"parallel={parallel}")
+        if durations := kwargs.get("durations"):
+            sys.stderr.write(f"durations={durations}")
 
 
 MockTestRunner.run_tests = mock.Mock(return_value=[])
@@ -475,6 +478,28 @@ class ManageCommandTests(unittest.TestCase):
             )
         self.assertIn("Total run took", stderr.getvalue())
 
+    @unittest.skipUnless(PY312, "unittest --durations option requires Python 3.12")
+    def test_durations(self):
+        with captured_stderr() as stderr:
+            call_command(
+                "test",
+                "--durations=10",
+                "sites",
+                testrunner="test_runner.tests.MockTestRunner",
+            )
+        self.assertIn("durations=10", stderr.getvalue())
+
+    @unittest.skipIf(PY312, "unittest --durations option requires Python 3.12")
+    def test_durations_lt_py312(self):
+        msg = "Error: unrecognized arguments: --durations=10"
+        with self.assertRaises(CommandError, msg=msg):
+            call_command(
+                "test",
+                "--durations=10",
+                "sites",
+                testrunner="test_runner.tests.MockTestRunner",
+            )
+
 
 # Isolate from the real environment.
 @mock.patch.dict(os.environ, {}, clear=True)