Add custom comparison for TickInfo objects for pytest

Testing the ticking behavior is very complicated in itself, and when
there are failures, it is very difficult to understand what is
happening and where the differences between the expected and actual
tick times are.

To help with this, we add a custom comparison for `TickInfo` objects
that provides a detailed report of the differences between the
expected and actual tick times, including the sleep information for
each sleep.

This uses the special `pytest` hook `pytest_assertrepr_compare`:
https://docs.pytest.org/en/stable/reference/reference.html#pytest.hookspec.pytest_assertrepr_compare

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

tests/timeseries/_resampling/wall_clock_timer/conftest.py

@@ -4,13 +4,14 @@
 """Fixtures for wall clock timer tests."""
 
 import asyncio
-from collections.abc import Iterator
-from datetime import datetime
+from collections.abc import Callable, Iterator, Sequence
+from datetime import datetime, timedelta
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from frequenz.core.datetime import UNIX_EPOCH
 
+from frequenz.sdk.timeseries._resampling._wall_clock_timer import ClocksInfo, TickInfo
 
 # Some of the utils do assertions and we want them to be rewritten by pytest for better
 # error messages
@@ -49,3 +50,106 @@ async def time_driver(datetime_mock: MagicMock) -> TimeDriver:
     return TimeDriver(
         datetime_mock=datetime_mock,
     )
+
+
+def pytest_assertrepr_compare(op: str, left: object, right: object) -> list[str] | None:
+    """Provide custom, readable error reports for TickInfo comparisons."""
+    # We only care about == comparisons involving our TickInfo objects, returning None
+    # makes pytest fall back to its default comparison behavior.
+    if op != "==" or not isinstance(left, TickInfo) or not isinstance(right, TickInfo):
+        return None
+
+    # Helper function to format values for readability
+    def format_val(val: object) -> str:
+        # For our time-based types, use str() for readability instead of repr()
+        if isinstance(val, (datetime, timedelta)):
+            return str(val)
+        # For our approx objects and others, the default repr is already good.
+        return repr(val)
+
+    errors = _compare_tick_info_objects(left, right, format_val)
+    # If the comparison was actually successful (no errors), let pytest handle it
+    if not errors:
+        return None
+
+    # Format the final error message
+    report = ["Comparing TickInfo objects:"]
+    report.append("  Differing attributes:")
+    report.append(f"  {list(errors.keys())!r}")
+    report.append("")
+
+    for field, diff in errors.items():
+        report.append(f"  Drill down into differing attribute '{field}':")
+        # The diff can be a simple tuple of (left, right) values or a list of
+        # strings for nested diffs
+        match diff:
+            case list():
+                report.extend(f"    {line}" for line in diff)
+            case (left_val, right_val):
+                report.append(f"    - {format_val(left_val)}")
+                report.append(f"    + {format_val(right_val)}")
+            case _:
+                assert False, f"Unexpected diff type: {type(diff)}"
+
+    return report
+
+
+# We are dealing these fields dynamically, so we make a sanity check here to make sure
+# if something changes, we can catch it early instead of getting some cryptic errors
+# later, deep in the code.
+assert set(TickInfo.__dataclass_fields__.keys()) == {
+    "expected_tick_time",
+    "sleep_infos",
+}
+
+
+def _compare_tick_info_objects(
+    left: TickInfo, right: TickInfo, format_val: Callable[[object], str]
+) -> dict[str, object]:
+    """Compare two TickInfo objects and return a dictionary of differences."""
+    errors: dict[str, object] = {}
+
+    # 1. Compare top-level fields
+    if left.expected_tick_time != right.expected_tick_time:
+        errors["expected_tick_time"] = (
+            left.expected_tick_time,
+            right.expected_tick_time,
+        )
+
+    # 2. Compare the list of ClocksInfo objects
+    sleeps_diff = _compare_sleep_infos_list(
+        left.sleep_infos, right.sleep_infos, format_val
+    )
+    if sleeps_diff:
+        errors["sleep_infos"] = sleeps_diff
+
+    return errors
+
+
+def _compare_sleep_infos_list(
+    left: Sequence[ClocksInfo],
+    right: Sequence[ClocksInfo],
+    format_val: Callable[[object], str],
+) -> list[str]:
+    """Compare two lists of ClocksInfo objects and return a list of error strings."""
+    if len(left) != len(right):
+        return [
+            f"List lengths differ: {len(left)} != {len(right)}",
+            f"                     {left!r}",
+            "                     !=",
+            f"                     {right!r}",
+        ]
+
+    diffs: list[str] = []
+    for i, (l_clock, r_clock) in enumerate(zip(left, right)):
+        if l_clock != r_clock:
+            diffs.append(f"Item at index [{i}] differs:")
+            # Get detailed diffs for the fields inside the ClocksInfo object
+            for field in l_clock.__dataclass_fields__:
+                l_val = getattr(l_clock, field)
+                r_val = getattr(r_clock, field)
+                if l_val != r_val:
+                    diffs.append(f"  Attribute '{field}':")
+                    diffs.append(f"    - {format_val(l_val)}")
+                    diffs.append(f"    + {format_val(r_val)}")
+    return diffs