Stage 4

Author: tzanko-matev

codetracer-python-recorder/tests/python/__init__.py

@@ -0,0 +1,14 @@
+"""Shared helpers for Python test suites."""
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["ensure_trace_dir"]
+
+
+def ensure_trace_dir(root: Path, name: str = "trace_out") -> Path:
+    """Return an existing trace directory under ``root``, creating it if needed."""
+    target = root / name
+    target.mkdir(exist_ok=True)
+    return target
+

codetracer-python-recorder/tests/python/support/__init__.py

@@ -9,6 +9,8 @@
 
 import codetracer_python_recorder as codetracer
 
+from .support import ensure_trace_dir
+
 
 @dataclass
 class ParsedTrace:
@@ -80,8 +82,7 @@ def _write_script(tmp: Path) -> Path:
 def test_py_start_line_and_return_events_are_recorded(tmp_path: Path) -> None:
     # Arrange: create a script and start tracing with activation restricted to that file
     script = _write_script(tmp_path)
-    out_dir = tmp_path / "trace_out"
-    out_dir.mkdir()
+    out_dir = ensure_trace_dir(tmp_path)
 
     session = codetracer.start(out_dir, format=codetracer.TRACE_JSON, start_on_enter=script)
 
@@ -132,8 +133,7 @@ def test_py_start_line_and_return_events_are_recorded(tmp_path: Path) -> None:
 
 
 def test_start_while_active_raises(tmp_path: Path) -> None:
-    out_dir = tmp_path / "trace_out"
-    out_dir.mkdir()
+    out_dir = ensure_trace_dir(tmp_path)
     session = codetracer.start(out_dir, format=codetracer.TRACE_JSON)
     try:
         with pytest.raises(RuntimeError):

codetracer-python-recorder/tests/python/test_monitoring_events.py

@@ -0,0 +1,122 @@
+"""Unit tests for session helper functions."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from codetracer_python_recorder import session
+
+
+def test_coerce_format_accepts_supported_aliases() -> None:
+    assert session._coerce_format("json") == "json"
+    assert session._coerce_format("JSON") == "json"
+    assert session._coerce_format("binary") == "binary"
+
+
+def test_coerce_format_rejects_unknown_value() -> None:
+    with pytest.raises(ValueError) as excinfo:
+        session._coerce_format("yaml")
+    assert "unsupported trace format" in str(excinfo.value)
+
+
+def test_validate_trace_path_expands_user(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    home_dir = tmp_path / "home"
+    home_dir.mkdir()
+    target = home_dir / "traces"
+
+    monkeypatch.setenv("HOME", str(home_dir))
+    path = session._validate_trace_path(Path("~/traces"))
+
+    assert path == target
+    assert path.parent == home_dir
+
+
+def test_validate_trace_path_rejects_file(tmp_path: Path) -> None:
+    file_path = tmp_path / "trace.bin"
+    file_path.write_text("stub")
+    with pytest.raises(ValueError):
+        session._validate_trace_path(file_path)
+
+
+def test_normalize_activation_path_handles_none() -> None:
+    assert session._normalize_activation_path(None) is None
+
+
+def test_normalize_activation_path_expands_user(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    home_dir = tmp_path / "home"
+    home_dir.mkdir()
+    script = home_dir / "script.py"
+    script.write_text("print('hi')\n")
+
+    monkeypatch.setenv("HOME", str(home_dir))
+    result = session._normalize_activation_path("~/script.py")
+
+    assert result == str(script)
+
+
+@pytest.fixture(autouse=True)
+def clear_active_session() -> None:
+    session._active_session = None
+    yield
+    session._active_session = None
+
+
+def test_trace_session_stop_clears_global(monkeypatch: pytest.MonkeyPatch) -> None:
+    called = {"stop": False, "start": False}
+
+    def fake_start(*args, **kwargs) -> None:
+        called["start"] = True
+
+    def fake_stop() -> None:
+        called["stop"] = True
+
+    monkeypatch.setattr(session, "_start_backend", fake_start)
+    monkeypatch.setattr(session, "_stop_backend", fake_stop)
+    monkeypatch.setattr(session, "_is_tracing_backend", lambda: session._active_session is not None)
+
+    session._active_session = session.TraceSession(path=Path("/tmp"), format="json")
+    session.stop()
+    assert session._active_session is None
+    assert called["stop"] is True
+
+
+def test_trace_session_flush_noop_when_inactive(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(session, "_is_tracing_backend", lambda: False)
+    flushed = []
+
+    def fake_flush() -> None:
+        flushed.append(True)
+
+    monkeypatch.setattr(session, "_flush_backend", fake_flush)
+    session.flush()
+    assert flushed == []
+
+
+def test_trace_context_manager_starts_and_stops(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    calls = {"start": [], "stop": []}
+
+    trace_state = {"active": False}
+
+    def fake_start(path: str, fmt: str, activation: str | None) -> None:
+        trace_state["active"] = True
+        calls["start"].append((Path(path), fmt, activation))
+
+    def fake_stop() -> None:
+        trace_state["active"] = False
+        calls["stop"].append(True)
+
+    monkeypatch.setattr(session, "_start_backend", fake_start)
+    monkeypatch.setattr(session, "_stop_backend", fake_stop)
+    monkeypatch.setattr(session, "_is_tracing_backend", lambda: trace_state["active"])
+    monkeypatch.setattr(session, "_flush_backend", lambda: None)
+
+    target = tmp_path / "trace"
+    target.mkdir()
+    with session.trace(target, format="binary") as handle:
+        assert isinstance(handle, session.TraceSession)
+        assert handle.path == target.expanduser()
+        assert handle.format == "binary"
+
+    assert calls["start"] == [(target, "binary", None)]
+    assert calls["stop"] == [True]

codetracer-python-recorder/tests/python/unit/test_session_helpers.py

@@ -11,11 +11,12 @@
 - ✅ Stage 3 – Activation Guard Rails: added unit tests around
   `ActivationController` covering activation start, non-matching frames, and
   deactivation behaviour; existing runtime integration tests continue to pass.
-- ⏳ Stage 4 – Python Unit Coverage: not started.
+- ✅ Stage 4 – Python Unit Coverage: added `tests/python/unit/test_session_helpers.py`
+  for facade utilities and introduced `tests/python/support` for shared
+  fixtures; updated monitoring tests to use the helper directory builder.
 - ⏳ Stage 5 – CI & Coverage Instrumentation: not started.
 - ⏳ Stage 6 – Cleanup & Documentation: not started.
 
 ## Next Actions
-1. Advance Stage 4 by creating Python unit tests for facade helpers and shared
-   fixtures.
-2. Plan Stage 5 CI split once the new unit coverage lands.
+1. Plan Stage 5 CI split so Rust/Python harness results appear separately.
+2. Draft coverage instrumentation approach before implementation (Stage 5).