OSIT-AE-API-FastAPI/tests/README.md

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

./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.