Add a section to the installation docs about running tests

matthiask · matthiask · commit 546e4b0080fb · 2024-05-27T10:37:12.000+02:00
Fixes django-commons#1920. 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.)
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -156,6 +156,30 @@ 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 = "argv" 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")),
+        ]
+
+
 Troubleshooting
 ---------------
 
