tests(regression): ensure all functions have google style docstrings

Author: harryswift01

tests/regression/cases.py

@@ -5,16 +5,48 @@
 
 @dataclass(frozen=True)
 class RegressionCase:
+    """
+    Represents a single regression test case.
+
+    A regression case corresponds to a specific system and a specific YAML
+    configuration file, along with its associated baseline file.
+
+    Attributes:
+        system (str): Name of the system (e.g. "dna", "benzene").
+        config_path (Path): Path to the YAML configuration file defining the scenario.
+        baseline_path (Path): Path to the expected baseline JSON output.
+    """
     system: str
     config_path: Path
     baseline_path: Path
 
 
 def repo_root() -> Path:
+    """
+    Return the repository root directory.
+
+    Returns:
+        Path: Absolute path to the repository root.
+    """
     return Path(__file__).resolve().parents[2]
 
 
 def discover_cases():
+    """
+    Discover all regression test cases from the configs directory.
+
+    Iterates over each system directory under `tests/regression/configs`,
+    and collects all YAML configuration files. Each configuration file is
+    paired with a corresponding baseline JSON file.
+
+    Returns:
+        list[pytest.Param]: A list of parametrized pytest cases, each wrapping
+        a RegressionCase instance.
+
+    Notes:
+        - Cases are automatically marked as slow unless the system is "dna".
+        - Baseline files are not required to exist at discovery time.
+    """
     base_dir = Path(__file__).resolve().parent
 
     configs_root = base_dir / "configs"

tests/regression/conftest.py

@@ -4,6 +4,15 @@
 
 
 def pytest_addoption(parser: pytest.Parser) -> None:
+    """
+    Register custom command-line options for pytest.
+
+    Adds options to control regression test execution, baseline updates,
+    and debugging output.
+
+    Args:
+        parser (pytest.Parser): Pytest CLI parser.
+    """
     parser.addoption(
         "--run-slow",
         action="store_true",
@@ -25,6 +34,12 @@ def pytest_addoption(parser: pytest.Parser) -> None:
 
 
 def pytest_configure(config: pytest.Config) -> None:
+    """
+    Register custom pytest markers.
+
+    Args:
+        config (pytest.Config): Pytest configuration object.
+    """
     config.addinivalue_line("markers", "regression: end-to-end regression tests")
     config.addinivalue_line("markers", "slow: long-running tests (20-30+ minutes)")
 
@@ -33,14 +48,19 @@ def pytest_collection_modifyitems(
     config: pytest.Config, items: list[pytest.Item]
 ) -> None:
     """
-    Regression tests are collected and runnable by default.
+    Modify collected test items to skip slow tests unless explicitly enabled.
+
+    Only tests marked with `@pytest.mark.slow` are skipped when the
+    `--run-slow` flag is not provided.
 
-    Only @pytest.mark.slow tests are skipped unless you pass --run-slow.
+    Args:
+        config (pytest.Config): Pytest configuration object.
+        items (list[pytest.Item]): Collected test items.
     """
     if config.getoption("--run-slow"):
         return
 
     skip_slow = pytest.mark.skip(reason="Skipped slow test (use --run-slow to run).")
     for item in items:
         if "slow" in item.keywords:
-            item.add_marker(skip_slow)
+            item.add_marker(skip_slow)

tests/regression/test_regression.py

@@ -12,6 +12,18 @@
 
 
 def _group_index(payload: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """
+    Extract the grouped structure from a regression output payload.
+
+    Args:
+        payload (dict[str, Any]): The full output payload produced by CodeEntropy.
+
+    Returns:
+        dict[str, dict[str, Any]]: Mapping of group IDs to group data.
+
+    Raises:
+        TypeError: If the 'groups' field is not a dictionary.
+    """
     groups = payload.get("groups", {})
     if not isinstance(groups, dict):
         raise TypeError("payload['groups'] must be a dict")
@@ -25,6 +37,21 @@ def _compare_grouped(
     rtol: float,
     atol: float,
 ) -> None:
+    """
+    Compare grouped regression outputs against baseline data.
+
+    Performs a structured comparison of group components and totals,
+    using numerical tolerances for floating-point comparisons.
+
+    Args:
+        got_payload (dict[str, Any]): Output generated by the test run.
+        baseline_payload (dict[str, Any]): Reference baseline output.
+        rtol (float): Relative tolerance for numeric comparisons.
+        atol (float): Absolute tolerance for numeric comparisons.
+
+    Raises:
+        AssertionError: If any mismatches are found between outputs and baseline.
+    """
     got_groups = _group_index(got_payload)
     base_groups = _group_index(baseline_payload)
 
@@ -80,6 +107,23 @@ def _compare_grouped(
 def test_regression_matches_baseline(
     tmp_path: Path, case, request: pytest.FixtureRequest
 ) -> None:
+    """
+    Execute a regression test for a single scenario and compare against baseline.
+
+    This test:
+        1. Loads a YAML configuration for a given system/scenario
+        2. Runs CodeEntropy using that configuration
+        3. Compares the output payload against a stored baseline JSON
+        4. Optionally updates the baseline if --update-baselines is set
+
+    Args:
+        tmp_path (Path): Temporary directory provided by pytest.
+        case (RegressionCase): Parameterized regression case.
+        request (pytest.FixtureRequest): Pytest request object for accessing CLI options.
+
+    Raises:
+        AssertionError: If the output does not match the baseline or baseline is missing.
+    """
     system = case.system
     config_path = case.config_path
     baseline_path = case.baseline_path