Updated comments in utils

Author: tisnik

tests/e2e/utils/utils.py

@@ -10,15 +10,42 @@
 
 
 def normalize_endpoint(endpoint: str) -> str:
-    """Normalize endpoint to be added into the URL."""
+    """Normalize endpoint to be added into the URL.
+
+    Ensure an endpoint string is suitable for inclusion in a URL.
+
+    Removes any double-quote characters and prepends a leading slash if one is
+    not already present.
+
+    Parameters:
+        endpoint (str): The endpoint string to normalize.
+
+    Returns:
+        str: The normalized endpoint starting with '/' and containing no double-quote characters.
+    """
     endpoint = endpoint.replace('"', "")
     if not endpoint.startswith("/"):
         endpoint = "/" + endpoint
     return endpoint
 
 
 def validate_json(message: Any, schema: Any) -> None:
-    """Check the JSON message with the given schema."""
+    """Check the JSON message with the given schema.
+
+    Validate a JSON-like object against a jsonschema-compatible schema.
+
+    Parameters:
+        message (Any): The JSON-like instance to validate (typically a dict or list).
+        schema (Any): A jsonschema-compatible schema describing the expected structure.
+
+    Returns:
+        None
+
+    Raises:
+        AssertionError: If the instance does not conform to the schema or if
+        the schema itself is invalid; the assertion message contains the
+        underlying jsonschema error.
+    """
     try:
         jsonschema.validate(
             instance=message,
@@ -33,7 +60,23 @@ def validate_json(message: Any, schema: Any) -> None:
 
 
 def wait_for_container_health(container_name: str, max_attempts: int = 3) -> None:
-    """Wait for container to be healthy."""
+    """Wait for container to be healthy.
+
+    Polls a Docker container until its health status becomes `healthy` or the
+    attempt limit is reached.
+
+    Checks the container's `Health.Status` using `docker inspect` up to
+    `max_attempts`, printing progress and final status messages. Transient
+    inspect errors or timeouts are ignored and retried; the function returns
+    after the container is observed healthy or after all attempts complete.
+
+    Returns:
+        None
+
+    Parameters:
+        container_name (str): Docker container name or ID to check.
+        max_attempts (int): Maximum number of health check attempts (default 3).
+    """
     for attempt in range(max_attempts):
         try:
             result = subprocess.run(
@@ -71,6 +114,13 @@ def validate_json_partially(actual: Any, expected: Any) -> None:
     """Recursively validate that `actual` JSON contains all keys and values specified in `expected`.
 
     Extra elements/keys are ignored. Raises AssertionError if validation fails.
+
+    Returns:
+        None
+
+    Raises:
+        AssertionError: If a required key is missing, no list element matches
+        an expected item, or a value does not equal the expected value.
     """
     if isinstance(expected, dict):
         for key, expected_value in expected.items():
@@ -98,7 +148,24 @@ def validate_json_partially(actual: Any, expected: Any) -> None:
 def switch_config(
     source_path: str, destination_path: str = "lightspeed-stack.yaml"
 ) -> None:
-    """Overwrite the config in `destination_path` by `source_path`."""
+    """Overwrite the config in `destination_path` by `source_path`.
+
+    Replace the destination configuration file with the file at source_path.
+
+    Parameters:
+        source_path (str): Path to the replacement configuration file.
+        destination_path (str): Path to the configuration file to be
+        overwritten (defaults to "lightspeed-stack.yaml").
+
+    Returns:
+        None
+
+    Raises:
+        FileNotFoundError: If source_path does not exist.
+        PermissionError: If the file cannot be read or destination cannot be
+                         written due to permissions.
+        OSError: For other OS-related failures during the copy operation.
+    """
     try:
         shutil.copy(source_path, destination_path)
     except (FileNotFoundError, PermissionError, OSError) as e:
@@ -107,7 +174,19 @@ def switch_config(
 
 
 def create_config_backup(config_path: str) -> str:
-    """Create a backup of `config_path` if it does not already exist."""
+    """Create a backup of `config_path` if it does not already exist.
+
+    Ensure a backup of the given configuration file exists by creating a
+    `.backup` copy if it is missing.
+
+    Returns:
+        str: Path to the backup file (original path with `.backup` appended).
+
+    Raises:
+        FileNotFoundError: If the source config file does not exist.
+        PermissionError: If the process lacks permission to read or write the files.
+        OSError: For other OS-level errors encountered while copying.
+    """
     backup_file = f"{config_path}.backup"
     if not os.path.exists(backup_file):
         try:
@@ -119,7 +198,18 @@ def create_config_backup(config_path: str) -> str:
 
 
 def remove_config_backup(backup_path: str) -> None:
-    """Delete the backup file at `backup_path` if it exists."""
+    """Delete the backup file at `backup_path` if it exists.
+
+    Remove the backup file at the given path if it exists.
+
+    If the file is present, attempts to delete it; on failure prints a warning with the error.
+
+    Returns:
+        None
+
+    Parameters:
+        backup_path (str): Filesystem path to the backup file to remove.
+    """
     if os.path.exists(backup_path):
         try:
             os.remove(backup_path)
@@ -128,7 +218,15 @@ def remove_config_backup(backup_path: str) -> None:
 
 
 def restart_container(container_name: str) -> None:
-    """Restart a Docker container by name and wait until it is healthy."""
+    """Restart a Docker container by name and wait until it is healthy.
+
+    Returns:
+        None
+
+    Raises:
+        subprocess.CalledProcessError: if the `docker restart` command fails.
+        subprocess.TimeoutExpired: if the `docker restart` command times out.
+    """
     try:
         subprocess.run(
             ["docker", "restart", container_name],
@@ -147,13 +245,12 @@ def restart_container(container_name: str) -> None:
 def replace_placeholders(context: Context, text: str) -> str:
     """Replace {MODEL} and {PROVIDER} placeholders with actual values from context.
 
-    Args:
-        context: Behave context containing default_model and default_provider
-        text: String that may contain {MODEL} and {PROVIDER} placeholders
+    Parameters:
+        context (Context): Behave context containing default_model and default_provider
+        text (str): String that may contain {MODEL} and {PROVIDER} placeholders
 
     Returns:
         String with placeholders replaced by actual values
-
     """
     result = text.replace("{MODEL}", context.default_model)
     result = result.replace("{PROVIDER}", context.default_provider)