pytest-jinja-check

A pytest plugin that lints Jinja2 templates used in FastAPI applications. Catches common issues at test time:

1. Syntax validation — templates parse without errors
2. Hardcoded route detection — href="/foo" should be url_for('foo')
3. Endpoint validation — url_for('endpoint') references actually exist in your app
4. Context variable checking — routes pass all variables their templates need

Installation

pip install pytest-jinja-check

Or with uv:

uv add pytest-jinja-check

For endpoint validation against a live FastAPI app, install with the fastapi extra:

pip install "pytest-jinja-check[fastapi]"
# or
uv add "pytest-jinja-check[fastapi]"

Quick start

The plugin auto-registers with pytest via entry points. Add configuration to your pyproject.toml:

[tool.pytest-jinja-check]
template_dir = "templates"
python_dir = "app"
auto_check = true
app = "app.main:app"  # optional — enables url_for() endpoint validation

With auto_check = true, all lint checks run at session start — no boilerplate tests required:

pytest

If lint issues are found, pytest exits before your tests run with a single aggregated report.

You can also enable checks for one run without changing config:

pytest --jinja-check

Use --no-jinja-check to skip checks when auto_check is enabled in config.

Manual checks with fixtures

If you prefer explicit tests or need to validate against a specific app instance, use the provided fixtures:

# tests/test_templates.py

def test_template_syntax(template_syntax_errors):
    assert not template_syntax_errors, "\n".join(str(e) for e in template_syntax_errors)

def test_no_hardcoded_routes(hardcoded_routes):
    assert not hardcoded_routes, "\n".join(str(e) for e in hardcoded_routes)

def test_context_variables(missing_context_variables):
    assert not missing_context_variables, "\n".join(
        str(e) for e in missing_context_variables
    )

def test_url_for_endpoints(validate_endpoints):
    from myapp.main import app
    errors = validate_endpoints(app)
    assert not errors, "\n".join(str(e) for e in errors)

Fixtures

All analysis fixtures are session-scoped (run once per test session).

Configuration

All settings in [tool.pytest-jinja-check] in your pyproject.toml:

You can also pass pytest CLI options:

Programmatic API

The analysis functions can also be used outside of pytest:

from pytest_jinja_check import (
    analyze_all_templates,
    check_syntax,
    check_hardcoded_routes,
    check_context_variables,
    validate_url_for_references,
    extract_all_route_contexts,
    run_all_checks,
    load_config,
)
from pathlib import Path

# Run all checks in one call (same as auto-check mode)
config = load_config(Path("."))
errors = run_all_checks(config)

# Or run checks individually
# Analyze templates
templates = analyze_all_templates(Path("templates"))
for name, info in templates.items():
    print(f"{name}: needs {info.variables}")

# Find issues
syntax_errors = check_syntax(Path("templates"))
hardcoded = check_hardcoded_routes(Path("templates"))
routes = extract_all_route_contexts(Path("app"))
missing = check_context_variables(Path("templates"), routes)

How it works

• Template analysis uses jinja2.meta.find_undeclared_variables() on parsed ASTs, recursively resolving {% extends %} to capture inherited variable requirements.
• Route analysis uses Python's ast module to find TemplateResponse(...) calls and extract template names and context dict keys. Handles both the old positional API and newer keyword API.
• Endpoint validation introspects a live FastAPI app.routes to get registered endpoint names.

Known limitations

• Template variables from dynamic {% extends variable %} can't be resolved.
• Context dicts built outside the TemplateResponse(...) call (e.g., ctx = {...}; TemplateResponse("t.html", ctx)) are flagged as dynamic and skipped rather than producing false positives.
• The variable union from template inheritance may over-report when a child block completely replaces a parent block that used a variable.

License

MIT