From 6b2270f811c4c4a2c909115f81d3d9176166c5b2 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 3 Mar 2026 01:13:03 -0500 Subject: [PATCH] docs: Update core documentation with Structural Testing Contract --- Readme.md | 2 ++ conductor/workflow.md | 6 ++++++ docs/guide_simulations.md | 12 +++++++++++- 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/Readme.md b/Readme.md index 887d88e..3d15005 100644 --- a/Readme.md +++ b/Readme.md @@ -99,6 +99,8 @@ uv run gui_2.py --enable-test-hooks # With Hook API on :8999 uv run pytest tests/ -v ``` +> **Note:** See the [Structural Testing Contract](./docs/guide_simulations.md#structural-testing-contract) for rules regarding mock patching, `live_gui` standard usage, and artifact isolation (logs are generated in `tests/logs/` and `tests/artifacts/`). + --- ## Project Configuration diff --git a/conductor/workflow.md b/conductor/workflow.md index 745bdf9..f9c84a7 100644 --- a/conductor/workflow.md +++ b/conductor/workflow.md @@ -212,6 +212,12 @@ Before marking any task complete, verify: ## Testing Requirements +### Structural Testing Contract + +1. **Ban on Arbitrary Core Mocking:** Tier 3 workers are strictly forbidden from using `unittest.mock.patch` to bypass or stub core infrastructure (e.g., event queues, `ai_client` internals, threading primitives) unless explicitly authorized by the Tier 2 Tech Lead for a specific boundary test. +2. **`live_gui` Standard:** All integration and end-to-end testing must utilize the `live_gui` fixture to interact with a real instance of the application via the Hook API. Bypassing the hook server to directly mutate GUI state in tests is prohibited. +3. **Artifact Isolation:** All test-generated artifacts (logs, temporary workspaces, mock outputs) MUST be written to the `tests/artifacts/` or `tests/logs/` directories. These directories are git-ignored to prevent repository pollution. + ### Unit Testing - Every module must have corresponding tests. diff --git a/docs/guide_simulations.md b/docs/guide_simulations.md index 2e235dd..4b3aa73 100644 --- a/docs/guide_simulations.md +++ b/docs/guide_simulations.md @@ -1,4 +1,14 @@ -# Verification & Simulation Framework +## Structural Testing Contract + +To maintain the integrity of the test suite and ensure that AI-driven test modifications do not create false positives ("mock-rot"), the following rules apply to all testing within this project: + +1. **Ban on Arbitrary Core Mocking:** Tier 3 workers are strictly forbidden from using `unittest.mock.patch` to bypass or stub core infrastructure (e.g., event queues, `ai_client` internals, threading primitives) unless explicitly authorized by the Tier 2 Tech Lead for a specific boundary test. +2. **`live_gui` Standard:** All integration and end-to-end testing must utilize the `live_gui` fixture to interact with a real instance of the application via the Hook API. Bypassing the hook server to directly mutate GUI state in tests is prohibited. +3. **Artifact Isolation:** All test-generated artifacts (logs, temporary workspaces, mock outputs) MUST be written to the `tests/artifacts/` or `tests/logs/` directories. These directories are git-ignored to prevent repository pollution. + +--- + +## Verification & Simulation Framework [Top](../Readme.md) | [Architecture](guide_architecture.md) | [Tools & IPC](guide_tools.md) | [MMA Orchestration](guide_mma.md)