'djdt' is not a registered namespace #1405

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "esbonio.sphinx.confDir": ""
+}

Makefile

@@ -6,6 +6,9 @@ example:
 		--noinput --username="$(USER)" --email="$(USER)@mailinator.com"
 	python example/manage.py runserver
 
+example_test:
+	python example/manage.py test example
+
 test:
 	DJANGO_SETTINGS_MODULE=tests.settings \
 		python -m django test $${TEST_ARGS:-tests}

debug_toolbar/apps.py

@@ -3,7 +3,7 @@
 
 from django.apps import AppConfig
 from django.conf import settings
-from django.core.checks import Warning, register
+from django.core.checks import Error, Warning, register
 from django.middleware.gzip import GZipMiddleware
 from django.utils.module_loading import import_string
 from django.utils.translation import gettext_lazy as _
@@ -206,3 +206,25 @@ def js_mimetype_check(app_configs, **kwargs):
             )
         ]
     return []
+
+
+@register()
+def debug_toolbar_installed_when_running_tests_check(app_configs, **kwargs):
+    """
+    Check that the toolbar is not being used when tests are running
+    """
+    if not settings.DEBUG and dt_settings.get_config()["IS_RUNNING_TESTS"]:
+        return [
+            Error(
+                "The Django Debug Toolbar can't be used with tests",
+                hint="Django changes the DEBUG setting to False when running "
+                "tests. By default the Django Debug Toolbar is installed because "
+                "DEBUG is set to True. For most cases, you need to avoid installing "
+                "the toolbar when running tests. If you feel this check is in error, "
+                "you can set `DEBUG_TOOLBAR_CONFIG['IS_RUNNING_TESTS'] = False` to "
+                "bypass this check.",
+                id="debug_toolbar.W008",
+            )
+        ]
+    else:
+        return []

debug_toolbar/settings.py

@@ -1,3 +1,4 @@
+import sys
 import warnings
 from functools import lru_cache
 
@@ -42,6 +43,7 @@
     "SQL_WARNING_THRESHOLD": 500,  # milliseconds
     "OBSERVE_REQUEST_CALLBACK": "debug_toolbar.toolbar.observe_request",
     "TOOLBAR_LANGUAGE": None,
+    "IS_RUNNING_TESTS": "test" in sys.argv,
     "UPDATE_ON_FETCH": False,
 }
 

docs/Makefile

@@ -8,6 +8,7 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/changes.rst

@@ -29,6 +29,11 @@ Pending
   <https://astral.sh/blog/the-ruff-formatter>`__.
 * Changed the default position of the toolbar from top to the upper top
   position.
+* Added a link in the installation docs to a more complete installation
+  example in the example app.
+* Added check to prevent the toolbar from being installed when tests
+  are running.
+* Added test to example app and command to run the example app's tests.
 * Added the setting, ``UPDATE_ON_FETCH`` to control whether the
   toolbar automatically updates to the latest AJAX request or not.
   It defaults to ``False``.

docs/installation.rst

@@ -81,6 +81,11 @@ Add ``"debug_toolbar"`` to your ``INSTALLED_APPS`` setting:
         "debug_toolbar",
         # ...
     ]
+.. note:: Check  out the configuration example in the
+   `example app
+   <https://github.com/jazzband/django-debug-toolbar/tree/main/example>`_
+   to learn how to set up the toolbar to function smoothly while running
+   your tests.
 
 4. Add the URLs
 ^^^^^^^^^^^^^^^
@@ -99,6 +104,7 @@ Add django-debug-toolbar's URLs to your project's URLconf:
 This example uses the ``__debug__`` prefix, but you can use any prefix that
 doesn't clash with your application's URLs.
 
+
 5. Add the Middleware
 ^^^^^^^^^^^^^^^^^^^^^
 

example/settings.py

@@ -1,12 +1,14 @@
 """Django settings for example project."""
 
 import os
+import sys
 
 BASE_DIR = os.path.dirname(os.path.dirname(__file__))
 
 
 # Quick-start development settings - unsuitable for production
 
+
 SECRET_KEY = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
 
 DEBUG = True
@@ -22,11 +24,9 @@
     "django.contrib.sessions",
     "django.contrib.messages",
     "django.contrib.staticfiles",
-    "debug_toolbar",
 ]
 
 MIDDLEWARE = [
-    "debug_toolbar.middleware.DebugToolbarMiddleware",
     "django.middleware.security.SecurityMiddleware",
     "django.contrib.sessions.middleware.SessionMiddleware",
     "django.middleware.common.CommonMiddleware",
@@ -61,7 +61,6 @@
 
 WSGI_APPLICATION = "example.wsgi.application"
 
-DEBUG_TOOLBAR_CONFIG = {"ROOT_TAG_EXTRA_ATTRS": "data-turbo-permanent hx-preserve"}
 
 # Cache and database
 
@@ -97,3 +96,18 @@
     }
 
 STATICFILES_DIRS = [os.path.join(BASE_DIR, "example", "static")]
+
+
+# Only enable the toolbar when we're in debug mode and we're
+# not running tests. Django will change DEBUG to be False for
+# tests, so we can't rely on DEBUG alone.
+ENABLE_DEBUG_TOOLBAR = DEBUG and "test" not in sys.argv
+if ENABLE_DEBUG_TOOLBAR:
+    INSTALLED_APPS += [
+        "debug_toolbar",
+    ]
+    MIDDLEWARE += [
+        "debug_toolbar.middleware.DebugToolbarMiddleware",
+    ]
+    # Customize the config to support turbo and htmx boosting.
+    DEBUG_TOOLBAR_CONFIG = {"ROOT_TAG_EXTRA_ATTRS": "data-turbo-permanent hx-preserve"}

example/test_views.py

@@ -0,0 +1,12 @@
+# Add tests to example app to check how the toolbar is used
+# when running tests for a project.
+# See https://github.com/jazzband/django-debug-toolbar/issues/1405
+
+from django.test import TestCase
+from django.urls import reverse
+
+
+class ViewTestCase(TestCase):
+    def test_index(self):
+        response = self.client.get(reverse("home"))
+        assert response.status_code == 200

example/urls.py

@@ -1,3 +1,4 @@
+from django.conf import settings
 from django.contrib import admin
 from django.urls import include, path
 from django.views.generic import TemplateView
@@ -33,5 +34,9 @@
     ),
     path("admin/", admin.site.urls),
     path("ajax/increment", increment, name="ajax_increment"),
-    path("__debug__/", include("debug_toolbar.urls")),
 ]
+
+if settings.ENABLE_DEBUG_TOOLBAR:
+    urlpatterns += [
+        path("__debug__/", include("debug_toolbar.urls")),
+    ]

tests/settings.py

@@ -126,5 +126,6 @@
 
 DEBUG_TOOLBAR_CONFIG = {
     # Django's test client sets wsgi.multiprocess to True inappropriately
-    "RENDER_PANELS": False
+    "RENDER_PANELS": False,
+    "IS_RUNNING_TESTS": False,
 }

tests/test_checks.py

@@ -4,9 +4,12 @@
 
 import django
 from django.conf import settings
-from django.core.checks import Warning, run_checks
+from django.core.checks import Error, Warning, run_checks
 from django.test import SimpleTestCase, override_settings
 
+from debug_toolbar import settings as dt_settings
+from debug_toolbar.apps import debug_toolbar_installed_when_running_tests_check
+
 PATH_DOES_NOT_EXIST = os.path.join(settings.BASE_DIR, "tests", "invalid_static")
 
 
@@ -120,7 +123,17 @@ def test_panels_is_empty(self):
                     hint="Set DEBUG_TOOLBAR_PANELS to a non-empty list in your "
                     "settings.py.",
                     id="debug_toolbar.W005",
-                )
+                ),
+                Error(
+                    "The Django Debug Toolbar can't be used with tests",
+                    hint="Django changes the DEBUG setting to False when running "
+                    "tests. By default the Django Debug Toolbar is installed because "
+                    "DEBUG is set to True. For most cases, you need to avoid installing "
+                    "the toolbar when running tests. If you feel this check is in error, "
+                    "you can set `DEBUG_TOOLBAR_CONFIG['IS_RUNNING_TESTS'] = False` to "
+                    "bypass this check.",
+                    id="debug_toolbar.W008",
+                ),
             ],
         )
 
@@ -258,3 +271,68 @@ def test_check_w007_invalid(self, mocked_guess_type):
                 )
             ],
         )
+
+    # def test_debug_toolbar_installed_when_running_tests(self, mocked_get_config):
+    #     with self.settings(DEBUG=False):
+    #         dt_settings.get_config()["IS_RUNNING_TESTS"] = False
+    #         errors = debug_toolbar_installed_when_running_tests_check(None)
+    #         self.assertEqual(len(errors), 0)
+    #     with self.settings(DEBUG=True):
+    #         dt_settings.get_config()["IS_RUNNING_TESTS"] = True
+    #         errors = debug_toolbar_installed_when_running_tests_check(None)
+    #         self.assertEqual(len(errors), 0)
+    #     with self.settings(DEBUG=True):
+    #         dt_settings.get_config()["IS_RUNNING_TESTS"] = False
+    #         errors = debug_toolbar_installed_when_running_tests_check(None)
+    #         self.assertEqual(len(errors), 0)
+    #     with self.settings(DEBUG=False):
+    #         dt_settings.get_config()["IS_RUNNING_TESTS"] = True
+    #         errors = debug_toolbar_installed_when_running_tests_check(None)
+    #         self.assertEqual(
+    #             errors,
+    #             [
+    #                 Error(
+    #                     "The Django Debug Toolbar can't be used with tests",
+    #                     hint="Django changes the DEBUG setting to False when running "
+    #                     "tests. By default the Django Debug Toolbar is installed because "
+    #                     "DEBUG is set to True. For most cases, you need to avoid installing "
+    #                     "the toolbar when running tests. If you feel this check is in error, "
+    #                     "you can set `DEBUG_TOOLBAR_CONFIG['IS_RUNNING_TESTS'] = False` to "
+    #                     "bypass this check.",
+    #                     id="debug_toolbar.W008",
+    #                 )
+    #             ],
+
+    # )
+
+    def test_debug_toolbar_installed_when_running_tests(self):
+        with self.settings(DEBUG=False):
+            dt_settings.get_config()["IS_RUNNING_TESTS"] = False
+            errors = debug_toolbar_installed_when_running_tests_check(None)
+            self.assertEqual(len(errors), 0)
+        with self.settings(DEBUG=True):
+            dt_settings.get_config()["IS_RUNNING_TESTS"] = True
+            errors = debug_toolbar_installed_when_running_tests_check(None)
+            self.assertEqual(len(errors), 0)
+        with self.settings(DEBUG=True):
+            dt_settings.get_config()["IS_RUNNING_TESTS"] = False
+            errors = debug_toolbar_installed_when_running_tests_check(None)
+            self.assertEqual(len(errors), 0)
+        with self.settings(DEBUG=False):
+            dt_settings.get_config()["IS_RUNNING_TESTS"] = True
+            errors = debug_toolbar_installed_when_running_tests_check(None)
+            self.assertEqual(
+                errors,
+                [
+                    Error(
+                        "The Django Debug Toolbar can't be used with tests",
+                        hint="Django changes the DEBUG setting to False when running "
+                        "tests. By default the Django Debug Toolbar is installed because "
+                        "DEBUG is set to True. For most cases, you need to avoid installing "
+                        "the toolbar when running tests. If you feel this check is in error, "
+                        "you can set `DEBUG_TOOLBAR_CONFIG['IS_RUNNING_TESTS'] = False` to "
+                        "bypass this check.",
+                        id="debug_toolbar.W008",
+                    )
+                ],
+            )