API coverage with TraceCov

TraceCov can be used as an optional API coverage layer for django-modern-rest test suites. It complements regular integration tests and schemathesis runs by showing which OpenAPI operations and parameters were actually exercised.

Official docs: https://docs.tracecov.sh/

Note

TraceCov is not bundled with the django-modern-rest. You have to install it.

uv poetry pip

uv add --group dev tracecov

Why is this better than regular coverage?

Most coverage tools measure which lines and branches of your implementation were executed. TraceCov instead measures coverage of your API contract: which OpenAPI operations, parameters, and response variants were exercised.

This matters because “missing contract coverage” often turns into real bugs: edge cases for parameters, incorrect status codes, or response variants that your tests never actually reach. With django-modern-rest the OpenAPI schema is built from the project’s semantic schema (derived from response validation). That makes TraceCov coverage tightly aligned with what your implementation claims to support.

Configuration

How is that wired with django-modern-rest?

• tracecov_map enables tracking for the whole test run.

• When tracecov_map is active, any test that uses dmr_client or dmr_async_client is automatically included in the TraceCov report.

• If you also run schemathesis, the schemathesis test records which validated requests and responses correspond to which OpenAPI operation, so the report can connect execution back to the spec.

To enable tracking, define a session-scoped tracecov_map fixture. When tracecov_map is configured and TraceCov is installed, dmr_client and dmr_async_client automatically register requests in tracecov.

conftest.py

[source]

def tracecov_map() -> 'tracecov.CoverageMap | None':
    """Provide the session ``tracecov`` coverage map for tests."""
    try:
        import tracecov  # noqa: PLC0415
    except ImportError:  # pragma: no cover
        return None

    from django_test_app.server.urls import schema  # noqa: PLC0415

    return tracecov.CoverageMap.from_dict(schema.convert())

To enable TraceCov recording for schemathesis runs, make sure your schemathesis test explicitly records validated interactions into tracecov_map via record_schemathesis_interactions(...).

test_schema.py

[source]

@schema.parametrize()
@h_settings(max_examples=_MAX_EXAMPLES)
@pytest.mark.timeout(0)
def test_schemathesis(
    tracecov_map: 'tracecov.CoverageMap | None',
    *,
    case: st.Case[Any],
) -> None:
    """Ensure that API implementation matches the OpenAPI schema."""
    if tracecov_map is None:  # pragma: no cover
        pytest.skip(reason='missing `tracecov`')

    from tracecov.schemathesis import helpers  # noqa: PLC0415

    # `werkzeug` leaves `REMOTE_ADDR` out of the WSGI environ entirely,
    # while every real server sets it. Code that looks up the client IP
    # then behaves differently under test than in production: for example
    # `django-allauth` rate limiting answers `403` when it cannot find one.
    response = case.call_and_validate(
        environ_base={'REMOTE_ADDR': '127.0.0.1'},
    )
    # Record interaction for `tracecov` report:
    tracecov_map.record_schemathesis_interactions(
        case.method,
        case.operation.full_path,
        [helpers.from_response(case.method, response)],
    )

What will happen here?

1. schemathesis executes requests generated from your OpenAPI schema.

2. After each schemathesis request is validated, the integration calls record_schemathesis_interactions(...) to record which OpenAPI operation and parameters were exercised for that verified response.

3. Independently from schemathesis, any requests performed through dmr_client or dmr_async_client are tracked automatically when tracecov_map is active.

4. TraceCov aggregates coverage across operations, parameters, keywords, and response coverage.

Tip

If TraceCov is not installed, or when tracecov_map is missing or inactive, fixtures return regular DMR clients without tracking.

When running your tests:

pytest tests/test_integration/test_openapi/test_schema.py

TraceCov generates a report in various formats. See TraceCov docs for details on the generated coverage report.

In short: run schemathesis and regular integration tests together and get one unified TraceCov view of what your test suite actually exercised.