pytest-django-autocheck

Zero-config pytest plugin that runs generic safety checks on any Django project. .

Pulls in pytest-django automatically and discovers Django settings from your manage.py. Install and run:

pip install pytest-django-autocheck
pytest --autocheck

Why

Legacy or untested Django projects rarely have any safety net. This plugin catches the basics in CI before they reach production:

• modules that fail to import
• migrations that don't reverse, or are missing entirely
• models that can't be saved or stringified
• admin pages that return 500/404
• broken URLconfs
• public pages that return 500
• template syntax errors
• management commands that fail to load
• forms and serializers that can't be instantiated
• Django system check failures

Requirements

• Python 3.10+
• Django 5.0+

Installation

pip install pytest-django-autocheck

Usage

From your project root (where manage.py lives):

pytest --autocheck

The plugin discovers DJANGO_SETTINGS_MODULE from manage.py. If you already declare it explicitly (in pytest.ini/pyproject.toml, via --ds, or as an environment variable), that value wins and auto-discovery is skipped.

Run only specific checks by repeating --autocheck-only:

# a single check
pytest --autocheck --autocheck-only=admin

# multiple checks
pytest --autocheck --autocheck-only=admin --autocheck-only=models

Or skip specific checks with --autocheck-skip:

pytest --autocheck --autocheck-skip=templates --autocheck-skip=serializers

Both flags can be combined; --autocheck-skip is applied after --autocheck-only, so a check named in both ends up skipped.

Valid check names for both flags: admin, forms, imports, management_commands, migrations, models, serializers, system_checks, templates, urls, views.

Checks

Project-vs-third-party detection is filesystem based: an app is considered third-party when it lives under site-packages, the standard library or the environment prefix. A dependency installed in editable mode (pip install -e) lives outside those locations and is therefore inspected as project code; use the SKIP/CHECKS settings (or MODELS_EXCLUDE) if its findings are noise.

Settings

Every option is read from Django settings under the PYTEST_DJANGO_AUTOCHECK_ prefix, with a safe default: override only what you need.

The dynamic migration verification runs in a short-lived subprocess, isolated from the suite's own test database. If that subprocess can't set up its environment, the dynamic step is skipped with a warning rather than failing the run.

Instance generation

The models and admin checks need a valid instance of every model. The generator prefers the project's own factory_boy factories when present (looked up in <app>.factories or <app>.tests.factories): they already encode domain rules, which avoids false positives. Falls back to model_bakery when no factory is found. factory_boy is optional; discovery is a no-op if it's not installed.

When neither a factory nor generated data can satisfy a model's domain constraints, point PYTEST_DJANGO_AUTOCHECK_MODELS_FACTORIES at your own callable to keep the model checked, or, as a last resort, list it in PYTEST_DJANGO_AUTOCHECK_MODELS_EXCLUDE (see Settings) to exclude it from instance building.

The serializers check requires Django REST Framework and is skipped if it's not installed.

Custom checks

Third-party packages can ship their own checks through the pytest_django_autocheck.checks entry-point group. Each entry point must resolve to a check class (instantiated with no arguments) or a check instance exposing name, severity and run(app_configs) -> list[Finding]:

[project.entry-points."pytest_django_autocheck.checks"]
mycheck = "mypackage.checks:MyCheck"

Registered checks run like the built-in ones: they get their own pytest item, their name works with --autocheck-only/--autocheck-skip and the CHECKS/ SKIP settings, and their ERROR findings fail the run.

A check that never touches the database can declare requires_db = False: its pytest item then skips the database fixture, and running only such checks (like the built-in imports, migrations, templates and urls) never creates the test database.

Testing

# clone repository
git clone https://github.com/fabiocaccamo/pytest-django-autocheck.git && cd pytest-django-autocheck

# create virtualenv and activate it
python -m venv .venv && . .venv/bin/activate

# upgrade pip
python -m pip install --upgrade pip

# install package and test requirements
python -m pip install -e ".[test]"

# install pre-commit to run formatters and linters
pre-commit install --install-hooks

# run tests using tox
tox

# or run tests using pytest
coverage run -m pytest && coverage report -m

License

Released under MIT License.

Supporting

• :star: Star this project on GitHub
• :octocat: Follow me on GitHub
• :blue_heart: Follow me on Bluesky
• :moneybag: Sponsor me on Github

See also

• django-admin-interface - the default admin interface made customizable by the admin itself. popup windows replaced by modals. 🧙 ⚡

• django-cache-cleaner - clear the entire cache or individual caches easily using the admin panel or management command. 🧹✨

• django-colorfield - simple color field for models with a nice color-picker in the admin. 🎨

• django-email-validators - no more invalid or disposable emails in your database. ✉️ ✅

• django-extra-settings - config and manage typed extra settings using just the django admin. ⚙️

• django-maintenance-mode - shows a 503 error page when maintenance-mode is on. 🚧 🛠️

• django-redirects - redirects with full control. ↪️

• django-treenode - probably the best abstract model / admin for your tree based stuff. 🌳

• python-benedict - dict subclass with keylist/keypath support, I/O shortcuts (base64, csv, json, pickle, plist, query-string, toml, xml, yaml) and many utilities. 📘

• python-codicefiscale - encode/decode Italian fiscal codes - codifica/decodifica del Codice Fiscale. 🇮🇹 💳

• python-fontbro - friendly font operations. 🧢

• python-fsutil - file-system utilities for lazy devs. 🧟‍♂️