From 1bbe5cc31f96ddc92691da524ef90c9f5b0bcce3 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Fri, 16 Jan 2026 11:12:17 -0500
Subject: [PATCH] Tests: Add README and fix diagnosis script paths

---
 tests/README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 tests/README.md

diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..6a7e899
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,71 @@
+# Aether API Test Suite
+
+This directory contains the automated and manual test scripts for the Aether FastAPI backend. The suite is organized by execution environment and scope to ensure a reliable development workflow.
+
+## 📁 Directory Structure
+
+- **`unit/`**: Isolated logic tests. These use heavy mocking to bypass database and network requirements. Fast and safe to run in any environment.
+- **`integration/`**: Local environment tests. These require a connection to the local MariaDB/Redis instance and verify how components interact.
+- **`e2e/` (End-to-End)**: Network-based API tests. these use the `requests` library to call the live API endpoints at `https://dev-api.oneskyit.com`.
+- **`tools/`**: Utility scripts for administrative tasks like registry generation or Docker exploration.
+- **`archive/`**: Legacy or deprecated scripts kept for historical reference.
+
+## 🛠️ Shared Helpers
+
+- **`mock_config_helper.py`**: A critical utility that mocks `app.config.settings` before other modules are imported. Use this in unit tests to prevent the application from trying to load real configuration files during import.
+
+---
+
+## 📜 Script Inventory
+
+### Unit Tests (`tests/unit/`)
+| Script | Description |
+| :--- | :--- |
+| `test_unit_email.py` | Unit tests for email logic with full SMTP mocking. |
+| `test_unit_email_safe.py` | Secondary safe-mode email verification logic. |
+| `test_unit_errors.py` | Verifies the regex-based SQL error string cleanup logic. |
+| `test_unit_filtering.py` | Ensures virtual/view fields are correctly marked for DB exclusion. |
+| `test_unit_models.py` | Validates custom Pydantic validators (e.g., Person given_name). |
+| `test_unit_payload_sanitization.py` | **Primary Logic Test**: Verifies payload stripping and ID resolution. |
+| `test_unit_router_stripping.py` | Simulates automatic removal of random IDs during updates. |
+| `test_unit_schema_logic.py` | Verifies V3 schema metadata extraction logic with mocked DB rows. |
+
+### Integration Tests (`tests/integration/`)
+| Script | Description |
+| :--- | :--- |
+| `test_int_boot_diagnosis.py` | Progressively imports modules to identify circular dependency traps. |
+| `test_int_db_connectivity.py` | Direct SQLAlchemy connectivity test (bypasses app config). |
+| `test_int_email_live.py` | Live SMTP connection test (non-mocked). |
+| `test_int_import_verification.py` | Basic check that all V3 routers are reachable. |
+| `test_int_schema_v3.py` | Verifies the enhanced schema discovery output against the real DB. |
+| `test_int_v3_auth_security.py` | Uses `TestClient` to verify auth bypass rules (Site vs Account). |
+
+### E2E Tests (`tests/e2e/`)
+| Script | Description |
+| :--- | :--- |
+| `test_e2e_agent_bridge.py` | Verifies the `/agent` diagnostics and log streaming endpoints. |
+| `test_e2e_legacy_remote_schema.py` | Remote check for legacy schema compatibility. |
+| `test_e2e_site_bootstrap.py` | Verifies the unauthenticated FQDN lookup for site initialization. |
+| `test_e2e_v3_accounts.py` | CRUD verification for the Account object via network. |
+| `test_e2e_v3_extra_filters.py` | Tests complex filtering (enabled/all) on User and Site objects. |
+| `test_e2e_v3_schema.py` | Validates the V3 `/schema` endpoint over the network. |
+| `test_e2e_v3_search.py` | **Primary API Test**: Verifies all search operators and JWT auth. |
+| `test_e2e_v3_security_exceptions.py` | Validates that restricted routes correctly return 403 Forbidden. |
+
+### Tools (`tests/tools/`)
+| Script | Description |
+| :--- | :--- |
+| `tool_generate_registry.py` | Exports the Aether object registry (`obj_type_kv_li`) as JSON. |
+| `tool_mcp_docker_explorer.py` | Model Context Protocol tool for Docker container inspection. |
+
+---
+
+## 🚀 How to Run
+
+### Recommended: Use the project virtual environment
+```bash
+./environment/bin/python3 tests/unit/test_unit_payload_sanitization.py
+```
+
+### Path Requirements
+Always run test scripts from the **project root** directory. Most scripts include `sys.path.append(os.getcwd())` to ensure local imports work correctly.