Django Coverage Plugin

3.2.2 · active · verified Mon Apr 13

django-coverage-plugin is a coverage.py plugin designed to measure test coverage of Django templates. It allows developers to see how much of their template code is exercised by their test suite, integrating template coverage reports alongside Python module coverage. The current version is 3.2.2 and it is actively maintained with regular releases to support new Python and Django versions.

Warnings

breaking Version 3.2.2 dropped support for Django 3.x and 4.x. Version 3.2.0 dropped support for Python 3.9 and Django 2.2. Version 3.1.1 dropped Python 3.8. Version 3.1.0 dropped Python 3.7 and Django 1.x. Version 3.0.0 dropped Python 2.7, 3.6, and Django 1.8. Ensure your Python and Django versions are compatible with the installed plugin version.
Fix: Upgrade your Python and Django environments to currently supported versions (Python 3.10-3.14, Django 5.2-6.0 for v3.2.2) or use an older plugin version compatible with your environment.
gotcha Django's template debugging must be enabled (`TEMPLATES.OPTIONS.debug = True`) in your settings file for the plugin to work correctly. If not enabled, template coverage will not be measured, or the plugin may raise a `DjangoTemplatePluginException`.
Fix: Set `TEMPLATES[0]['OPTIONS']['debug'] = True` in your Django settings.py.
gotcha The `DJANGO_SETTINGS_MODULE` environment variable must be set correctly, especially when running `coverage run` directly without `manage.py` properly bootstrapping the environment. Failure to set this can lead to `django.core.exceptions.ImproperlyConfigured` errors.
Fix: Ensure `DJANGO_SETTINGS_MODULE` is set, e.g., `os.environ['DJANGO_SETTINGS_MODULE'] = 'your_project.settings'` or by running via `manage.py test` as `coverage run manage.py test`.
gotcha In versions prior to 3.2.2, `{% endblock %}` lines (and similar tags) could be falsely reported as unexecuted if they appeared on their own indented line.
Fix: Upgrade to version 3.2.2 or newer to resolve this false reporting.
gotcha Files included by Django's `{% ssi %}` tag are not included in the coverage measurements by this plugin.
Fix: Be aware of this limitation; these files will not appear in your template coverage report.

Install

pip install django-coverage-plugin Install stable version

Imports

django_coverage_plugin
```
# In .coveragerc
[run]
plugins = django_coverage_plugin

# Or in pyproject.toml
[tool.coverage.run]
plugins = [
    'django_coverage_plugin',
]
```
The plugin is activated via configuration in .coveragerc or pyproject.toml, not through direct Python import of a class or function.

Quickstart

To quickly get started, install the plugin, configure your `coverage.py` settings (either in `.coveragerc` or `pyproject.toml`) to include `django_coverage_plugin` in the `plugins` list, and ensure Django's template debugging is enabled (`TEMPLATES.OPTIONS.debug: True`). You might also need to set the `DJANGO_SETTINGS_MODULE` environment variable. Then, run your Django tests using the `coverage run` command, followed by `coverage html` to generate an interactive HTML report that includes template coverage.

import os

# Assume a Django project structure like:
# myproject/
#   manage.py
#   myproject/
#     settings.py
#     ...
#   myapp/
#     templates/
#       myapp/my_template.html

# 1. Ensure Django settings are configured for template debugging
#    In myproject/settings.py:
#    TEMPLATES = [
#        {
#            'BACKEND': 'django.template.backends.django.DjangoTemplates',
#            'DIRS': [],
#            'APP_DIRS': True,
#            'OPTIONS': {
#                'context_processors': [
#                    'django.template.context_processors.debug',
#                    # ... other context processors
#                ],
#                'debug': True, # THIS IS CRUCIAL!
#            },
#        },
#    ]

# 2. Create or modify your .coveragerc or pyproject.toml
#    For .coveragerc:
#    [run]
#    plugins = django_coverage_plugin
#    source = .
#
#    For pyproject.toml:
#    [tool.coverage.run]
#    plugins = [
#        'django_coverage_plugin',
#    ]
#    source = ['.']

# 3. Set DJANGO_SETTINGS_MODULE environment variable (if not already set)
#    This is typically handled by manage.py, but explicit setting can avoid ImproperlyConfigured errors.
os.environ['DJANGO_SETTINGS_MODULE'] = os.environ.get('DJANGO_SETTINGS_MODULE', 'myproject.settings')

# 4. Run tests with coverage
#    Execute this command in your project's root directory (where manage.py is):
#    coverage run manage.py test
#
# 5. Generate a report (e.g., HTML)
#    coverage html
#    (This will create an 'htmlcov' directory with the report, including template coverage.)

print("Setup complete. Run 'coverage run manage.py test' then 'coverage html' from your project root.")
print(f"DJANGO_SETTINGS_MODULE is set to: {os.environ['DJANGO_SETTINGS_MODULE']}")

# Example of running tests with coverage (conceptually):
# import subprocess
# try:
#     subprocess.run(['coverage', 'run', 'manage.py', 'test'], check=True)
#     subprocess.run(['coverage', 'html'], check=True)
#     print("Coverage report generated in htmlcov/")
# except subprocess.CalledProcessError as e:
#     print(f"Error running coverage: {e}")

view raw JSON →