Testing¶

Built-in testing tools¶

Django has really good testing tools:

Just like Django itself, we provide several built-in utilities for testing.

These includes subclasses of django.test.RequestFactory for sync and async requests. Use them for faster and simpler unit-tests:

DMRRequestFactory for sync cases
DMRAsyncRequestFactory for async ones

We also have two subclasses of django.test.Client

DMRClient for sync cases
DMRAsyncClient for async ones

What is the difference between the default ones? Not much:

Default Content-Type header is set to application/json
It is now easier to change Content-Type header as simple as specifying headers={'Content-Type': 'application/xml'} to change the content type for XML (or any other) requests and responses
Our test clients are faster, because they use msgspec if it is available to dump and parse json, instead of a regular json

Testing styles support¶

We support both:

django.test.TestCase styled tests
And pytest-django styled tests

For pytest we also have a bundled plugin with several different fixtures:

dmr_pytest.py¶

[source]

from collections.abc import Iterator
from typing import TYPE_CHECKING

try:
    import pytest
except ImportError:  # pragma: no cover
    print(  # noqa: WPS421
        'Looks like `pytest` is not installed, please install it separately',
    )
    raise

if TYPE_CHECKING:
    # We can't import it directly, because it will ruin our coverage measures.
    from django.conf import LazySettings

    from dmr.test import (
        DMRAsyncClient,
        DMRAsyncRequestFactory,
        DMRClient,
        DMRRequestFactory,
    )


@pytest.fixture
def dmr_client(request: pytest.FixtureRequest) -> 'DMRClient':
    """Customized version of :class:`django.test.Client`."""
    from dmr.internal.test import maybe_track_client
    from dmr.test import DMRClient

    client = DMRClient()
    maybe_track_client(request, client)
    return client


@pytest.fixture
def dmr_async_client(request: pytest.FixtureRequest) -> 'DMRAsyncClient':
    """Customized version of :class:`django.test.AsyncClient`."""
    from dmr.internal.test import maybe_track_client
    from dmr.test import DMRAsyncClient

    client = DMRAsyncClient()
    maybe_track_client(request, client)
    return client


@pytest.fixture
def dmr_rf() -> 'DMRRequestFactory':
    """Customized version of :class:`django.test.RequestFactory`."""
    from dmr.test import DMRRequestFactory

    return DMRRequestFactory()


@pytest.fixture
def dmr_async_rf() -> 'DMRAsyncRequestFactory':
    """Customized version of :class:`django.test.AsyncRequestFactory`."""
    from dmr.test import DMRAsyncRequestFactory

    return DMRAsyncRequestFactory()


@pytest.fixture
def dmr_clean_settings() -> Iterator[None]:
    """Cleans settings caches before and after the test."""
    from dmr.settings import clear_settings_cache

    clear_settings_cache()
    yield
    clear_settings_cache()


@pytest.fixture
def settings(
    settings: 'LazySettings',
    dmr_clean_settings: None,
) -> 'LazySettings':
    """Customized version of :func:`pytest_django.fixtures.settings`."""
    return settings

No need to configure anything, just use these fixtures by names in your tests.

You can use plain Django test primitives:

django_builtin_client.py¶

[source]

import json
from http import HTTPStatus

from django.test import TestCase
from django.test.utils import override_settings
from django.urls import path

from examples.testing.pydantic_controller import UserController

urlpatterns = [
    path('users/', UserController.as_view(), name='users'),
]


@override_settings(ROOT_URLCONF=__name__)
class TestDjangoBuiltinClient(TestCase):
    def test_post_user(self) -> None:
        payload = {'email': 'user@example.com', 'age': 20}

        response = self.client.post(
            '/users/',
            data=json.dumps(payload),
            content_type='application/json',
        )

        assert response.status_code == HTTPStatus.CREATED
        response_data = json.loads(response.content)
        assert response_data['email'] == payload['email']
        assert response_data['age'] == payload['age']
        assert isinstance(response_data['uid'], str)

Or use dmr.test helpers when you want JSON defaults and controller-level testing with request factories:

dmr_helpers.py¶

[source]

import json
from http import HTTPStatus

from dirty_equals import IsUUID
from django.http import HttpResponse
from django.test import TestCase
from django.test.utils import override_settings
from django.urls import path
from typing_extensions import override

from dmr.test import DMRClient, DMRRequestFactory
from examples.testing.pydantic_controller import UserController

urlpatterns = [
    path('users/', UserController.as_view(), name='users'),
]


@override_settings(ROOT_URLCONF=__name__)
class TestDMRHelpers(TestCase):
    @override
    def setUp(self) -> None:
        self.client = DMRClient()

    def test_dmr_client_post_json_by_default(self) -> None:
        payload = {'email': 'user@example.com', 'age': 20}

        response = self.client.post('/users/', data=payload)

        assert isinstance(response, HttpResponse)
        assert response.status_code == HTTPStatus.CREATED
        assert json.loads(response.content) == {
            'uid': IsUUID,
            **payload,
        }

    def test_dmr_request_factory_with_controller(self) -> None:
        dmr_rf = DMRRequestFactory()
        payload = {'email': 'user@example.com', 'age': 20}

        request = dmr_rf.post('/users/', data=payload)
        response = UserController.as_view()(request)

        assert isinstance(response, HttpResponse)
        assert request.content_type == 'application/json'
        assert response.status_code == HTTPStatus.CREATED
        assert json.loads(response.content) == {
            'uid': IsUUID,
            **payload,
        }

Structured data generation¶

Since django-modern-rest is already built around an idea that we use models for everything, it is quite natural to reuse these models for tests as well.

For example, one can use Polyfactory to build test data from pydantic, msgspec, @dataclass, or even TypedDict models.

Let’s say you have this code for your controller, using pydantic models:

views.py¶

[source]

import uuid

import pydantic

from dmr import Body, Controller
from dmr.plugins.pydantic import PydanticSerializer


class UserCreateModel(pydantic.BaseModel):
    email: str
    age: int


class UserModel(UserCreateModel):
    uid: uuid.UUID


class UserController(Controller[PydanticSerializer]):
    def post(self, parsed_body: Body[UserCreateModel]) -> UserModel:
        return UserModel(
            uid=uuid.uuid4(),
            age=parsed_body.age,
            email=parsed_body.email,
        )

Let’s reuse the models for data generation in tests!

test_user_create.py¶

[source]

import json
from http import HTTPStatus

from dirty_equals import IsUUID
from django.http import HttpResponse
from polyfactory.factories.pydantic_factory import ModelFactory

from dmr.test import DMRRequestFactory
from examples.testing.pydantic_controller import UserController, UserCreateModel


class UserCreateModelFactory(ModelFactory[UserCreateModel]):
    """Will create structured random request data for you."""

    __check_model__ = True


def test_create_user(dmr_rf: DMRRequestFactory) -> None:
    # This will return random `UserCreatedModel` instances:
    request_data = UserCreateModelFactory.build().model_dump(mode='json')

    request = dmr_rf.post('/url/', data=request_data)

    response = UserController.as_view()(request)

    assert isinstance(response, HttpResponse)
    assert response.status_code == HTTPStatus.CREATED
    assert response.headers == {'Content-Type': 'application/json'}
    assert json.loads(response.content) == {
        'uid': IsUUID,
        **request_data,
    }

Which will make your tests simple, fast, and will help you find unexpected corner cases.

Property-based API testing¶

There’s a great tool called schemathesis that can be used to test your API to match your OpenAPI spec.

Official docs: https://schemathesis.readthedocs.io

schemathesis is not bundled together with the django-modern-rest. You have to install it with:

uv add --group dev schemathesis

poetry add --group dev schemathesis

pip install schemathesis

Now, let’s see how you can generate thousands of tests for your API with just several lines of python code:

tests/test_integration/test_openapi/test_schema.py¶

[source]

import logging
import os
from collections.abc import Iterator
from http import HTTPStatus
from http.cookies import SimpleCookie
from typing import TYPE_CHECKING, Final

import pytest
import schemathesis as st
from django.conf import LazySettings
from django.contrib.auth.models import User
from django.urls import reverse
from hypothesis import settings as h_settings
from hypothesis import strategies
from schemathesis.specs.openapi.schemas import OpenApiSchema

from django_test_app.server.wsgi import application
from dmr.test import DMRClient
from dmr.validation import ResponseValidator

_LOCAL_MAX_EXAMPLES: Final = 25
_MAX_EXAMPLES: Final = 100 if os.environ.get('CI') else _LOCAL_MAX_EXAMPLES

if TYPE_CHECKING:
    import tracecov


@pytest.fixture(autouse=True)
def _patch_response_validation(monkeypatch: pytest.MonkeyPatch) -> None:
    # Patches the response validator class to never validate the responses,
    # despite their settings. This is needed to test schematesis's
    # response schema validation and compatibility between two. Not ours schema.
    # https://github.com/wemake-services/django-modern-rest/issues/776
    monkeypatch.setattr(
        ResponseValidator,
        '_should_validate_responses',
        lambda *args, **kwargs: False,
    )


@pytest.fixture(autouse=True)
def _disable_logging(settings: LazySettings) -> Iterator[None]:
    # Logging has too much output with schemathesis:
    logging.disable(logging.CRITICAL)
    yield
    logging.disable(logging.NOTSET)


@pytest.fixture(autouse=True)
def _modify_integration_settings(settings: LazySettings) -> None:
    # Schemathesis tests only run meaningfully with DEBUG=False (the test
    # explicitly skips when DEBUG=True), so there is no value in running
    # the full suite twice via the parent conftest parametrisation.
    settings.DEBUG = False


# The `transactional_db` fixture is required to enable database access.
# When `st.openapi.from_wsgi()` makes a WSGI request, Django's request
# lifecycle triggers database operations.
# The `admin_user` fixture is required here so that auth can use
# its credentials (username and password) for authentication.
# This follows the `pytest-django` pattern for creating user fixtures:
# https://github.com/pytest-dev/pytest-django/blob/main/pytest_django/fixtures.py#L483
@pytest.fixture
def api_schema(transactional_db: None, admin_user: User) -> OpenApiSchema:
    """Load OpenAPI schema as a pytest fixture."""
    return st.openapi.from_wsgi(reverse('openapi_json'), application)


schema = st.pytest.from_fixture('api_schema')

# Register custom strategies:
st.openapi.format(
    'phone',
    strategies.from_regex(r'^\+7-495-[0-9]{3}-[0-9]{2}-[0-9]{2}$'),
)

# Register custom auth:


@st.auth().apply_to(st.openapi.require_security_scheme('django_session'))
class _DjangoSessionAuth:
    def get(
        self,
        case: st.Case,
        ctx: st.AuthContext,
    ) -> SimpleCookie:
        dmr_client = DMRClient()
        response = dmr_client.post(
            reverse('api:django_session_auth:django_session_sync'),
            # Username and password are taken from `admin_user` fixture,
            # which is defined in `pytest-django`:
            data={'username': 'admin', 'password': 'password'},
        )
        assert response.status_code == HTTPStatus.OK, response.content
        return response.cookies

    def set(
        self,
        case: st.Case,
        data: SimpleCookie,
        ctx: st.AuthContext,
    ) -> None:
        # Set to the case itself:
        case.cookies.update({
            cookie_name: cookie.coded_value
            for cookie_name, cookie in data.items()
        })
        assert case.cookies, ctx


@schema.parametrize()
@h_settings(max_examples=_MAX_EXAMPLES)
def test_schemathesis(
    tracecov_map: 'tracecov.CoverageMap | None',
    *,
    case: st.Case,
) -> 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

    response = case.call_and_validate()
    # 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?

schemathesis loads OpenAPI schema definition from the reverse('openapi') URL
Then we will create a top level schema object from the api_schema pytest fixture. It is needed to create a property-based test case
Lastly, we create a generated test case with the help of @schema.parametrize()

You can also provide settings, like the number of generated tests, enabled rules, auth, etc:

schemathesis.toml¶

[source]

[warnings]
# Fail on any warning:
fail-on = true

[auth.openapi.http_basic]
# Our own credentials from
# django_test_app/server/apps/controllers/auth.py
username = 'test'
password = 'pass'

[auth.dynamic.openapi.jwt]
path = '/api/jwt-auth/jwt-obtain-access-refresh-sync/'
# These are default user credentials from
# https://github.com/pytest-dev/pytest-django
payload = { username = 'admin', password = 'password' }
extract_selector = '/access_token'

[output.sanitization]
# We don't have any real data to hide, but it is easier to debug:
enabled = false

When running the test case with

pytest tests/test_integration/test_openapi/test_schema.py

it will cover all your API. In simple cases it might be enough tests. Yes, you heard right: in simple cases just using schemathesis can remove the need to write any other integration tests.

Important

Using schemathesis with django-modern-rest is very easy, because we offer state-of-the-art OpenAPI schema generation. It will be really hard to satisfy schemathesis with a different framework.

Validating responses¶

schemathesis can also be used in regular tests to validate the response schema. See https://schemathesis.readthedocs.io/en/stable/guides/schema-conformance/

Example:

from dmr.test import DMRClient

def test_with_conditional_logic(dmr_client: DMRClient) -> None:
    response = dmr_client.post(
       '/users',
       data={'name': 'Alice'},
   )

   assert schema['/users']['POST'].is_valid_response(response.json())

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 add --group dev tracecov

poetry add --group dev tracecov

pip install 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]

from typing import TYPE_CHECKING

import pytest
from django.conf import LazySettings

from dmr.settings import Settings

if TYPE_CHECKING:
    import tracecov


@pytest.fixture(scope='session')
def tracecov_map() -> 'tracecov.CoverageMap | None':

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]

if TYPE_CHECKING:
    import tracecov


@pytest.fixture(autouse=True)
def _patch_response_validation(monkeypatch: pytest.MonkeyPatch) -> None:
    # Patches the response validator class to never validate the responses,
    # despite their settings. This is needed to test schematesis's
    # response schema validation and compatibility between two. Not ours schema.
    # https://github.com/wemake-services/django-modern-rest/issues/776
    monkeypatch.setattr(
        ResponseValidator,
        '_should_validate_responses',
        lambda *args, **kwargs: False,
    )


@pytest.fixture(autouse=True)
def _disable_logging(settings: LazySettings) -> Iterator[None]:
    # Logging has too much output with schemathesis:
    logging.disable(logging.CRITICAL)

What will happen here?

schemathesis executes requests generated from your OpenAPI schema.
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.
Independently from schemathesis, any requests performed through dmr_client or dmr_async_client are tracked automatically when tracecov_map is active.
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.