doc: better documentation for the checkers

Author: azmeuk

scim2_tester/checkers/__init__.py

@@ -13,7 +13,6 @@
 from .misc import random_url
 from .resource import resource_type_tests
 from .resource_delete import object_deletion
-from .resource_get import model_from_resource_type
 from .resource_get import object_query
 from .resource_get import object_query_without_id
 from .resource_post import object_creation
@@ -48,6 +47,4 @@
     "resource_type_tests",
     # Miscellaneous checkers
     "random_url",
-    # Utilities
-    "model_from_resource_type",
 ]

scim2_tester/checkers/misc.py

@@ -11,7 +11,26 @@
 
 @checker("misc")
 def random_url(context: CheckContext) -> CheckResult:
-    """Check that a request to a random URL returns a 404 Error object."""
+    """Validate server error handling for non-existent endpoints.
+
+    Tests that the server properly returns a :class:`~scim2_models.Error` object with HTTP 404 status
+    when accessing invalid or non-existent URLs, ensuring compliance with SCIM
+    error handling requirements.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Server returns valid :class:`~scim2_models.Error` object with 404 status
+    - :attr:`~scim2_tester.Status.ERROR`: Server returns non-:class:`~scim2_models.Error` object or incorrect status code
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.12 - Error Response Handling <7644#section-3.12>`
+
+       "When returning HTTP error status codes other than a '401' 'Unauthorized',
+       '403' 'Forbidden', or '404' 'Not Found', the server SHOULD return
+       a SCIM error response."
+
+       For 404 responses specifically, servers SHOULD return proper :class:`~scim2_models.Error`
+       objects to maintain consistent error handling across all endpoints.
+    """
     probably_invalid_url = f"/{str(uuid.uuid4())}"
     response: Any = context.client.query(
         url=probably_invalid_url, raise_scim_errors=False

scim2_tester/checkers/resource.py

@@ -4,7 +4,7 @@
 from ..utils import CheckResult
 from ..utils import Status
 from .resource_delete import object_deletion
-from .resource_get import model_from_resource_type
+from .resource_get import _model_from_resource_type
 from .resource_get import object_query
 from .resource_get import object_query_without_id
 from .resource_post import object_creation
@@ -15,13 +15,24 @@ def resource_type_tests(
     context: CheckContext,
     resource_type: ResourceType,
 ) -> list[CheckResult]:
-    """Orchestrate CRUD tests for a resource type.
+    """Orchestrate comprehensive CRUD testing for a specific resource type.
 
-    :param context: The check context containing the SCIM client and configuration
-    :param resource_type: The ResourceType object to test
-    :returns: A list of check results for all tested operations
+    Runs the complete suite of CRUD operations (Create, Read, Update, Delete)
+    on a given resource type to validate full lifecycle management compliance.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: All CRUD operations completed successfully
+    - :attr:`~scim2_tester.Status.ERROR`: One or more CRUD operations failed or no schema found
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3 - SCIM Protocol <7644#section-3>`
+
+       "SCIM is intended to reduce the cost and complexity of user management
+       operations by providing a common user schema and extension model, as
+       well as binding documents to provide patterns for exchanging this schema
+       using standard protocols."
     """
-    model = model_from_resource_type(context, resource_type)
+    model = _model_from_resource_type(context, resource_type)
     if not model:
         return [
             CheckResult(

scim2_tester/checkers/resource_delete.py

@@ -10,14 +10,23 @@
 
 @checker("crud:delete")
 def object_deletion(context: CheckContext, model: type[Resource[Any]]) -> CheckResult:
-    """Test object deletion with automatic cleanup.
+    """Validate SCIM resource deletion via DELETE requests.
 
-    Creates a test object specifically for deletion testing, performs the
-    delete operation, and verifies the object no longer exists.
+    Tests that resources can be successfully deleted using DELETE method and
+    verifies that the resource no longer exists after deletion.
 
-    :param context: The check context containing the SCIM client and configuration
-    :param model: The Resource model class to test
-    :returns: The result of the check operation
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Resource deleted successfully and no longer accessible
+    - :attr:`~scim2_tester.Status.ERROR`: Deletion failed or resource still exists after deletion
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.6 - Deleting Resources <7644#section-3.6>`
+
+       "Clients request resource removal via HTTP DELETE requests to the
+       resource endpoint (e.g., ``/Users/{id}`` or ``/Groups/{id}``)."
+
+       "In response to a successful DELETE, the server SHALL return HTTP status
+       code 204 (No Content)."
     """
     test_obj = context.resource_manager.create_and_register(model)
 

scim2_tester/checkers/resource_get.py

@@ -9,17 +9,13 @@
 from ..utils import checker
 
 
-def model_from_resource_type(
+def _model_from_resource_type(
     context: CheckContext, resource_type: ResourceType
 ) -> type[Resource[Any]] | None:
-    """Return the Resource model class from a given ResourceType.
+    """Resolve Resource model class from ResourceType metadata.
 
-    ResourceType.name contains the resource type name (e.g., "User", "Group").
-    This function looks up the corresponding model class from the client.
-
-    :param context: The check context containing the SCIM client and configuration
-    :param resource_type: The ResourceType object containing metadata
-    :returns: The Resource model class, or None if not found
+    Maps a :class:`~scim2_models.ResourceType` object (containing schema URIs and metadata) to the
+    corresponding Python model class registered in the SCIM client.
     """
     for resource_model in context.client.resource_models:
         if resource_model.model_fields["schemas"].default[0] == resource_type.schema_:
@@ -30,14 +26,23 @@ def model_from_resource_type(
 
 @checker("crud:read")
 def object_query(context: CheckContext, model: type[Resource[Any]]) -> CheckResult:
-    """Test object query by ID with automatic cleanup.
+    """Validate SCIM resource retrieval by ID via GET requests.
+
+    Tests that individual resources can be successfully retrieved using GET method
+    on the resource endpoint with specific resource ID, with automatic cleanup.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Resource retrieved successfully with valid data
+    - :attr:`~scim2_tester.Status.ERROR`: Failed to retrieve or received invalid response
 
-    Creates a temporary test object, queries it by ID to validate the
-    read operation.
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.4.1 - Retrieving a Known Resource <7644#section-3.4.1>`
 
-    :param context: The check context containing the SCIM client and configuration
-    :param model: The Resource model class to test
-    :returns: The result of the check operation
+       "Clients retrieve a known resource using an HTTP GET request to the resource
+       endpoint, such as ``/Users/{id}`` or ``/Groups/{id}``."
+
+       "If successful, the server responds with HTTP status code 200 (OK) and includes
+       the target resource within the response body."
     """
     test_obj = context.resource_manager.create_and_register(model)
 
@@ -58,14 +63,21 @@ def object_query(context: CheckContext, model: type[Resource[Any]]) -> CheckResu
 def object_query_without_id(
     context: CheckContext, model: type[Resource[Any]]
 ) -> CheckResult:
-    """Test object listing without ID with automatic cleanup.
+    """Validate SCIM resource listing via GET requests without ID.
+
+    Tests that resources can be successfully listed using GET method on the
+    collection endpoint, validating bulk retrieval with automatic cleanup.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Resources listed successfully, created resource found
+    - :attr:`~scim2_tester.Status.ERROR`: Failed to list resources or created resource not found
 
-    Creates a temporary test object, performs a list/search operation to
-    validate bulk retrieval.
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.4.2 - List/Query Resources <7644#section-3.4.2>`
 
-    :param context: The check context containing the SCIM client and configuration
-    :param model: The Resource model class to test
-    :returns: The result of the check operation
+       "To query resources, clients send GET requests to the resource endpoint
+       (e.g., ``/Users`` or ``/Groups``). The response to a successful query
+       operation SHALL be a JSON structure that matches the ListResponse schema."
     """
     test_obj = context.resource_manager.create_and_register(model)
 

scim2_tester/checkers/resource_post.py

@@ -10,14 +10,24 @@
 
 @checker("crud:create")
 def object_creation(context: CheckContext, model: type[Resource[Any]]) -> CheckResult:
-    """Test object creation with automatic cleanup.
+    """Validate SCIM resource creation via POST requests.
 
-    Creates a test object of the specified model type, validates the creation
-    operation.
+    Tests that resources can be successfully created using POST method on the
+    appropriate resource endpoint, with automatic cleanup after validation.
+    Creates a test object with all required fields populated with valid data.
 
-    :param context: The check context containing the SCIM client and configuration
-    :param model: The Resource model class to test
-    :returns: The result of the check operation
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Resource created successfully with valid response
+    - :attr:`~scim2_tester.Status.ERROR`: Creation failed due to client/server error
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.3 - Creating Resources <7644#section-3.3>`
+
+       "To create new resources, clients send HTTP POST requests to the resource
+       endpoint, such as ``/Users`` or ``/Groups``."
+
+       "If the resource is successfully created, the server SHALL return a ``201``
+       'Created' response code with the newly created resource."
     """
     created_obj = context.resource_manager.create_and_register(model)
 

scim2_tester/checkers/resource_put.py

@@ -14,14 +14,23 @@
 def object_replacement(
     context: CheckContext, model: type[Resource[Any]]
 ) -> CheckResult:
-    """Test object replacement (PUT) with automatic cleanup.
+    """Validate SCIM resource replacement via PUT requests.
 
-    Creates a test object, modifies its mutable fields, performs a replacement
-    operation to validate the update functionality.
+    Tests that resources can be successfully replaced using PUT method, modifying
+    mutable fields and validating the complete resource replacement operation.
 
-    :param context: The check context containing the SCIM client and configuration
-    :param model: The Resource model class to test
-    :returns: The result of the check operation
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Resource replaced successfully with valid response
+    - :attr:`~scim2_tester.Status.ERROR`: Replacement failed due to client/server error
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.5.1 - Replacing Resources <7644#section-3.5.1>`
+
+       "To replace a resource's attributes, clients issue an HTTP PUT request
+       to the resource endpoint (e.g., ``/Users/{id}`` or ``/Groups/{id}``)."
+
+       "If successful, the server responds with HTTP status code 200 (OK) and
+       includes the updated resource within the response body."
     """
     test_obj = context.resource_manager.create_and_register(model)
 

scim2_tester/checkers/resource_types.py

@@ -10,13 +10,28 @@
 
 
 def resource_types_endpoint(context: CheckContext) -> list[CheckResult]:
-    """As described in RFC7644 §4 <rfc7644#section-4>`, `/ResourceTypes` is a mandatory endpoint, and should only be accessible by GET.
+    """Orchestrate validation of the ResourceTypes discovery endpoint.
+
+    Runs comprehensive tests on the ``/ResourceTypes`` endpoint including listing
+    all resource types, querying individual types by ID, and error handling for
+    invalid requests.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: All sub-checks completed successfully
+    - :attr:`~scim2_tester.Status.ERROR`: One or more sub-checks failed
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 4 - Discovery <7644#section-4>`
+
+       "An HTTP GET to this endpoint is used to discover the types of resources
+       available on a SCIM service provider (e.g., Users and Groups)."
+
+       "Service providers MUST provide this endpoint."
 
     .. todo::
 
         - Check POST/PUT/PATCH/DELETE on the endpoint
         - Check that query parameters are ignored
-        - Check that query parameters are ignored
         - Check that a 403 response is returned if a filter is passed
         - Check that the `schema` attribute exists and is available.
     """
@@ -34,6 +49,21 @@ def resource_types_endpoint(context: CheckContext) -> list[CheckResult]:
 
 @checker("discovery", "resource-types")
 def query_all_resource_types(context: CheckContext) -> CheckResult:
+    """Validate retrieval of all available resource types.
+
+    Tests that the ``/ResourceTypes`` endpoint returns a list of all supported
+    resource types with their metadata, schemas, and endpoint information.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Endpoint returns valid list of :class:`~scim2_models.ResourceType` objects
+    - :attr:`~scim2_tester.Status.ERROR`: Endpoint is inaccessible or returns invalid response
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 4 - Discovery <7644#section-4>`
+
+       "An HTTP GET to this endpoint is used to discover the types of resources
+       available on a SCIM service provider (e.g., Users and Groups)."
+    """
     response = context.client.query(
         ResourceType, expected_status_codes=context.conf.expected_status_codes or [200]
     )
@@ -46,6 +76,21 @@ def query_all_resource_types(context: CheckContext) -> CheckResult:
 def query_resource_type_by_id(
     context: CheckContext, resource_type: ResourceType
 ) -> CheckResult:
+    """Validate individual ResourceType retrieval by ID.
+
+    Tests that specific resource types can be retrieved using GET requests
+    to ``/ResourceTypes/{id}`` with their complete metadata and configuration.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: :class:`~scim2_models.ResourceType` retrieved successfully with valid data
+    - :attr:`~scim2_tester.Status.ERROR`: Failed to retrieve or received invalid response
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 4 - Discovery <7644#section-4>`
+
+       "Each resource type defines the endpoint, the core schema URI that defines
+       the resource, and any supported schema extensions."
+    """
     response = context.client.query(
         ResourceType,
         resource_type.id,
@@ -60,6 +105,20 @@ def query_resource_type_by_id(
 
 @checker("discovery", "resource-types")
 def access_invalid_resource_type(context: CheckContext) -> CheckResult:
+    """Validate error handling for non-existent resource type IDs.
+
+    Tests that accessing ``/ResourceTypes/{invalid_id}`` with a non-existent resource
+    type ID returns appropriate :class:`~scim2_models.Error` object with 404 status.
+
+    **Status:**
+
+    - :attr:`~scim2_tester.Status.SUCCESS`: Server returns :class:`~scim2_models.Error` object with 404 status
+    - :attr:`~scim2_tester.Status.ERROR`: Server returns non-:class:`~scim2_models.Error` object or incorrect status
+
+    .. pull-quote:: :rfc:`RFC 7644 Section 3.12 - Error Response Handling <7644#section-3.12>`
+
+       "When returning HTTP error status codes, the server SHOULD return a SCIM error response."
+    """
     probably_invalid_id = str(uuid.uuid4())
     response = context.client.query(
         ResourceType,