feat: add custom django testing client

Introduce `OpenAPIClient` that extends `rest_framework.test.APIClient`
with responses validation against OpenAPI schema by using `SchemaTester`.

Author: skarzi

README.md

@@ -192,6 +192,29 @@ 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
+
+`OpenAPIClient` extends Django REST framework
+[`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
+(TIP: add custom fixture if you are using `pytest` to avoid code boilerplate):
+
+```python
+schema_tester = SchemaTester()
+client = OpenAPIClient(schema_tester=schema_tester)
+response = client.get('/api/v1/tests/123/')
+```
+
+To enforce all developers working on the project to use `OpenAPIClient` simply
+override the `client` fixture (when using `pytest-django`) or provide custom
+test cases implementation (when using standard Django `unitest`-based approach)
+and then you will be sure 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,26 @@
+"""Subclass of ``APIClient`` using ``SchemaTester`` to validate responses."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rest_framework.test import APIClient
+
+if TYPE_CHECKING:
+    from rest_framework.response import Response
+
+    from .schema_tester import SchemaTester
+
+
+class OpenAPIClient(APIClient):
+    """``APIClient`` validating responses against OpenAPI schema."""
+
+    def __init__(self, *args, schema_tester: SchemaTester, **kwargs) -> None:
+        """Initialize ``OpenAPIClient`` instance."""
+        super().__init__(*args, **kwargs)
+        self.schema_tester = schema_tester
+
+    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

tests/test_clients.py

@@ -0,0 +1,75 @@
+import json
+
+import pytest
+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(schema_tester=SchemaTester())
+
+
+@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)