refactor(testing): deprecate testtools support in TestCase

docs/_newsfragments/2156.breakingchange.rst

@@ -0,0 +1,3 @@
+- **Deprecation**: Support for `testtools` in `falcon.testing` is now deprecated and will be removed in Falcon 5.0.
+  If `testtools` is selected automatically (i.e., without explicit configuration via `FALCON_BASE_TEST_CASE`), a deprecation warning will be issued.
+  Explicit configuration using `FALCON_BASE_TEST_CASE=testtools.TestCase` will not emit a warning.

falcon/testing/test_case.py

@@ -18,36 +18,79 @@
 utilities for simulating and validating HTTP requests.
 """
 
-try:
-    import testtools as unittest
-except ImportError:  # pragma: nocover
-    import unittest
+import os
+import unittest
+import warnings
 
 import falcon
 import falcon.request
-
-# TODO hoist for backwards compat. Remove in falcon 4.
 from falcon.testing.client import Result  # NOQA
 from falcon.testing.client import TestClient
 
+base_case = os.environ.get('FALCON_BASE_TEST_CASE')
+
+if base_case and 'testtools.TestCase' in base_case:
+    try:
+        import testtools
+
+        BaseTestCase = testtools.TestCase
+    except ImportError:
+        BaseTestCase = unittest.TestCase
+elif base_case is None:
+    try:
+        import testtools
+
+        warnings.warn(
+            'Support for testtools is deprecated and will be removed in Falcon 5.0.',
+            DeprecationWarning,
+        )
+        BaseTestCase = testtools.TestCase
+    except ImportError:
+        BaseTestCase = unittest.TestCase
+else:
+    BaseTestCase = unittest.TestCase
+
 
 class TestCase(unittest.TestCase, TestClient):
-    """Extends :mod:`unittest` to support WSGI/ASGI functional testing.
+    """Extends ``unittest`` to support WSGI/ASGI functional testing.
 
     Note:
-        If available, uses :mod:`testtools` in lieu of
-        :mod:`unittest`.
+        This class uses ``unittest`` by default, but you may use ``pytest``
+        to run ``unittest.TestCase`` instances, allowing a hybrid approach.
 
-    This base class provides some extra plumbing for unittest-style
-    test cases, to help simulate WSGI or ASGI requests without having
-    to spin up an actual web server. Various simulation methods are
-    derived from :class:`falcon.testing.TestClient`.
+    Recommended:
+        We recommend using **pytest** alongside **unittest** for testing.
+        See our tutorial on using pytest.
+
+    This base class provides extra functionality for unittest-style test cases,
+    helping simulate WSGI or ASGI requests without spinning up a web server. Various
+    simulation methods are derived from :class:`falcon.testing.TestClient`.
 
     Simply inherit from this class in your test case classes instead of
-    :class:`unittest.TestCase` or :class:`testtools.TestCase`.
+    ``unittest.TestCase``.
+
+    For example::
+
+        from falcon import testing
+        import myapp
+
+        class MyTestCase(testing.TestCase):
+            def setUp(self):
+                super(MyTestCase, self).setUp()
+
+                # Assume the hypothetical `myapp` package has a
+                # function called `create()` to initialize and
+                # return a `falcon.App` instance.
+                self.app = myapp.create()
+
+        class TestMyApp(MyTestCase):
+            def test_get_message(self):
+                doc = {'message': 'Hello world!'}
+
+                result = self.simulate_get('/messages/42')
+                self.assertEqual(result.json, doc)
     """
 
-    # NOTE(vytas): Here we have to restore __test__ to allow collecting tests!
     __test__ = True
 
     app: falcon.App
@@ -60,7 +103,6 @@
         from falcon import testing
         import myapp
 
-
         class MyTestCase(testing.TestCase):
             def setUp(self):
                 super(MyTestCase, self).setUp()
@@ -69,14 +111,6 @@
                 # function called `create()` to initialize and
                 # return a `falcon.App` instance.
                 self.app = myapp.create()
-
-
-        class TestMyApp(MyTestCase):
-            def test_get_message(self):
-                doc = {'message': 'Hello world!'}
-
-                result = self.simulate_get('/messages/42')
-                self.assertEqual(result.json, doc)
     """
 
     def setUp(self) -> None: