Merge pull request #262 from skarzi/issue-261

feat: Add custom django testing client

Author: sondrelg

README.md

@@ -63,9 +63,10 @@ def test_response_documentation(client):
 If you are using the Django testing framework, you can create a base APITestCase that incorporates schema validation:
 
 ```python
-from openapi_tester.schema_tester import SchemaTester
-from rest_framework.test import APITestCase
 from rest_framework.response import Response
+from rest_framework.test import APITestCase
+
+from openapi_tester.schema_tester import SchemaTester
 
 schema_tester = SchemaTester()
 
@@ -189,6 +190,68 @@ When the SchemaTester loads a schema, it runs it through
 specification compliance issues. In case of issues with the schema itself, the validator will raise the appropriate
 error.
 
+## Django testing client
+
+The library includes an `OpenAPIClient`, which extends Django REST framework's
+[`APIClient` class](https://www.django-rest-framework.org/api-guide/testing/#apiclient).
+If you wish to validate each response against OpenAPI schema when writing
+unit tests - `OpenAPIClient` is what you need!
+
+To use `OpenAPIClient` simply pass `SchemaTester` instance that should be used
+to validate responses and then use it like regular Django testing client:
+
+```python
+schema_tester = SchemaTester()
+client = OpenAPIClient(schema_tester=schema_tester)
+response = client.get('/api/v1/tests/123/')
+```
+
+To force all developers working on the project to use `OpenAPIClient` simply
+override the `client` fixture (when using `pytest` with `pytest-django`):
+
+```python
+from pytest_django.lazy_django import skip_if_no_django
+
+from openapi_tester.schema_tester import SchemaTester
+
+
+@pytest.fixture
+def schema_tester():
+    return SchemaTester()
+
+
+@pytest.fixture
+def client(schema_tester):
+    skip_if_no_django()
+
+    from openapi_tester.clients import OpenAPIClient
+
+    return OpenAPIClient(schema_tester=schema_tester)
+```
+
+If you are using plain Django test framework, we suggest to create custom
+test case implementation and use it instead of original Django one:
+
+```python
+import functools
+
+from django.test.testcases import SimpleTestCase
+from openapi_tester.clients import OpenAPIClient
+from openapi_tester.schema_tester import SchemaTester
+
+schema_tester = SchemaTester()
+
+
+class MySimpleTestCase(SimpleTestCase):
+    client_class = OpenAPIClient
+    # or use `functools.partial` when you want to provide custom
+    # ``SchemaTester`` instance:
+    # client_class = functools.partial(OpenAPIClient, schema_tester=schema_tester)
+```
+
+This will ensure you all newly implemented views will be validated against
+the OpenAPI schema.
+
 ## Known Issues
 
 * We are using [prance](https://github.com/jfinkhaeuser/prance) as a schema resolver, and it has some issues with the

openapi_tester/__init__.py

@@ -1,16 +1,18 @@
 """ DRF OpenAPI Schema Tester """
 from .case_testers import is_camel_case, is_kebab_case, is_pascal_case, is_snake_case
+from .clients import OpenAPIClient
 from .loaders import BaseSchemaLoader, DrfSpectacularSchemaLoader, DrfYasgSchemaLoader, StaticSchemaLoader
 from .schema_tester import SchemaTester
 
 __all__ = [
-    "is_camel_case",
-    "is_kebab_case",
-    "is_pascal_case",
-    "is_snake_case",
     "BaseSchemaLoader",
     "DrfSpectacularSchemaLoader",
     "DrfYasgSchemaLoader",
-    "StaticSchemaLoader",
     "SchemaTester",
+    "StaticSchemaLoader",
+    "is_camel_case",
+    "is_kebab_case",
+    "is_pascal_case",
+    "is_snake_case",
+    "OpenAPIClient",
 ]

openapi_tester/clients.py

@@ -0,0 +1,36 @@
+"""Subclass of ``APIClient`` using ``SchemaTester`` to validate responses."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rest_framework.test import APIClient
+
+from .schema_tester import SchemaTester
+
+if TYPE_CHECKING:
+    from rest_framework.response import Response
+
+
+class OpenAPIClient(APIClient):
+    """``APIClient`` validating responses against OpenAPI schema."""
+
+    def __init__(
+        self,
+        *args,
+        schema_tester: SchemaTester | None = None,
+        **kwargs,
+    ) -> None:
+        """Initialize ``OpenAPIClient`` instance."""
+        super().__init__(*args, **kwargs)
+        self.schema_tester = schema_tester or self._schema_tester_factory()
+
+    def request(self, **kwargs) -> Response:  # type: ignore[override]
+        """Validate fetched response against given OpenAPI schema."""
+        response = super().request(**kwargs)
+        self.schema_tester.validate_response(response)
+        return response
+
+    @staticmethod
+    def _schema_tester_factory() -> SchemaTester:
+        """Factory of default ``SchemaTester`` instances."""
+        return SchemaTester()

tests/test_clients.py

@@ -0,0 +1,107 @@
+import functools
+import json
+
+import pytest
+from django.test.testcases import SimpleTestCase
+from rest_framework import status
+
+from openapi_tester.clients import OpenAPIClient
+from openapi_tester.exceptions import UndocumentedSchemaSectionError
+from openapi_tester.schema_tester import SchemaTester
+
+
+@pytest.fixture()
+def openapi_client(settings) -> OpenAPIClient:
+    """Sample ``OpenAPIClient`` instance to use in tests."""
+    # use `drf-yasg` schema loader in tests
+    settings.INSTALLED_APPS = [app for app in settings.INSTALLED_APPS if app != "drf_spectacular"]
+    return OpenAPIClient()
+
+
+def test_init_schema_tester_passed():
+    """Ensure passed ``SchemaTester`` instance is used."""
+    schema_tester = SchemaTester()
+
+    client = OpenAPIClient(schema_tester=schema_tester)
+
+    assert client.schema_tester is schema_tester
+
+
+@pytest.mark.parametrize(
+    ("generic_kwargs", "expected_status_code"),
+    [
+        (
+            {"method": "GET", "path": "/api/v1/cars/correct"},
+            status.HTTP_200_OK,
+        ),
+        (
+            {
+                "method": "POST",
+                "path": "/api/v1/vehicles",
+                "data": json.dumps({"vehicle_type": "suv"}),
+                "content_type": "application/json",
+            },
+            status.HTTP_201_CREATED,
+        ),
+    ],
+)
+def test_request(openapi_client, generic_kwargs, expected_status_code):
+    """Ensure ``SchemaTester`` doesn't raise exception when response valid."""
+    response = openapi_client.generic(**generic_kwargs)
+
+    assert response.status_code == expected_status_code
+
+
+@pytest.mark.parametrize(
+    ("generic_kwargs", "raises_kwargs"),
+    [
+        (
+            {
+                "method": "POST",
+                "path": "/api/v1/vehicles",
+                "data": json.dumps({"vehicle_type": ("1" * 50)}),
+                "content_type": "application/json",
+            },
+            {
+                "expected_exception": UndocumentedSchemaSectionError,
+                "match": "Undocumented status code: 400",
+            },
+        ),
+        (
+            {"method": "PUT", "path": "/api/v1/animals"},
+            {
+                "expected_exception": UndocumentedSchemaSectionError,
+                "match": "Undocumented method: put",
+            },
+        ),
+    ],
+)
+def test_request_invalid_response(
+    openapi_client,
+    generic_kwargs,
+    raises_kwargs,
+):
+    """Ensure ``SchemaTester`` raises an exception when response is invalid."""
+    with pytest.raises(**raises_kwargs):  # noqa: PT010
+        openapi_client.generic(**generic_kwargs)
+
+
+@pytest.mark.parametrize(
+    "openapi_client_class",
+    [
+        OpenAPIClient,
+        functools.partial(OpenAPIClient, schema_tester=SchemaTester()),
+    ],
+)
+def test_django_testcase_client_class(openapi_client_class):
+    """Ensure example from README.md about Django test case works fine."""
+
+    class DummyTestCase(SimpleTestCase):
+        """Django ``TestCase`` with ``OpenAPIClient`` client."""
+
+        client_class = openapi_client_class
+
+    test_case = DummyTestCase()
+    test_case._pre_setup()
+
+    assert isinstance(test_case.client, OpenAPIClient)