django-test-doctor 0.5.0

360° health check for Django projects — URLs, forms (blank + POST smoke + orphan cleaned_data), admin, models, security, migrations, DRF serializers — one command

django-test-doctor

360° health check for Django projects. One command, ten layers of analysis, one verdict. Catches crashes your unit tests miss because they never exercise the blank-init / GET / POST / signal-save 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

Layer	What it does	Status
system	Wraps Django's built-in check framework	✅ 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	Byte-for-byte parity with makemigrations --check --dry-run	✅ 0.1
admin	list_display / list_filter / search_fields / ordering exist on the model	✅ 0.2
models	__str__ defined, Meta.ordering, no SET_NULL on NOT NULL FK	✅ 0.2
security	check --deploy + weak SECRET_KEY + DEBUG=True + empty ALLOWED_HOSTS	✅ 0.2
drf	Serializer init + Meta.fields ↔ Meta.model coherence	✅ 0.3
post_smoke	POST every CreateView / UpdateView with auto fixture, fail on 5xx	✅ 0.4
forms_meta	cleaned_data[x] = … where x is NOT NULL but not in Meta.fields	✅ 0.5
templates	{% url %}, {% static %}, context vars vs get_context_data	🚧 0.6
views	Permission declared, LoginRequired, has a test (via coverage)	🚧 0.6
static	Every {% static "x" %} resolves to a file that exists	🚧 0.7
i18n	Untranslated msgid, stale .mo vs .po, missing _() wrapping	🚧 0.7

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.5 ships ten layers. 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