docs: 📚 document testing's core components (#305)

hbakri · Nov 16, 2023 · e2ddf7a · e2ddf7a
1 parent 3fcd52d
commit e2ddf7a
Show file tree

Hide file tree

Showing 7 changed files with 141 additions and 62 deletions.
diff --git a/.gitignore b/.gitignore
@@ -164,9 +164,8 @@ cython_debug/
 Icon?
 Icon
 
-# Pydoc-markdown
-docs/reference/views/*.md
-docs/reference/tests/*.md
+# Documentation
+docs/reference/
 
 # Ruff
 .ruff_cache/
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
@@ -26,7 +26,14 @@
   - [ModelViewSet](ModelViewSet)
   - [BaseModelViewSet](BaseModelViewSet)
 
-### Tests
+### Testing
+
+#### Components
+
+  - [PathParameters](PathParameters)
+  - [QueryParameters](QueryParameters)
+  - [Headers](Headers)
+  - [Payloads](Payloads)
 
 > 🚧 **Work in Progress**
 >

diff --git a/docs/generate_docs.py b/docs/generate_docs.py
@@ -15,6 +15,10 @@
     ("views/helpers/types", "Types"),
     ("viewsets/model_viewset", "ModelViewSet"),
     ("viewsets/base_model_viewset", "BaseModelViewSet"),
+    ("testing/core/components/headers", "Headers"),
+    ("testing/core/components/path_parameters", "PathParameters"),
+    ("testing/core/components/payloads", "Payloads"),
+    ("testing/core/components/query_parameters", "QueryParameters"),
 ]
 
 template_path = "docs/pydoc-markdown.yml"

diff --git a/ninja_crud/testing/core/components/headers.py b/ninja_crud/testing/core/components/headers.py
@@ -5,26 +5,31 @@
 
 class Headers:
     """
-    This class is used to manage headers used in HTTP requests.
+    Manages HTTP request headers for various test scenarios.
 
-    This class allows you to define sets of headers for different test scenarios. Specifically,
-    it enables you to set up headers that should result in successful requests ('ok'), headers
-    that should result in 'forbidden' responses, and headers that should result in 'unauthorized'
+    The Headers class is designed to simplify the process of defining and using different sets of
+    headers for multiple test scenarios. It supports defining headers for successful requests (`ok`),
+    as well as headers expected to result in forbidden (`forbidden`) or unauthorized (`unauthorized`)
     responses.
 
+    One of the key features is its ability to accept either a single dictionary (for testing a single
+    case) or a list of dictionaries (for testing multiple cases), providing a convenient way to test
+    various scenarios with minimal setup.
+
     Example:
-        >>> from ninja_crud.testing.core.components import Headers
-        >>> headers = Headers(
-        ...     ok=[{"HTTP_AUTHORIZATION": "Bearer ok"}],
-        ...     forbidden=[{"HTTP_AUTHORIZATION": "Bearer forbidden"}],
-        ...     unauthorized=[{}]
-        ... )
-        >>> headers.ok
-        [{"HTTP_AUTHORIZATION": "Bearer ok"}]
-        >>> headers.forbidden
-        [{"HTTP_AUTHORIZATION": "Bearer forbidden"}]
-        >>> headers.unauthorized
-        [{}]
+    ```python
+    from ninja_crud.testing.core.components import Headers
+
+    # Single case
+    single_headers = Headers(ok={"HTTP_AUTHORIZATION": "Bearer ok"})
+
+    # Multiple cases
+    multiple_headers = Headers(
+        ok=[{"HTTP_AUTHORIZATION": "Bearer ok1"}, {"HTTP_AUTHORIZATION": "Bearer ok2"}],
+        forbidden=[{"HTTP_AUTHORIZATION": "Bearer forbidden"}],
+        unauthorized=[{}]
+    )
+    ```
     """
 
     def __init__(
@@ -33,6 +38,17 @@ def __init__(
         forbidden: Union[dict, List[dict], None] = None,
         unauthorized: Union[dict, List[dict], None] = None,
     ) -> None:
+        """
+        Initializes the Headers instance, allowing for the specification of various header configurations.
+
+        Args:
+            ok (Union[dict, List[dict]]): Headers for successful requests. Can be a single dictionary
+                for one test case, or a list of dictionaries for multiple cases.
+            forbidden (Union[dict, List[dict], None], optional): Headers expected to yield a 'forbidden'
+                response. Accepts a single dictionary or a list of dictionaries. Defaults to `None`.
+            unauthorized (Union[dict, List[dict], None], optional): Headers expected to yield an 'unauthorized'
+                response. Like `ok` and `forbidden`, it accepts both a single dictionary or a list. Defaults to `None`.
+        """
         self.ok: List[dict] = utils.ensure_list_of_dicts(ok)
         self.forbidden: Optional[List[dict]] = (
             utils.ensure_list_of_dicts(forbidden) if forbidden is not None else None

diff --git a/ninja_crud/testing/core/components/path_parameters.py b/ninja_crud/testing/core/components/path_parameters.py
@@ -5,29 +5,46 @@
 
 class PathParameters:
     """
-    This class is used to manage path parameters used in HTTP requests.
+    Manages HTTP path parameters for various test scenarios.
 
-    This class allows you to define sets of path parameters for different test scenarios. Specifically,
-    it enables you to set up parameters that should result in successful requests ('ok') and parameters
-    that should result in 'not found' responses.
+    The PathParameters class is designed to simplify the process of defining and using different sets of
+    path parameters for multiple test scenarios. It supports defining path parameters for successful
+    requests (`ok`), as well as path parameters expected to result in not found (`not_found`) responses.
+
+    One of the key features is its ability to accept either a single dictionary (for testing a single
+    case) or a list of dictionaries (for testing multiple cases), providing a convenient way to test
+    various scenarios with minimal setup.
 
     Example:
-        >>> from ninja_crud.testing.core.components import PathParameters
-        >>> path_parameters = PathParameters(
-        ...     ok=[{"id": 1}, {"id": 2}],
-        ...     not_found=[{"id": 3}, {"id": 4}],
-        ... )
-        >>> path_parameters.ok
-        [{'id': 1}, {'id': 2}]
-        >>> path_parameters.not_found
-        [{'id': 3}, {'id': 4}]
+    ```python
+    from ninja_crud.testing.core.components import PathParameters
+
+    # Single case
+    single_path_parameters = PathParameters(ok={"id": 1})
+
+    # Multiple cases
+    multiple_path_parameters = PathParameters(
+        ok=[{"id": 1}, {"id": 2}],
+        not_found=[{"id": 3}]
+    )
+    ```
     """
 
     def __init__(
         self,
         ok: Union[dict, List[dict]],
         not_found: Union[dict, List[dict], None] = None,
     ) -> None:
+        """
+        Initializes the PathParameters instance, allowing for the specification of various
+        path parameter configurations.
+
+        Args:
+            ok (Union[dict, List[dict]]): Path parameters for successful resolution. Can be a single
+                dictionary representing one test case or a list of dictionaries for multiple test cases.
+            not_found (Union[dict, List[dict], None], optional): Path parameters expected to lead to a
+                'not found' outcome. Accepts either a single dictionary or a list of dictionaries. Defaults to `None`.
+        """
         self.ok: List[dict] = utils.ensure_list_of_dicts(ok)
         self.not_found: Optional[List[dict]] = (
             utils.ensure_list_of_dicts(not_found) if not_found is not None else None

diff --git a/ninja_crud/testing/core/components/payloads.py b/ninja_crud/testing/core/components/payloads.py
@@ -5,26 +5,31 @@
 
 class Payloads:
     """
-    This class is used to manage payloads used in HTTP requests.
+    Manages HTTP request payloads for various test scenarios.
 
-    This class allows you to define sets of payloads for different test scenarios. Specifically,
-    it enables you to set up payloads that should result in successful requests ('ok'), payloads
-    that should result in 'bad request' responses, and payloads that should result in 'conflict'
+    The Payloads class is designed to simplify the process of defining and using different sets of
+    payloads for multiple test scenarios. It supports defining payloads for successful requests (`ok`),
+    as well as payloads expected to result in bad request (`bad_request`) or conflict (`conflict`)
     responses.
 
+    One of the key features is its ability to accept either a single dictionary (for testing a single
+    case) or a list of dictionaries (for testing multiple cases), providing a convenient way to test
+    various scenarios with minimal setup.
+
     Example:
-        >>> from ninja_crud.testing.core.components import Payloads
-        >>> payloads = Payloads(
-        ...     ok=[{"name": "item 1"}, {"name": "item 2"}],
-        ...     bad_request=[{"name": ""}],
-        ...     conflict=[{"name": "existing item"}],
-        ... )
-        >>> payloads.ok
-        [{'name': 'item 1'}, {'name': 'item 2'}]
-        >>> payloads.bad_request
-        [{'name': ''}]
-        >>> payloads.conflict
-        [{'name': 'existing item'}]
+    ```python
+    from ninja_crud.testing.core.components import Payloads
+
+    # Single case
+    single_payloads = Payloads(ok={"name": "ok"})
+
+    # Multiple cases
+    multiple_payloads = Payloads(
+        ok=[{"name": "ok1"}, {"name": "ok2"}],
+        bad_request=[{"name": "bad_request"}],
+        conflict=[{"name": "conflict"}]
+    )
+    ```
     """
 
     def __init__(
@@ -33,6 +38,18 @@ def __init__(
         bad_request: Union[dict, List[dict], None] = None,
         conflict: Union[dict, List[dict], None] = None,
     ) -> None:
+        """
+        Initializes the Payloads instance, allowing for the specification of various payload configurations.
+
+        Args:
+            ok (Union[dict, List[dict]]): Payloads for successful requests. Can be a single dictionary
+                for one test case, or a list of dictionaries for multiple cases.
+            bad_request (Union[dict, List[dict], None], optional): Payloads expected to yield a 'bad request'
+                response. Accepts a single dictionary or a list of dictionaries. Defaults to `None`.
+            conflict (Union[dict, List[dict], None], optional): Payloads expected to yield a 'conflict'
+                response. Like `ok` and `bad_request`, it accepts both a single dictionary or a list.
+                Defaults to `None`.
+        """
         self.ok: List[dict] = utils.ensure_list_of_dicts(ok)
         self.bad_request: Optional[List[dict]] = (
             utils.ensure_list_of_dicts(bad_request) if bad_request is not None else None

diff --git a/ninja_crud/testing/core/components/query_parameters.py b/ninja_crud/testing/core/components/query_parameters.py
@@ -5,29 +5,48 @@
 
 class QueryParameters:
     """
-    This class is used to manage query parameters used in HTTP requests.
+    Manages HTTP query parameters for various test scenarios.
 
-    This class allows you to define sets of query parameters for different test scenarios. Specifically,
-    it enables you to set up parameters that should result in successful requests ('ok') and parameters
-    that should result in 'bad request' responses.
+    The QueryParameters class is designed to simplify the process of defining and using different sets of
+    query parameters for multiple test scenarios. It supports defining query parameters for successful
+    requests (`ok`), as well as query parameters expected to result in bad request (`bad_request`)
+    responses.
+
+    One of the key features is its ability to accept either a single dictionary (for testing a single
+    case) or a list of dictionaries (for testing multiple cases), providing a convenient way to test
+    various scenarios with minimal setup.
 
     Example:
-        >>> from ninja_crud.testing.core.components import QueryParameters
-        >>> query_parameters = QueryParameters(
-        ...     ok=[{"search": "item"}, {"page": 2, "limit": 10}],
-        ...     bad_request=[{"page": -1}, {"limit": "invalid"}],
-        ... )
-        >>> query_parameters.ok
-        [{'search': 'item'}, {'page': 2, 'limit': 10}]
-        >>> query_parameters.bad_request
-        [{'page': -1}, {'limit': 'invalid'}]
+    ```python
+    from ninja_crud.testing.core.components import QueryParameters
+
+    # Single case
+    single_query_parameters = QueryParameters(ok={"page": 2, "limit": 10})
+
+    # Multiple cases
+    multiple_query_parameters = QueryParameters(
+        ok=[{"page": 1, "limit": 10}, {"page": 2, "limit": 10}],
+        bad_request=[{"page": 1, "limit": 0}]
+    )
+    ```
     """
 
     def __init__(
         self,
         ok: Union[dict, List[dict]],
         bad_request: Union[dict, List[dict], None] = None,
     ) -> None:
+        """
+        Initializes the QueryParameters instance, allowing for the specification of various
+        query parameter configurations.
+
+        Args:
+            ok (Union[dict, List[dict]]): Query parameters for successful resolution. Can be a single
+                dictionary representing one test case or a list of dictionaries for multiple test cases.
+            bad_request (Union[dict, List[dict], None], optional): Query parameters expected to lead to a
+                'bad request' outcome. Accepts either a single dictionary or a list of dictionaries.
+                Defaults to `None`.
+        """
         self.ok: List[dict] = utils.ensure_list_of_dicts(ok)
         self.bad_request: Optional[List[dict]] = (
             utils.ensure_list_of_dicts(bad_request) if bad_request is not None else None