Merge pull request #1448 from tisnik/lcore-1608-updated-docstrings-in-auth-unit-tests

LCORE-1608: Updated docstrings in auth unit tests

Author: tisnik

tests/unit/authentication/test_api_key_token.py

@@ -15,7 +15,8 @@
 def default_api_key_token_configuration() -> APIKeyTokenConfiguration:
     """Default APIKeyTokenConfiguration for testing.
 
-    Provide a default APIKeyTokenConfiguration for tests.
+    Pytest fixture providing a default APIKeyTokenConfiguration for
+    tests.
 
     Returns:
         APIKeyTokenConfiguration: configuration with `api_key` set to

tests/unit/authentication/test_jwk_token.py

@@ -57,7 +57,16 @@ def token_payload() -> dict[str, Any]:
 
 
 def make_key() -> dict[str, Any]:
-    """Generate a key pair for testing purposes."""
+    """Generate a key pair for testing purposes.
+
+    Create an RSA test key pair and return the private key, public key, and key identifier.
+
+    Returns:
+        dict: A dictionary with the following entries:
+            - "private_key": the generated private JsonWebKey instance.
+            - "public_key": the corresponding public JsonWebKey instance.
+            - "kid": the key identifier (thumbprint) as a string.
+    """
     key = JsonWebKey.generate_key("RSA", 2048, is_private=True)
     return {
         "private_key": key,
@@ -79,8 +88,10 @@ def another_single_key_set() -> list[dict[str, Any]]:
     Create a single-key JWK set using a newly generated RSA key.
 
     Returns:
-        list[dict[str, Any]]: A list containing one key dict with keys
-        `private_key`, `public_key`, and `kid`.
+        list[dict[str, Any]]: A list containing one dict with keys:
+            - `private_key`: the generated private JsonWebKey
+            - `public_key`: the corresponding public JsonWebKey
+            - `kid`: the key identifier (thumbprint)
     """
     return [make_key()]
 
@@ -114,7 +125,11 @@ def valid_token(
 
 @pytest.fixture(autouse=True)
 def clear_jwk_cache() -> Generator:
-    """Clear the global JWK cache before each test."""
+    """Clear the global JWK cache before each test.
+
+    This autouse fixture ensures the module-level `_jwk_cache` is emptied at
+    setup and teardown to prevent cross-test interference.
+    """
     _jwk_cache.clear()
     yield
     _jwk_cache.clear()
@@ -497,6 +512,9 @@ def no_user_id_token(
     `single_key_set`; the supplied `token_payload` is modified in-place to
     remove `user_id`.
 
+    Parameters:
+        token_payload (dict): Payload to encode; will be mutated to remove `user_id`.
+
     Returns:
         jwt (str): Encoded JWT as a string that does not contain the `user_id` claim.
     """
@@ -637,7 +655,11 @@ async def test_custom_claims(
     mocked_signing_keys_server: Any,
     custom_claims_token: str,
 ) -> None:
-    """Test with a token that has custom claims."""
+    """Test with a token that has custom claims.
+
+    Asserts the returned auth tuple matches the expected user id, username,
+    skip flag, and original token.
+    """
     _ = mocked_signing_keys_server
 
     dependency = JwkTokenAuthDependency(custom_claims_configuration)
@@ -650,7 +672,15 @@ async def test_custom_claims(
 
 @pytest.fixture
 def token_header_256_1(multi_key_set: list[dict[str, Any]]) -> dict[str, Any]:
-    """A sample token header for RS256 using multi_key_set."""
+    """A sample token header for RS256 using multi_key_set.
+
+    Parameters:
+        multi_key_set (list[dict[str, Any]]): List of JWK dictionaries; the
+        header's `kid` is taken from multi_key_set[0]["kid"].
+
+    Returns:
+        dict[str, Any]: JWT header containing "alg", "typ", and "kid".
+    """
     return {"alg": "RS256", "typ": "JWT", "kid": multi_key_set[0]["kid"]}
 
 
@@ -727,7 +757,7 @@ def multi_key_set() -> list[dict[str, Any]]:
     by tests (e.g., `private_key`, `public_key`, and `kid`).
 
     Returns:
-        key_set (list[dict]): A list of three signing key dictionaries.
+        list[dict[str, Any]]: A list of three signing key dictionaries.
     """
     return [make_key(), make_key(), make_key()]
 

tests/unit/authentication/test_k8s.py

@@ -836,7 +836,15 @@ async def test_kube_admin_cluster_version_not_found_returns_500(
 async def test_kube_admin_cluster_version_permission_error_returns_500(
     mocker: MockerFixture,
 ) -> None:
-    """Test kube:admin flow returns 500 when permission to ClusterVersion is denied."""
+    """Test kube:admin flow returns 500 when permission to ClusterVersion is denied.
+
+    Sets up a request with a valid Bearer token, mocks subject access review to
+    allow the action and mocks the authenticated user as `kube:admin`. Patches
+    cluster-id retrieval to raise ClusterVersionPermissionError and asserts
+    that the dependency raises an HTTPException with status code 500,
+    `detail["response"] == "Internal server error"`, and that `detail["cause"]`
+    contains an "Insufficient permissions" message.
+    """
     dependency = K8SAuthDependency()
     mock_authz_api = mocker.patch("authentication.k8s.K8sClientSingleton.get_authz_api")
     mock_authz_api.return_value.create_subject_access_review.return_value = (

tests/unit/authentication/test_rh_identity.py

@@ -21,6 +21,12 @@ def user_identity_data() -> dict:
 
     Provide a valid Red Hat identity payload for a User, suitable for unit tests.
 
+    The payload contains two top-level keys:
+    - `identity`: includes `account_number`, `org_id`, `type` (set to
+      `"User"`), and `user` with `user_id`, `username`, and `is_org_admin`.
+    - `entitlements`: maps service names (for example, `"rhel"`, `"ansible"`,
+      `"openshift"`) to objects with `is_entitled` and `is_trial`.
+
     Returns:
         identity_data (dict): A dictionary with two top-level keys:
             - "identity": contains "account_number", "org_id", "type" (set to
@@ -485,7 +491,13 @@ class TestRHIdentityHealthProbeSkip:
     def _mock_configuration(
         mocker: MockerFixture, skip_for_health_probes: bool
     ) -> None:
-        """Patch the configuration singleton with a mock for probe skip tests."""
+        """Patch the configuration singleton with a mock for probe skip tests.
+
+        Parameters:
+            skip_for_health_probes (bool): Value to assign to the mocked
+            configuration's authentication_configuration.skip_for_health_probes
+            flag.
+        """
         mock_config = mocker.MagicMock()
         mock_config.authentication_configuration.skip_for_health_probes = (
             skip_for_health_probes
@@ -714,7 +726,13 @@ def test_org_id_valid_accepted(self, user_identity_data: dict) -> None:
         RHIdentityData(user_identity_data)
 
     def test_org_id_oversized_rejected(self, user_identity_data: dict) -> None:
-        """Reject oversized org_id."""
+        """Reject oversized org_id.
+
+        Verifies that an identity with an org_id longer than 256 characters is rejected.
+
+        Expects RHIdentityData to raise an HTTPException with status_code 400
+        when identity.org_id length exceeds 256 characters.
+        """
         user_identity_data["identity"]["org_id"] = "a" * 257
         with pytest.raises(HTTPException) as exc_info:
             RHIdentityData(user_identity_data)