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 verify component interactions, often requiring a connection to the local MariaDB/Redis instance.
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.

📜 Standardized E2E Suite (`tests/e2e/`)

These consolidated scripts are the primary verification tool for the V3 API.

Script	Description
`test_e2e_v3_search_engine.py`	Primary Search: Basic operators, Registry fields, Nested search, and Filter bypass.
`test_e2e_v3_auth_security.py`	Primary Auth: Site bootstrap, Passcode-to-JWT, and permission boundaries.
`test_e2e_v3_actions_file_lifecycle.py`	Primary Actions: Upload, Download (ID/Hash/Streaming), and physical Deletion.
`test_e2e_v3_data_store_lookup.py`	V3 Parity: Verifies code-based lookups and latency simulation.
`test_e2e_redis_extensive.py`	Redis Stress: Benchmarks bidirectional ID caching across thousands of records.
`test_e2e_v3_event_vision_parity.py`	Vision ID: Verifies string-ID enforcement across event models.
`test_e2e_v3_cms_vision_parity.py`	Vision ID: Verifies string-ID enforcement across CMS (post/comment) models.
`test_e2e_v3_demo_parity.py`	Demo Parity: Comprehensive check for Badge, Exhibit, Tracking, and nested Journal Entries.
`test_e2e_v3_action_event_file.py`	Event Actions: Specialized atomic upload and linking for event files.
`test_e2e_v3_action_zoom.py`	Zoom Integration: Verifies OAuth and ticket sync logic for Zoom Events.
`test_e2e_v3_accounts.py`	CRUD verification for the core Account object.
`test_e2e_v3_schema.py`	Network verification of the V3 metadata discovery endpoint.
`test_e2e_agent_bridge.py`	Verifies container diagnostics and log streaming routes.
`cleanup_test_files.py`	Utility to purge E2E artifacts from physical storage.

🛠️ Shared Helpers

mock_config_helper.py: A critical utility that mocks app.config.settings before other modules are imported. Use this in unit tests.

🧹 Maintenance Policy

Standardization: All E2E tests should use the standard Agent API Key (PMM4n50teUCaOMMTN8qOJA) and provide clean [✅ PASS] or [❌ FAIL] output.
Archiving: When a new specialized test is created, check if it can be combined into one of the "Primary" suites above. If so, combine and move the original to archive/.
Cleanup: Always use tests/e2e/cleanup_test_files.py after running file lifecycle tests.

🛠️ Standards & Patterns

To maintain a "nice" and readable test suite, follow these patterns in all new Python E2E scripts:

Helper Functions: Use a print_result(label, success, message="") helper to output standardized ✅ PASS and ❌ FAIL status lines.
Functional Isolation: Wrap test scenarios in descriptive functions (e.g., test_hierarchical_fallback()) rather than writing monolithic scripts.
Vision Compliance: Always verify that IDs in the response are strings (Random IDs) and not integers, to ensure "ID Vision" is working.
Performance Logging: Include a suite timer at the end of the if __name__ == "__main__": block to track execution speed.
Clean Environment: Do not leave temporary debug or local-only scripts in the e2e/ directory.

🚀 How to Run

Recommended: Use the project virtual environment

./environment/bin/python3 tests/e2e/test_e2e_v3_search_engine.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.

README.md