Added testing docs

Author: eadwinCode

docs/basics/testing.md

@@ -13,14 +13,14 @@ These features include:
 
 Ellar is compatible with `unittest` and `pytest` testing frameworks in python but in this documentation, we will be using `pytest`.
 
-## Getting started
+## **Getting started**
 You will need to install `pytest`
 
 ```shell
 pip install pytest
 ```
 
-## Unit testing
+## **Unit testing**
 In the following example, we test two classes: `CarController` and `CarRepository`. For this we need to use `TestClientFactory` to build
 them in isolation from the application since we are writing unit test.
 
@@ -29,8 +29,6 @@ We are going to be writing unit test for `CarController` in there.
 
 ```python
 # project_name/car/tests/test_controllers.py
-from unittest.mock import patch
-
 from project_name.apps.car.controllers import CarController
 from project_name.apps.car.schemas import CreateCarSerializer, CarListFilter
 from project_name.apps.car.services import CarRepository
@@ -52,6 +50,45 @@ class TestCarController:
             "name": "Mercedes",
             "year": 2022,
         }
+```
+In example above, we aren't really testing anything Ellar-specific. Notice that we are not using dependency injection; rather, 
+we pass an instance of `CarController` to our `CarRepository`. 
+This type of testing, where we manually instantiate the classes being tested, is commonly referred to as **isolated testing** because it is framework-independent
+
+## **Using Test Factory**
+**Test** factory function in `ellar.testing` package, is a great tool employ for a quick and better test setup. 
+Let's rewrite the previous example using the built-in `Test` class:
+
+```python
+# project_name/car/tests/test_controllers.py
+from unittest.mock import patch
+from ellar.di import ProviderConfig
+from ellar.testing import Test
+from project_name.apps.car.controllers import CarController
+from project_name.apps.car.schemas import CreateCarSerializer, CarListFilter
+from project_name.apps.car.services import CarRepository
+
+
+class TestCarController:
+    def setup(self):
+        test_module = Test.create_test_module(
+            controllers=[CarController,], 
+            providers=[ProviderConfig(CarRepository, use_class=CarRepository)]
+        )
+        self.controller: CarController = test_module.get(CarController)
+
+    async def test_create_action(self, anyio_backend):
+        result = await self.controller.create(
+            CreateCarSerializer(name="Mercedes", year=2022, model="CLS")
+        )
+
+        assert result == {
+            "id": "1",
+            "message": "This action adds a new car",
+            "model": "CLS",
+            "name": "Mercedes",
+            "year": 2022,
+        }
 
     @patch.object(CarRepository, 'get_all', return_value=[dict(id=2, model='CLS',name='Mercedes', year=2023)])
     async def test_get_all_action(self, mock_get_all, anyio_backend):
@@ -69,9 +106,253 @@ class TestCarController:
             'message': 'This action returns all cars at limit=10, offset=0'
         }
 ```
-In example above, we aren't really testing anything Ellar-specific. Notice that we are not using dependency injection; rather, 
-we pass an instance of `CarController` to our `CarRepository`. This type of testing, where we manually instantiate the classes being tested, is commonly referred to as **isolated testing** because it is framework-independent
-## Using TestClientFactory
-## Controller Testing
-## Module Testing
-## Mocking Services
+With the `Test` class, you can create an application execution context that simulates the entire Ellar runtime, 
+providing hooks to easily manage class instances by allowing for mocking and overriding.
+
+The `Test` class has a `create_test_module()` method that takes a module metadata object as its argument (the same object you pass to the `@Module()` decorator).
+This method returns a `TestingModule` instance which in turn provides a few methods:
+
+- [**`override_provider`**](#overriding-providers): Essential for overriding `providers` or `guards` with a mocked type.
+- [**`create_application`**](#create-application): This method will return an application instance for the isolated testing module.
+- [**`get_test_client`**](#testclient): creates and return a `TestClient` for the application which will allow you to make requests against your application, using the `httpx` library.
+
+### **Overriding Providers**
+`TestingModule` `override_provider` method allows you to provide an alternative for a provider type or a guard type. For example:
+
+```python
+from ellar.testing import Test
+
+class MockCarRepository(CarRepository):
+    pass
+
+class TestCarController:
+    def setup(self):
+        test_module = Test.create_test_module(
+            controllers=[CarController,]
+        ).override_provider(
+            CarRepository, use_class=MockCarRepository
+        )
+```
+`override_provider` takes the same arguments as `ellar.di.ProviderConfig` and in fact, it builds to `ProvideConfig` behind the scenes.
+In example above, we created a `MockCarRepository` for `CarRepository` and applied it as shown above. 
+We can also create an instance of `MockCarRepository` and have it behave as a singleton within the scope of `test_module` instance.
+
+```python
+from ellar.testing import Test
+
+class MockCarRepository(CarRepository):
+    pass
+
+class TestCarController:
+    def setup(self):
+        test_module = Test.create_test_module(
+            controllers=[CarController,]
+        ).override_provider(CarRepository, use_value=MockCarRepository())
+```
+We this, anywhere `CarRepository` is needed, a `MockCarRepository()` instance will be applied.
+
+In same way, we can override `Guards` used in controllers during testing. For example, lets assume `CarController` has a guard `JWTGuard`
+
+```python
+import typing
+from ellar.compatible.dict import AttributeDict
+from ellar.common import Guards, Controller
+from ellar.core import ControllerBase
+from ellar.core.guard import HttpBearerAuth
+from ellar.di import injectable
+
+
+@injectable()
+class JWTGuard(HttpBearerAuth):
+    async def authenticate(self, connection, credentials) -> typing.Any:
+        # JWT verification goes here
+        return AttributeDict(is_authenticated=True, first_name='Ellar', last_name='ASGI Framework') 
+
+
+@Guards(JWTGuard)
+@Controller('/car')
+class CarController(ControllerBase):
+    ...
+```
+During testing, we can replace `JWTGuard` with a `MockAuthGuard` as shown below.
+
+```python
+from ellar.testing import Test
+from .controllers import CarController, JWTGuard
+
+class MockAuthGuard(JWTGuard):
+    async def authenticate(self, connection, credentials) -> typing.Any:
+        # Jwt verification goes here.
+        return dict(first_name='Ellar', last_name='ASGI Framework')
+
+
+class TestCarController:
+    def setup(self):
+        test_module = Test.create_test_module(
+            controllers=[CarController,]
+        ).override_provider(JWTGuard, use_class=MockAuthGuard)
+```
+### **Create Application**
+We can access the application instance after setting up the `TestingModule`. You simply need to call `create_application` method of the `TestingModule`. 
+
+For example:
+```python
+from ellar.di import ProviderConfig
+from ellar.testing import Test
+
+class TestCarController:
+    def setup(self):
+        test_module = Test.create_test_module(
+            controllers=[CarController,], 
+            providers=[ProviderConfig(CarRepository, use_class=CarRepository)]
+        )
+        app = test_module.create_application()
+        car_repo = app.injector.get(CarRepository)
+        assert isinstance(car_repo, CarRepository)
+```
+
+### **Overriding Application Conf During Testing**
+Having different application configurations for different environments is a best practice in software development. 
+It involves creating different sets of configuration variables, such as database connection details, API keys, and environment-specific settings, 
+for different environments such as development, staging, and production.
+
+During testing, there two ways to apply or modify configuration.
+
+=== "In a file"
+    In `config.py` file, we can define another configuration for testing eg, `class TestConfiguration` and then we can apply it to `config_module` when creating `TestingModule`.
+
+    For example:
+
+    ```python
+    # project_name/config.py
+    
+    ...
+    
+    class BaseConfig(ConfigDefaultTypesMixin):
+        DEBUG: bool = False
+    
+    class TestingConfiguration(BaseConfig):
+        DEBUG = True
+        ANOTHER_CONFIG_VAR = 'Ellar'
+        
+    ```
+    We have created `TestingConfiguration` inside `project_name.config` python module. Lets apply this to TestingModule.
+    
+    ```python
+    # project_name/car/tests/test_controllers.py
+    
+    class TestCarController:
+        def setup(self):
+            test_module = Test.create_test_module(
+                controllers=[CarController,], 
+                providers=[ProviderConfig(CarRepository, use_class=CarRepository)],
+                config_module='project_name.config.TestingConfiguration'
+            )
+            self.controller: CarController = test_module.get(CarController)
+    ```
+=== "Inline"
+    This method doesn't require configuration file, we simply go ahead and define the configuration variables in a dictionary type set to `config_module`. 
+
+    For instance:
+    
+    ```python
+    # project_name/car/tests/test_controllers.py
+    
+    class TestCarController:
+        def setup(self):
+            test_module = Test.create_test_module(
+                controllers=[CarController,], 
+                providers=[ProviderConfig(CarRepository, use_class=CarRepository)],
+                config_module=dict(DEBUG=True, ANOTHER_CONFIG_VAR='Ellar')
+            )
+            self.controller: CarController = test_module.get(CarController)
+    ```
+
+
+## **End-to-End Test**
+**End-to-end (e2e)** testing operates on a higher level of abstraction than unit testing, assessing the interaction between 
+classes and modules in a way that approximates user behavior with the production system. 
+
+As an application expands, manual e2e testing of every API endpoint becomes increasingly difficult, 
+which is where automated e2e testing becomes essential in validating that the system's overall behavior is correct and 
+aligned with project requirements. 
+
+To execute e2e tests, we adopt a similar configuration to that of unit testing, 
+and Ellar's use of **TestClient**, a tool provided by Starlette, to facilitates the simulation of HTTP requests
+
+### **TestClient**
+Starlette provides a [TestClient](https://www.starlette.io/testclient/) for making requests ASGI Applications, and it's based on [httpx](https://www.python-httpx.org/) library similar to requests.
+```python
+from starlette.responses import HTMLResponse
+from starlette.testclient import TestClient
+
+
+async def app(scope, receive, send):
+    assert scope['type'] == 'http'
+    response = HTMLResponse('<html><body>Hello, world!</body></html>')
+    await response(scope, receive, send)
+
+
+def test_app():
+    client = TestClient(app)
+    response = client.get('/')
+    assert response.status_code == 200
+```
+In example above, `TestClient` needs an `ASGI` Callable. It exposes the same interface as any other `httpx` session. 
+In particular, note that the calls to make a request are just standard function calls, not awaitable.
+
+Let's see how we can use `TestClient` in writing e2e testing for `CarController` and `CarRepository`.
+
+```python
+# project_name/car/tests/test_controllers.py
+from unittest.mock import patch
+from ellar.di import ProviderConfig
+from ellar.testing import Test, TestClient
+from project_name.apps.car.controllers import CarController
+from project_name.apps.car.schemas import CreateCarSerializer, CarListFilter
+from project_name.apps.car.services import CarRepository
+
+
+class TestCarControllerE2E:
+    def setup(self):
+        test_module = Test.create_test_module(
+            controllers=[CarController,],
+            providers=[ProviderConfig(CarRepository, use_class=CarRepository)],
+            config_module=dict(
+                REDIRECT_SLASHES=True
+            )
+        )
+        self.client: TestClient = test_module.get_test_client()
+
+    def test_create_action(self):
+        res = self.client.post('/car', json=dict(
+            name="Mercedes", year=2022, model="CLS"
+        ))
+        assert res.status_code == 200
+        assert res.json() == {
+            "id": "1",
+            "message": "This action adds a new car",
+            "model": "CLS",
+            "name": "Mercedes",
+            "year": 2022,
+        }
+
+    @patch.object(CarRepository, 'get_all', return_value=[dict(id=2, model='CLS',name='Mercedes', year=2023)])
+    def test_get_all_action(self, mock_get_all):
+        res = self.client.get('/car?offset=0&limit=10')
+        assert res.status_code == 200
+        assert res.json() == {
+            'cars': [
+                {
+                    'id': 2,
+                    'model': 'CLS',
+                    'name': 'Mercedes',
+                    'year': 2023
+                }
+            ],
+            'message': 'This action returns all cars at limit=10, offset=0'
+        }
+```
+
+In the construct above, `test_module.get_test_client()` created an isolated application instance and used it to instantiate a `TestClient`.
+And with we are able to simulate request behaviour on `CarController`.

ellar/testing/module.py

@@ -121,14 +121,3 @@ def create_test_module(
         return cls.TESTING_MODULE(
             testing_module, global_guards=global_guards, config_module=config_module
         )
-
-    @classmethod
-    def create_test_module_from_module(
-        cls,
-        module: t.Type[t.Union[ModuleBase, t.Any]],
-        config_module: str = None,
-    ) -> TestingModule:
-        """
-        Create a TestingModule from an existing module
-        """
-        return cls.TESTING_MODULE(module, global_guards=[], config_module=config_module)

tests/test_application/test_application_functions.py

@@ -28,8 +28,9 @@
 from .config import ConfigTrustHostConfigure
 from .sample import AppAPIKey, ApplicationModule
 
-test_module = Test.create_test_module_from_module(
-    module=ApplicationModule, config_module=get_class_import(ConfigTrustHostConfigure)
+test_module = Test.create_test_module(
+    modules=(ApplicationModule,),
+    config_module=get_class_import(ConfigTrustHostConfigure),
 )
 
 

tests/test_application/test_replacing_app_services.py

@@ -108,7 +108,7 @@ def exception_400(self, context: IHostContext, exc: Exception):
                 "Exception 400 handled by ExampleModule.exception_400"
             )
 
-    tm = Test.create_test_module_from_module(ExampleModule)
+    tm = Test.create_test_module(modules=[ExampleModule])
 
     assert hasattr(NewExceptionMiddlewareService, "worked") is False
     client = tm.get_test_client()

tests/test_cache/test_module_setup.py

@@ -4,11 +4,13 @@
 
 
 def test_cache_module_setup_works():
-    tm = Test.create_test_module_from_module(
-        CacheModule.setup(
-            default=LocalMemCacheBackend(),
-            local=LocalMemCacheBackend(version=2, ttl=400),
-        )
+    tm = Test.create_test_module(
+        modules=[
+            CacheModule.setup(
+                default=LocalMemCacheBackend(),
+                local=LocalMemCacheBackend(version=2, ttl=400),
+            )
+        ]
     )
 
     cache_service = tm.get(ICacheService)