manual_slop/conductor/tracks/test_engine_integration_20260627/metadata.json

{
 "track_id": "test_engine_integration_20260627",
 "name": "ImGui Test Engine Integration (Bridge via API Hooks)",
 "status": "active",
 "branch": "master",
 "created": "2026-06-27",
 "owner": "Tier 1 (initialized); implementation delegated to Tier 2/3.",
 "blocked_by": [],
 "blocks": ["test_engine_docking_tests (Track 2)", "test_engine_capture_regression (Track 3)"],
 "scope": {
  "new_files": [
   "tests/test_test_engine_smoke.py",
   "docs/reports/TRACK_COMPLETION_test_engine_integration_20260627.md"
  ],
  "modified_files": [
   "sloppy.py (add --enable-test-engine CLI flag)",
   "src/app_controller.py (add test_engine_enabled field)",
   "src/gui_2.py (enable engine in App.run + _register_imgui_tests method)",
   "src/api_hooks.py (4 new /api/test_engine/* endpoints)",
   "src/api_hook_client.py (4 new client methods)",
   "tests/conftest.py (pass --enable-test-engine in live_gui fixture)",
   "conductor/tracks.md (add row)",
   "conductor/chronology.md (prepend row)"
  ],
  "deleted_files": []
 },
 "estimated_effort": {
  "method": "scope (per workflow.md Tier 1 Track Initialization Rules. NO day estimates.)",
  "phase_1": "4 tasks: 1 failing test + 1 CLI flag + 1 engine enable + 1 manual verification",
  "phase_2": "4 tasks: 1 failing tests + 4 endpoints + 4 client methods + green verification",
  "phase_3": "2 tasks: 1 conftest update + 1 full smoke test verification",
  "phase_4": "3 tasks: 1 end-of-track report + 1 state update + 1 user sign-off"
 },
 "verification_criteria": [
  "G1: sloppy.py accepts --enable-test-engine; when set, runner_params.use_imgui_test_engine = True + callbacks.register_tests assigned",
  "G2: App._register_imgui_tests exists + registers at least 1 smoke test via imgui.test_engine.register_test",
  "G3: HookServer has 4 new /api/test_engine/* endpoints (queue, status, results, abort)",
  "G4: ApiHookClient has 4 new methods (queue_test, get_test_status, get_test_results, wait_for_test_results)",
  "G5: live_gui fixture passes --enable-test-engine in subprocess args",
  "G6: tests/test_test_engine_smoke.py has >=3 tests; all pass (engine enabled + queue+run smoke + results shape)",
  "G7: docs/reports/TRACK_COMPLETION_test_engine_integration_20260627.md exists; documents threading model verification + Track 2 handoff",
  "VC_parallel_safe": "ZERO file overlap with tier2/post_module_taxonomy_de_cruft_20260627 (touching sloppy.py, gui_2.py:641-700, api_hooks.py, api_hook_client.py, conftest.py — none of which Tier 2 touches) or enforcement_gap_closure_20260627 (touching scripts/audit_*, python.md — zero overlap)"
 ],
 "regressions_and_pre_existing_failures": [],
 "pre_existing_failures_remaining": [],
 "deferred_to_followup_tracks": [
  {
   "title": "Track 2: test_engine_docking_tests",
   "description": "Migrate docking/focus/panel tests (test_workspace_profiles_restoration, test_auto_switch_sim, etc.) to use ctx.dock_into, ctx.window_focus, ctx.window_resize. The bridge built in this track enables it.",
   "track_status": "planned (Track 2 of 3)"
  },
  {
   "title": "Track 3: test_engine_capture_regression",
   "description": "Visual regression via ctx.capture_screenshot_window + baseline PNG diff. The capture API is available but not wired in this track.",
   "track_status": "planned (Track 3 of 3)"
  },
  {
   "title": "Headless test execution",
   "description": "The test engine requires a live GLFW window. Headless mode (no window) is a future research item; the engine's scenario thread drives the actual render loop.",
   "track_status": "not yet initialized; research item"
  },
  {
   "title": "Interactive test engine panel",
   "description": "show_test_engine_windows(engine, True) opens the engine's debug UI. Not shown by default; can be added as a debug toggle in a follow-up.",
   "track_status": "not yet initialized"
  }
 ],
 "risk_register": [
  {
   "id": "R1",
   "description": "GIL-transfer crash: the test engine's scenario thread calls Python test_func from a different thread; if the GIL transfer mechanism in hello_imgui/immapp doesn't work with the app's existing thread layout, the app crashes",
   "likelihood": "medium",
   "impact": "hard blocker; the entire test engine approach is invalid if the threading model doesn't work",
   "mitigation": "Phase 1 Task 1.4 is a manual verification checkpoint that catches this before any further work. If it crashes, STOP and report to user. The demo_testengine.py proves the mechanism works for simple apps; the risk is specific to this app's thread layout (AppController, SyncEventQueue, etc.)"
  },
  {
   "id": "R2",
   "description": "Label path mismatch: the smoke test's ctx.set_ref('###manual slop') + ctx.item_click('**/Session') may not match the actual label tree",
   "likelihood": "high",
   "impact": "smoke test fails with 'item not found'; not a crash, just a wrong path",
   "mitigation": "Use imgui.show_id_stack_tool_window() or ctx.window_info() to find the correct labels during implementation. The label tree is deterministic (same build, same layout). Once found, the path is stable."
  },
  {
   "id": "R3",
   "description": "Engine overhead degrades live_gui test performance",
   "likelihood": "low",
   "impact": "live_gui tests take longer; batch run exceeds timeout",
   "mitigation": "The engine is idle when no tests are queued (sub-ms per-frame overhead). The existing fps_idling settings are unchanged. If measurable, the --enable-test-engine flag can be made conditional (only passed when running test_test_engine_* files)."
  },
  {
   "id": "R4",
   "description": "test_func accesses App state from the scenario thread, causing a race with the GUI render thread",
   "likelihood": "medium",
   "impact": "intermittent test failures or state corruption",
   "mitigation": "The spec FR2 + plan Task 1.3 explicitly document: test_func must NOT directly mutate App/AppController state; it must use ctx.* primitives (which post simulated input to the GUI thread). Reading via ctx.item_info / ctx.window_info is safe (C++ accessors). CHECK() runs on the scenario thread but only writes to the engine's C++ result log (thread-safe)."
  }
 ],
 "campaign": {
  "name": "Test Engine Campaign (3 tracks)",
  "tracks": [
   "test_engine_integration_20260627 (THIS TRACK; bridge + smoke test)",
   "test_engine_docking_tests (Track 2; migrate docking/focus/panel tests)",
   "test_engine_capture_regression (Track 3; visual regression via screenshot capture)"
  ],
  "campaign_rationale": "The test engine enables high-fidelity simulation of docking, focus, panel visibility, drag-and-drop, and keyboard input that the current Hook API cannot express. The campaign is split into 3 tracks to isolate risk: Track 1 proves the threading model + bridge work; Track 2 migrates the high-value docking tests; Track 3 adds visual regression. Each track is independently shippable."
 }
}