milo-cli 0.1.0__py3-none-any.whl

milo/testing/_record.py

@@ -0,0 +1,125 @@
+"""Session recording — action log writer."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from milo._types import Action
+
+
+@dataclass(frozen=True, slots=True)
+class ActionRecord:
+    """Single recorded action with timestamp."""
+
+    timestamp: float
+    action: Action
+    state_hash: str
+
+
+@dataclass(frozen=True, slots=True)
+class SessionRecording:
+    """Complete recorded session."""
+
+    initial_state: Any
+    records: tuple[ActionRecord, ...]
+    final_state: Any
+    metadata: dict[str, str]
+
+
+def state_hash(state: Any) -> str:
+    """SHA256 hash of state repr, truncated to 16 chars."""
+    return hashlib.sha256(repr(state).encode()).hexdigest()[:16]
+
+
+def recording_middleware(
+    records: list[dict],
+) -> Any:
+    """Create a middleware that records actions and state hashes."""
+
+    def middleware(dispatch: Any, get_state: Any) -> Any:
+        def recording_dispatch(action: Action) -> None:
+            dispatch(action)
+            records.append(
+                {
+                    "timestamp": time.time(),
+                    "action_type": action.type,
+                    "action_payload": action.payload,
+                    "state_hash": state_hash(get_state()),
+                }
+            )
+
+        return recording_dispatch
+
+    return middleware
+
+
+def save_recording(
+    path: str | Path,
+    initial_state: Any,
+    records: list[dict],
+    final_state: Any,
+    metadata: dict[str, str] | None = None,
+) -> None:
+    """Save a session recording to JSONL."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with path.open("w") as f:
+        # Header
+        header = {
+            "type": "header",
+            "initial_state": repr(initial_state),
+            "metadata": metadata or {},
+        }
+        f.write(json.dumps(header) + "\n")
+
+        # Records
+        for record in records:
+            record_data = {"type": "action", **record}
+            # Convert non-serializable payloads
+            if "action_payload" in record_data:
+                try:
+                    json.dumps(record_data["action_payload"])
+                except TypeError, ValueError:
+                    record_data["action_payload"] = repr(record_data["action_payload"])
+            f.write(json.dumps(record_data) + "\n")
+
+        # Footer
+        footer = {
+            "type": "footer",
+            "final_state": repr(final_state),
+        }
+        f.write(json.dumps(footer) + "\n")
+
+
+def load_recording(path: str | Path) -> SessionRecording:
+    """Load a session recording from JSONL."""
+    path = Path(path)
+    lines = path.read_text().strip().split("\n")
+
+    header = json.loads(lines[0])
+    footer = json.loads(lines[-1])
+
+    records = []
+    for line in lines[1:-1]:
+        data = json.loads(line)
+        if data["type"] == "action":
+            records.append(
+                ActionRecord(
+                    timestamp=data["timestamp"],
+                    action=Action(data["action_type"], data.get("action_payload")),
+                    state_hash=data["state_hash"],
+                )
+            )
+
+    return SessionRecording(
+        initial_state=header.get("initial_state"),
+        records=tuple(records),
+        final_state=footer.get("final_state"),
+        metadata=header.get("metadata", {}),
+    )

milo/testing/_replay.py

@@ -0,0 +1,68 @@
+"""Action log replay (time-travel)."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from milo._types import Action, ReducerResult
+from milo.testing._record import SessionRecording, load_recording, state_hash
+
+
+def replay(
+    recording: SessionRecording | str | Path,
+    reducer: Callable,
+    *,
+    speed: float = 1.0,
+    step: bool = False,
+    on_state: Callable | None = None,
+    assert_hashes: bool = False,
+) -> Any:
+    """Replay a recorded session through a reducer.
+
+    Returns final state. Optionally asserts state_hash matches
+    at each step to detect reducer regressions.
+    """
+    if isinstance(recording, (str, Path)):
+        recording = load_recording(recording)
+
+    state = None
+    prev_time = None
+
+    # Init
+    result = reducer(state, Action("@@INIT"))
+    state = result.state if isinstance(result, ReducerResult) else result
+
+    for record in recording.records:
+        # Timing
+        if prev_time is not None and speed > 0 and not step:
+            delay = (record.timestamp - prev_time) / speed
+            if delay > 0:
+                time.sleep(delay)
+
+        prev_time = record.timestamp
+
+        # Apply action
+        result = reducer(state, record.action)
+        state = result.state if isinstance(result, ReducerResult) else result
+
+        # Hash check
+        if assert_hashes:
+            actual_hash = state_hash(state)
+            if actual_hash != record.state_hash:
+                raise AssertionError(
+                    f"State hash mismatch at action {record.action.type}: "
+                    f"expected {record.state_hash}, got {actual_hash}"
+                )
+
+        # Callback
+        if on_state is not None:
+            on_state(state, record.action)
+
+        # Step mode
+        if step:
+            input("Press Enter to continue...")
+
+    return state

milo/testing/_snapshot.py

@@ -0,0 +1,96 @@
+"""Snapshot capture and comparison."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from text."""
+    return re.sub(r"\x1b\[[0-9;]*[a-zA-Z]", "", text)
+
+
+def assert_renders(
+    state: Any,
+    template: str | Any,
+    *,
+    snapshot: str | Path | None = None,
+    width: int = 80,
+    color: bool = False,
+    update: bool = False,
+    env: Any = None,
+) -> str:
+    """Render state through template, assert output matches snapshot.
+
+    If snapshot is None, returns rendered string.
+    If snapshot is a path and doesn't exist, creates it.
+    If update=True, overwrites on mismatch.
+    """
+    if env is None:
+        from milo.templates import get_env
+
+        env = get_env()
+
+    tmpl = env.get_template(template) if isinstance(template, str) else template
+
+    rendered = tmpl.render(state=state)
+
+    if not color:
+        rendered = strip_ansi(rendered)
+
+    if snapshot is None:
+        return rendered
+
+    snap_path = Path(snapshot)
+    should_update = update or os.environ.get("MILO_UPDATE_SNAPSHOTS") == "1"
+
+    if not snap_path.exists() or should_update:
+        snap_path.parent.mkdir(parents=True, exist_ok=True)
+        snap_path.write_text(rendered)
+        return rendered
+
+    expected = snap_path.read_text()
+    if rendered != expected:
+        raise AssertionError(
+            f"Snapshot mismatch: {snap_path}\n"
+            f"--- expected ---\n{expected}\n"
+            f"--- actual ---\n{rendered}"
+        )
+
+    return rendered
+
+
+def assert_state(
+    reducer: Any,
+    initial: Any,
+    actions: list | tuple,
+    expected: Any,
+) -> None:
+    """Feed actions through reducer, assert final state matches."""
+    from milo._types import ReducerResult
+
+    state = initial
+    for action in actions:
+        result = reducer(state, action)
+        state = result.state if isinstance(result, ReducerResult) else result
+
+    assert state == expected, f"State mismatch:\n  expected: {expected}\n  actual: {state}"
+
+
+def assert_saga(
+    saga: Any,
+    steps: list[tuple[Any, Any]],
+) -> None:
+    """Step through saga, assert each yielded effect matches."""
+    effect = next(saga)
+    for expected_effect, send_value in steps:
+        assert effect == expected_effect, (
+            f"Effect mismatch:\n  expected: {expected_effect}\n  actual: {effect}"
+        )
+        try:
+            effect = saga.send(send_value)
+        except StopIteration:
+            return