Add a section to the installation docs about running tests (django-co…

…mmons#1921)

I thought about including the relevant documentation in the earlier
steps, but I'd have to explain DEBUG, INTERNAL_IPS and TESTING all at
once instead of introducing everything step by step. So even though it
may be annoying to go back and modify code the user just added it still
reads better to me, especially since it only applies to users running
tests in their project. (I would hope a lot of them do, but still.)

docs/changes.rst

@@ -6,6 +6,8 @@ Pending
 
 * Removed some CSS which wasn't carefully limited to the toolbar's elements.
 * Stopped assuming that ``INTERNAL_IPS`` is a list.
+* Added a section to the installation docs about running tests in projects
+  where the toolbar is being used.
 
 
 4.4.1 (2024-05-26)

docs/configuration.rst

@@ -72,6 +72,8 @@ Toolbar options
   The toolbar searches for this string in the HTML and inserts itself just
   before.
 
+.. _IS_RUNNING_TESTS:
+
 * ``IS_RUNNING_TESTS``
 
   Default: ``"test" in sys.argv``

docs/installation.rst

@@ -156,6 +156,39 @@ option.
     able to get the toolbar to work with your docker installation, review
     the code in ``debug_toolbar.middleware.show_toolbar``.
 
+7. Disable the toolbar when running tests (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you're running tests in your project you shouldn't activate the toolbar. You
+can do this by adding another setting:
+
+.. code-block:: python
+
+    TESTING = "test" in sys.argv
+
+    if not TESTING:
+        INSTALLED_APPS = [
+            *INSTALLED_APPS,
+            "debug_toolbar",
+        ]
+        MIDDLEWARE = [
+            "debug_toolbar.middleware.DebugToolbarMiddleware",
+            *MIDDLEWARE,
+        ]
+
+You should also modify your URLconf file:
+
+.. code-block:: python
+
+    if not settings.TESTING:
+        urlpatterns = [
+            *urlpatterns,
+            path("__debug__/", include("debug_toolbar.urls")),
+        ]
+
+Alternatively, you can check out the :ref:`IS_RUNNING_TESTS <IS_RUNNING_TESTS>`
+option.
+
 Troubleshooting
 ---------------