django-test-doctor

360° health check for Django projects. One command, fifteen layers of analysis, one verdict. Catches crashes your unit tests miss because they never exercise the blank-init / GET / POST / signal-save / {% url %} / permission-guard / auto-gen-parse / update_fields-consistency / fk-redundancy pathway an actual user hits first.

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. Doctor does.

Real-world bugs doctor caught in the past week:

• A form whose __init__ assigns to self.fields['fonction'].choices crashed with AttributeError on every GET because Contact.fonction is a plain CharField — 500 in production. Fixed by the forms check.
• A post_save signal on Mandat created a ConfigurationTVA without passing the NOT-NULL regime FK — IntegrityError on every mandat creation. Fixed by the post_smoke check.
• An OperationTVAForm.clean() that assigned cleaned_data["montant_ttc"] while montant_ttc wasn't in Meta.fields — Django silently dropped the value, NOT NULL violation at save. Fixed by the forms_meta check.

Every one of these passed ./manage.py check, passed its unit test suite, and still reached production.

Layers

Plus in 0.6: --html <path> (standalone HTML report suitable for CI artifacts), --diff <ref> (only show findings on files changed since a git ref — perfect for PR-scoped gating), and a URL-kwargs fixture generator that unlocks the urls and post_smoke checks on detail and edit routes (<int:pk>, <uuid:id>, <slug:slug>).

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,post_smoke   # target specific layers
./manage.py doctor --quick                      # skip slow layers
./manage.py doctor --ci                         # exit 1 on critical/error
./manage.py doctor --json                       # machine-readable output

Safety

post_smoke writes to the database (creates a transient superuser, submits forms) but always rolls back via transaction.atomic() + savepoint_rollback. Still, point it at a dev or CI database — never production.

Configuration

In your project's pyproject.toml:

[tool.django-doctor]
enabled = ["*"]
disabled = []                          # or ["post_smoke"] to skip slow layers
fail_on = ["critical", "error"]        # what --ci should bail on
ignore = ["urls:admin:*", "forms:legacy_migrations.*"]

[tool.django-doctor.urls]
roles = ["anonymous", "authenticated", "staff", "superuser"]
skip  = ["admin:*", "djdt:*", "rp-initiated-logout"]
timeout = 10

[tool.django-doctor.forms]
scenarios = ["blank", "empty_data"]

[tool.django-doctor.migrations]
skip_apps = []
include_third_party = false

[tool.django-doctor.post_smoke]
skip = ["legacy:*"]

[tool.django-doctor.security]
forbidden_secret_keys = ["django-insecure", "changeme", "secret"]

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
# Distribution is django-test-doctor, import path is django_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",
                )

Need auto-generated form fixtures in your own tests? The helper doctor uses internally is public:

from django_doctor.fixtures import make_form_fixture

data = make_form_fixture(MyModelForm)
client.post("/my-view/", data)

Status

Alpha — 0.10 ships fifteen layers + HTML reporter + --diff mode + URL-kwargs fixtures. Roadmap in CHANGELOG.md. Battle-tested against a production Django 6 / DRF / PostGIS / pgvector codebase with ~175 models, ~150 forms, 202 serializers, and 300+ URLs.

License

MIT © Paul Guindo