Fixed #32655 -- Deprecated extra_tests argument for DiscoverRunner.build_suite()/run_tests().

6 files changed, 72 insertions, 12 deletions

diff --git a/django/test/runner.py b/django/test/runner.py
index 3846b3be01..b6cd1ad487 100644
--- a/django/test/runner.py
+++ b/django/test/runner.py
@@ -11,6 +11,7 @@ import random
 import sys
 import textwrap
 import unittest
+import warnings
 from collections import defaultdict
 from contextlib import contextmanager
 from importlib import import_module
@@ -25,6 +26,7 @@ from django.test.utils import (
     teardown_databases as _teardown_databases, teardown_test_environment,
 )
 from django.utils.datastructures import OrderedSet
+from django.utils.deprecation import RemovedInDjango50Warning
 
 try:
     import ipdb as pdb
@@ -727,6 +729,12 @@ class DiscoverRunner:
         return tests
 
     def build_suite(self, test_labels=None, extra_tests=None, **kwargs):
+        if extra_tests is not None:
+            warnings.warn(
+                'The extra_tests argument is deprecated.',
+                RemovedInDjango50Warning,
+                stacklevel=2,
+            )
         test_labels = test_labels or ['.']
         extra_tests = extra_tests or []
 
@@ -866,11 +874,14 @@ class DiscoverRunner:
         Test labels should be dotted Python paths to test modules, test
         classes, or test methods.
 
-        A list of 'extra' tests may also be provided; these tests
-        will be added to the test suite.
-
         Return the number of tests that failed.
         """
+        if extra_tests is not None:
+            warnings.warn(
+                'The extra_tests argument is deprecated.',
+                RemovedInDjango50Warning,
+                stacklevel=2,
+            )
         self.setup_test_environment()
         suite = self.build_suite(test_labels, extra_tests)
         databases = self.get_databases(suite)
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 69a21109f3..c56b875aed 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -27,6 +27,9 @@ details on these changes.
 * The default sitemap protocol for sitemaps built outside the context of a
   request will change from ``'http'`` to ``'https'``.
 
+* The ``extra_tests`` argument for ``DiscoverRunner.build_suite()`` and
+  ``DiscoverRunner.run_tests()`` will be removed.
+
 .. _deprecation-removed-in-4.1:
 
 4.1
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index ee3922c9b6..9f63a3d3ed 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -533,6 +533,9 @@ Miscellaneous
 * The default sitemap protocol for sitemaps built outside the context of a
   request will change from ``'http'`` to ``'https'`` in Django 5.0.
 
+* The ``extra_tests`` argument for :meth:`.DiscoverRunner.build_suite` and
+  :meth:`.DiscoverRunner.run_tests` is deprecated.
+
 Features removed in 4.0
 =======================
 
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index dcc1be7f44..f94da75ece 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -631,7 +631,7 @@ Attributes
 Methods
 ~~~~~~~
 
-.. method:: DiscoverRunner.run_tests(test_labels, extra_tests=None, **kwargs)
+.. method:: DiscoverRunner.run_tests(test_labels, **kwargs)
 
     Run the test suite.
 
@@ -639,9 +639,11 @@ Methods
     several formats (see :meth:`DiscoverRunner.build_suite` for a list of
     supported formats).
 
-    ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
-    suite that is executed by the test runner. These extra tests are run
-    in addition to those discovered in the modules listed in ``test_labels``.
+    .. deprecated:: 4.0
+
+        ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
+        suite that is executed by the test runner. These extra tests are run in
+        addition to those discovered in the modules listed in ``test_labels``.
 
     This method should return the number of tests that failed.
 
@@ -658,7 +660,7 @@ Methods
     :func:`~django.test.utils.setup_test_environment` and setting
     :setting:`DEBUG` to ``self.debug_mode`` (defaults to ``False``).
 
-.. method:: DiscoverRunner.build_suite(test_labels=None, extra_tests=None, **kwargs)
+.. method:: DiscoverRunner.build_suite(test_labels=None, **kwargs)
 
     Constructs a test suite that matches the test labels provided.
 
@@ -678,9 +680,11 @@ Methods
     tests in all files below the current directory whose names match its
     ``pattern`` (see above).
 
-    ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
-    suite that is executed by the test runner. These extra tests are run
-    in addition to those discovered in the modules listed in ``test_labels``.
+    .. deprecated:: 4.0
+
+        ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
+        suite that is executed by the test runner. These extra tests are run in
+        addition to those discovered in the modules listed in ``test_labels``.
 
     Returns a ``TestSuite`` instance ready to be run.
 
diff --git a/tests/test_runner/runner.py b/tests/test_runner/runner.py
index a2c9ede897..46660d690b 100644
--- a/tests/test_runner/runner.py
+++ b/tests/test_runner/runner.py
@@ -16,5 +16,5 @@ class CustomOptionsTestRunner(DiscoverRunner):
         parser.add_argument('--option_b', '-b', default='2'),
         parser.add_argument('--option_c', '-c', default='3'),
 
-    def run_tests(self, test_labels, extra_tests=None, **kwargs):
+    def run_tests(self, test_labels, **kwargs):
         print("%s:%s:%s" % (self.option_a, self.option_b, self.option_c))
diff --git a/tests/test_runner/tests.py b/tests/test_runner/tests.py
index 3a535f3e1e..6916331e78 100644
--- a/tests/test_runner/tests.py
+++ b/tests/test_runner/tests.py
@@ -734,3 +734,42 @@ class RunTestsExceptionHandlingTests(unittest.TestCase):
                     runner.run_tests(['test_runner_apps.sample.tests_sample.TestDjangoTestCase'])
             self.assertTrue(teardown_databases.called)
             self.assertFalse(teardown_test_environment.called)
+
+
+# RemovedInDjango50Warning
+class NoOpTestRunner(DiscoverRunner):
+    def setup_test_environment(self, **kwargs):
+        return
+
+    def setup_databases(self, **kwargs):
+        return
+
+    def run_checks(self, databases):
+        return
+
+    def teardown_databases(self, old_config, **kwargs):
+        return
+
+    def teardown_test_environment(self, **kwargs):
+        return
+
+
+class DiscoverRunnerExtraTestsDeprecationTests(SimpleTestCase):
+    msg = 'The extra_tests argument is deprecated.'
+
+    def get_runner(self):
+        return NoOpTestRunner(verbosity=0, interactive=False)
+
+    def test_extra_tests_build_suite(self):
+        runner = self.get_runner()
+        with self.assertWarnsMessage(RemovedInDjango50Warning, self.msg):
+            runner.build_suite(extra_tests=[])
+
+    def test_extra_tests_run_tests(self):
+        runner = self.get_runner()
+        with captured_stderr():
+            with self.assertWarnsMessage(RemovedInDjango50Warning, self.msg):
+                runner.run_tests(
+                    test_labels=['test_runner_apps.sample.tests_sample.EmptyTestCase'],
+                    extra_tests=[],
+                )