feat(directives): harvest 5 directives from docs/guide_testing.md (sandbox overview, live_gui session-scoped, defer-not-catch, narrow tests, AST method visibility)

This commit is contained in:
ed
2026-07-02 23:56:26 -04:00
parent 782530ba6d
commit a758f0a4c9
10 changed files with 99 additions and 0 deletions
@@ -0,0 +1,7 @@
# test_narrow_not_kitchen_sink
## v1
**Why this iteration:** Lifted verbatim from `docs/guide_testing.md:817-829 (§Pattern: Narrow Test Paths)`.
**Source:** `docs/guide_testing.md:817-829 (§Pattern: Narrow Test Paths)`
**Lifted:** 2026-07-02 (Phase A expansion harvest; user directive 2026-07-02)
@@ -0,0 +1,9 @@
## Pattern: Narrow Test Paths vs. Kitchen-Sink Functions
**Anti-pattern: calling a kitchen-sink function.** A test that does `gui_2.render_main_interface(app_instance)` requires mocking 50+ imgui/imscope methods because `render_main_interface` dispatches to dozens of nested render functions. Adding a single mock for `imscope.window` (to return a tuple) just reveals the next un-mocked dependency (e.g. `imgui.begin` returning bool where a 2-tuple is expected). The test never reaches its assertion.
**Better pattern: test the narrow function.** Most render flows have a dedicated sub-function (e.g. `render_prior_session_view`, `render_preset_manager_window`, `render_theme_panel`). Refactor the test to call the narrow function directly with mocks scoped to what that function actually uses.
**When to refactor vs. add mocks:**
- If the test intent is verify push/pop balance in the prior-session render path, call the narrow function.
- If the test intent is verify the whole GUI render path is correct, accept the 50+ mock cost (and ensure all mocks are correct).