.. _testing:

Testing
=======

Overview
--------

When it comes to testing, DSG follows the same conventions as `Django <https://docs.djangoproject.com/en/5.0/topics/testing/>`_
and `DRF <https://www.django-rest-framework.org/api-guide/testing/>`_.
It use the `unittest <https://docs.python.org/3/library/unittest.html>`_ library,
a built-in Python module for testing. This allows for the creation of robust and comprehensive unit tests,
ensuring the reliability and stability of the codebase.

To enable unit test of your gRPC services, DSG provides a **mock gRPC server** that allows you to test your services
as if they were being handled by a real gRPC server, **replacing the networking calls by function calls**.

The following sections will guide you through the process of writing and running tests for DSG.

Writing Tests
-------------

Let's imagine a dummy service for a model Post

  .. code-block:: python

    # quickstrart/services.py
    from django_filters.rest_framework import DjangoFilterBackend
    from django_socio_grpc.generics import AsyncModelService

    from quickstart.models import Post
    from quickstart.serializer import PostProtoSerializer

    # AsyncModelService implements basic crud functionnalities
    class PostService(AsyncModelService):
        queryset = Post.objects.all()
        serializer_class = PostProtoSerializer
        filter_backends = [DjangoFilterBackend]
        filterset_fields = ["headline"]


The following is a basic structure for your testing class:

  .. code-block:: python

    # quickstart/tests.py
    from django.test import TestCase
    from .post.services.post_service import PostService
    from .post.grpc import post_pb2
    from .post.grpc.post_pb2_grpc import (
        PostControllerStub,
        add_PostControllerServicer_to_server,
    )
    from .grpc_test_utils.fake_grpc import FakeFullAIOGRPC

    class TestPost(TestCase):
        def setup(self):
            self.fake_grpc = FakeFullAIOGRPC(
                add_PostControllerServicer_to_server,
                PostService.as_servicer(),
            )

Now, let's dissect the ``TestPost`` class:

- We recommend using ``TestCase`` from ``django.test`` for testing your service.
- The ``setup`` method should instantiate a ``FakeFullAIOGRPC``.
- ``FakeFullAIOGRPC`` is initialized with two parameters:

  - ``add_PostControllerServicer_to_server``: This function is **automatically generated by gRPC**. It's responsible for **adding a servicer to a gRPC server**. In this case, it's used to add the ``PostService`` servicer to the server.

  - ``Servicer``: This is the actual **service that handles the RPCs**. In this context, ``PostService`` is the servicer. It contains the logic for handling the client's requests.

  - For a deeper understanding of services and the process of initiating a real server, consult the `gRPC Python Basics documentation <https://grpc.io/docs/languages/python/basics/#starting-the-server>`_.

- When you create an instance of ``FakeFullAIOGRPC``, it sets up a **mock gRPC server with your servicer**. This allows you to make calls to your servicer methods **as if they were being handled by a real gRPC server**.


.. warning::
  The ``fake_grpc.py`` file provides two classes: ``FakeAIOGRPC`` and ``FakeFullAIOGRPC``, both of which inherit from the ``fakeRPC`` base class. However, it's important to note that both ``FakeGRPC`` and ``FakeAIOGRPC`` are now deprecated. For asynchronous contexts, we strongly recommend using ``FakeFullAIOGRC``, as it is specifically designed and optimized for such use cases.


Testing common functionnalities:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here are some important test files in the DSG project:

- `Actions <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_actions.py>`_: Contains tests for the action functionality.

- `Basic async service <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_async_basic_service.py>`_: Test the basic asynchronous service.

- `Async exception <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_async_exception.py>`_: Contains tests for handling exceptions in asynchronous services.

- `Basic mixin <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_basic_mixins.py>`_: Test the basic mixins used in the project.

- `Filtering <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_filtering.py>`_: Contains tests for the filtering functionality.

- `Pagination <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_pagination.py>`_: Test the pagination functionality.

- `Permissions <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_permissions.py>`_: Contains tests for the permissions functionality.

- `Placeholders <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_placeholders.py>`_: Test the placeholder functionality.

- `Auth <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_authentication.py>`_: Contains tests for the authentication functionality.

- `Auth without session middleware <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_auth_without_session_middleware.py>`_: Test the authentication functionality without using session middleware.

- `Async stream <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_async_stream_in.py>`_: Test the asynchronous streaming functionality.

- `Local middleware <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_locale_middleware.py>`_: Test the locale middleware.

- `Legacy django middleware <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_legacy_django_middlewares.py>`_: Test the legacy Django middleware.

- `Proto generation <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_proto_generation.py>`_: Test the protobuf generation functionality.

- `Protobuf registration <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_protobuf_registration.py>`_: Test the registration of protobufs.

- `App handler registration <https://github.com/socotecio/django-socio-grpc/blob/master/django_socio_grpc/tests/test_app_handler_registry.py>`_: Test the registration of app handlers.


Running Tests
-------------

To run tests on your application, it is advised to install ``pytest`` and ``pytest-django``. The installation instructions can be found in the `pytest-django tutorial <https://pytest-django.readthedocs.io/en/latest/tutorial.html>`_.

Verify your installation by checking the ``pytest`` version:

.. code-block:: bash

  pytest --version

Create a test file named ``quickstart/tests.py``. Follow the instructions provided earlier in this document for guidance on how to structure your first test.

Run your tests with the following command:

.. code-block:: bash

  pytest

For more details on ``pytest`` and ``unittest``, refer to the `pytest documentation <https://pytest-django.readthedocs.io/en/latest/>`_ and `unittest documentation <https://docs.python.org/3/library/unittest.html>`_ respectively.