django-test-doctor 0.3.0

360° health check for Django projects — URLs, forms, admin, models, security, migrations in one command

django-test-doctor

360° health check for Django projects. One command, twelve layers of analysis, one verdict.

Installed as django-test-doctor, imported as django_doctor:

pip install django-test-doctor
./manage.py doctor

Why

./manage.py check validates runtime configuration. djlint validates template syntax. pytest validates whatever you remembered to test. Nothing validates the whole project at once.

Real-world bug that slipped into production despite unit tests:

class ContactPrincipalForm(forms.ModelForm):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # CRASH — Contact.fonction is a CharField (no choices)
        self.fields['fonction'].choices = [('', '---')] + list(self.fields['fonction'].choices)

The view using this form returned HTTP 500 in production. Any ./manage.py doctor run would have caught it, because the form check instantiates every ModelForm blank.

Layers

Layer	What it does	Status
system	Wraps ./manage.py check with rich output	✅ 0.1
urls	Crawls urlpatterns, probes every URL as anon/user/staff/superuser	✅ 0.1
forms	Instantiates every Form / ModelForm blank + with empty data	✅ 0.1
migrations	makemigrations --check --dry-run, detects missing migrations	✅ 0.1
admin	list_display / list_filter / search_fields fields actually exist	✅ 0.2
models	__str__ defined, Meta.ordering, FK on_delete=SET_NULL with null=False	✅ 0.2
security	check --deploy + forbidden SECRET_KEY substrings + DEBUG=True	✅ 0.2
templates	{% url %}, {% static %}, context vars vs get_context_data	🚧 0.3
views	Permission declared, LoginRequired, has a test (via coverage)	🚧 0.3
drf	Serializer ↔ model fields match, OpenAPI diff vs HEAD~1 for breaking	🚧 0.4
static	Every {% static "x" %} resolves to a file that exists	🚧 0.4
i18n	Untranslated msgid, stale .mo vs .po, missing _() wrapping	🚧 0.4

Quickstart

pip install django-test-doctor

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "django_doctor",
]

Then:

./manage.py doctor                       # full report
./manage.py doctor --section forms,urls  # target specific layers
./manage.py doctor --quick               # skip slow layers
./manage.py doctor --ci                  # exit 1 on critical/error
./manage.py doctor --html report.html    # browsable report
./manage.py doctor --diff origin/main    # only re-check what changed
./manage.py doctor --fix                 # auto-fix (run makemigrations, compilemessages)
./manage.py doctor --watch               # dev mode, re-run on save

Configuration

In your project's pyproject.toml:

[tool.django-doctor]
enabled = ["*"]
disabled = ["drf"]
fail_on = ["critical", "error"]
ignore = ["urls:admin:*", "forms:legacy_migrations.*"]

[tool.django-doctor.urls]
roles = ["anonymous", "staff"]
skip = ["admin:*"]
timeout = 10

Plugin API

Third-party checks plug in via the django_doctor.checks entry point:

[project.entry-points."django_doctor.checks"]
my_check = "my_package.checks:MyCheck"

# my_package/checks.py
# note: imports use django_doctor — the distribution is django-test-doctor
from django_doctor import Check, Finding, Severity

class MyCheck(Check):
    id = "my_check"
    description = "Verify my custom invariant"

    def run(self, project):
        for thing in project.iter_something():
            if not thing.ok:
                yield Finding(
                    severity=Severity.ERROR,
                    location=thing.file_path,
                    message=f"{thing!r} is broken",
                    fix_hint="Run ./manage.py fix_things",
                )

Status

Alpha — 0.2 ships seven layers (system / urls / forms / migrations / admin / models / security). Roadmap in CHANGELOG.md.

License

MIT © Paul Guindo