refactor(testing): deprecate testtools support in TestCase

Remove conditional dependency on testtools in TestCase to simplify maintenance and prepare for
Falcon 5.0 where testtools will no longer be supported. Instead, unittest is now the default,
and users are encouraged to use pytest for testing Falcon applications. This change emits a
deprecation warning if testtools is still enabled via environment variables.

Closes falconry#2156

falcon/testing/test_case.py

@@ -18,15 +18,25 @@
 utilities for simulating and validating HTTP requests.
 """
 
-try:
-    import testtools as unittest
-except ImportError:  # pragma: nocover
-    import unittest
+import os
+import unittest
+import warnings
+
+if 'DISABLE_TESTTOOLS' not in os.environ:
+    try:
+        import testtools
+
+        warnings.warn(
+            'Support for testtools is deprecated and will be removed in Falcon 5.0. '
+            'Please migrate to unittest or pytest.',
+            DeprecationWarning,
+        )
+        BaseTestCase = testtools.TestCase
+    except ImportError:  # pragma: nocover
+        BaseTestCase = unittest.TestCase
 
 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
 
@@ -35,16 +45,45 @@ class TestCase(unittest.TestCase, TestClient):
     """Extends :mod:`unittest` to support WSGI/ASGI functional testing.
 
     Note:
-        If available, uses :mod:`testtools` in lieu of
-        :mod:`unittest`.
+        This class uses :mod:`unittest` by default. If :mod:`testtools`
+        is available and the environment variable
+        ``DISABLE_TESTTOOLS`` is **not** set, it will use :mod:`testtools` instead.
+        **Support for testtools is deprecated and will be removed in Falcon 5.0.**
+
+    Recommended:
+        We recommend using **pytest** for testing Falcon applications.
+        See our tutorial on using pytest.
 
     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`.
 
     Simply inherit from this class in your test case classes instead of
-    :class:`unittest.TestCase` or :class:`testtools.TestCase`.
+    :class:`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!
@@ -69,14 +108,6 @@ def setUp(self):
                 # 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: