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)