| 1 | # Tests DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own pytest regression, security, integration, and contract tests. |
| 6 | - Keep tests focused on behavior that should remain stable across framework changes. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Test files live directly under `tests/` and are named for the behavior or subsystem they cover. |
| 11 | - Shared fixtures should be added only when multiple tests need them. |
| 12 | - Runtime artifacts created during tests should use pytest temporary directories or existing isolated test helpers. |
| 13 | |
| 14 | ## Local Contracts |
| 15 | |
| 16 | - Tests must not require real API keys, network-only services, private user data, or local `usr/` runtime state. |
| 17 | - Keep tests deterministic and isolated from existing chats, uploads, downloads, plugin state, and settings. |
| 18 | - Prefer exercising public helper/API contracts over fragile implementation details when practical. |
| 19 | - Security regression tests should assert the protected behavior directly. |
| 20 | - Launcher gateway tests must cover feature negotiation, authenticated and |
| 21 | CSRF-protected control, acknowledgement timeout, identity lifecycle, |
| 22 | context-bound CLI routing precedence, duplicate/multiple-host behavior, |
| 23 | scope-driven availability, and emergency disconnect without a live host. |
| 24 | |
| 25 | ## Work Guidance |
| 26 | |
| 27 | - Add focused tests near the affected subsystem's existing tests. |
| 28 | - Use descriptive test names that state the regression or contract. |
| 29 | - Avoid broad sleeps or real-time dependencies; use monkeypatching or controlled clocks where possible. |
| 30 | |
| 31 | ## Verification |
| 32 | |
| 33 | - Run `pytest` for broad changes. |
| 34 | - Run `pytest tests/test_name.py` for narrow changes and mention any broader test gaps at closeout. |
| 35 | |
| 36 | ## Child DOX Index |
| 37 | |
| 38 | No child DOX files. |