aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/copier-aegis-project/{{ project_slug }}/tests/api/test_health_endpoints.py.jinja

@@ -0,0 +1,262 @@
+"""
+Tests for health API endpoints.
+
+These tests focus on the HTTP endpoints that CLI health commands call,
+ensuring API responses match expected CLI input format and handle errors correctly.
+"""
+
+from collections.abc import AsyncIterator
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from app.integrations.main import create_integrated_app
+
+
+class TestHealthEndpoints:
+    """Test health API endpoints with various component states."""
+
+    @pytest.fixture
+    async def async_client(self) -> AsyncIterator[AsyncClient]:
+        """Async HTTP client for testing."""
+        app = create_integrated_app()
+
+        # Manually trigger startup for health check registration
+        from app.components.backend.hooks import backend_hooks
+        await backend_hooks.discover_lifespan_hooks()
+        await backend_hooks.execute_startup_hooks()
+
+        transport = ASGITransport(app=app)
+        async with AsyncClient(
+            transport=transport, base_url="http://test"
+        ) as client:
+            yield client
+
+        # Clean up after test
+        await backend_hooks.execute_shutdown_hooks()
+
+    @pytest.mark.asyncio
+    async def test_basic_health_endpoint_accessible(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /health/ endpoint is accessible."""
+        response = await async_client.get("/health/")
+
+        # Should return a valid response (200 for healthy, 503 for unhealthy)
+        assert response.status_code in [200, 503]
+        data = response.json()
+
+        # Verify response structure matches HealthResponse model
+        assert "healthy" in data
+        assert "status" in data
+        assert "components" in data
+        assert "timestamp" in data
+
+        # Verify components are included
+        assert isinstance(data["components"], dict)
+
+    @pytest.mark.asyncio
+    async def test_detailed_health_endpoint_accessible(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /health/detailed endpoint is accessible."""
+        response = await async_client.get("/health/detailed")
+
+        # Should return a valid response
+        assert response.status_code in [200, 503]
+        data = response.json()
+
+        if response.status_code == 200:
+            # Verify response structure matches DetailedHealthResponse model
+            assert "healthy" in data
+            assert "status" in data
+            assert "service" in data
+            assert "version" in data
+            assert "components" in data
+            assert "system_info" in data
+            assert "timestamp" in data
+            assert "healthy_components" in data
+            assert "unhealthy_components" in data
+            assert "health_percentage" in data
+        else:
+            # For 503 responses, check error structure
+            assert "detail" in data
+
+    @pytest.mark.asyncio
+    async def test_health_endpoints_json_format(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that health endpoints return valid JSON for CLI consumption."""
+
+        # Test both endpoints
+        endpoints = ["/health/", "/health/detailed"]
+
+        for endpoint in endpoints:
+            response = await async_client.get(endpoint)
+            assert response.status_code in [200, 503]
+
+            # Should be valid JSON
+            data = response.json()
+            assert isinstance(data, dict)
+
+            # Should have basic health information
+            if response.status_code == 200:
+                assert isinstance(data.get("healthy"), bool)
+                assert isinstance(data.get("components"), dict)
+            elif response.status_code == 503:
+                # Error response should have detail
+                assert "detail" in data
+
+    @pytest.mark.asyncio
+    async def test_health_endpoint_component_structure(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that component structure is suitable for CLI tree display."""
+
+        response = await async_client.get("/health/detailed")
+        assert response.status_code in [200, 503]
+
+        data = response.json()
+
+        if response.status_code == 200:
+            components = data["components"]
+
+            # Should have aegis root component
+            assert "aegis" in components
+            aegis_component = components["aegis"]
+
+            # Aegis component should have required fields for CLI display
+            assert "name" in aegis_component
+            assert "healthy" in aegis_component
+            assert "message" in aegis_component
+
+            # Should have sub-components for tree structure
+            if "sub_components" in aegis_component:
+                sub_components = aegis_component["sub_components"]
+                assert isinstance(sub_components, dict)
+
+                # Each sub-component should have required fields
+                for comp_name, comp_data in sub_components.items():
+                    assert "name" in comp_data
+                    assert "healthy" in comp_data
+                    assert "message" in comp_data
+
+{%- if include_worker %}
+
+    @pytest.mark.asyncio
+    async def test_worker_component_appears_in_health_response(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that worker component appears in health responses when included."""
+
+        response = await async_client.get("/health/detailed")
+        assert response.status_code in [200, 503]
+
+        data = response.json()
+
+        if response.status_code == 200:
+            components = data["components"]
+
+            # Should have aegis root component
+            assert "aegis" in components
+            aegis_component = components["aegis"]
+
+            if "sub_components" in aegis_component:
+                sub_components = aegis_component["sub_components"]
+
+                # Check if using grouped structure
+                if "components" in sub_components:
+                    components_group = sub_components["components"]
+                    if "sub_components" in components_group:
+                        worker_component = components_group["sub_components"].get(
+                            "worker"
+                        )
+                else:
+                    # Legacy direct structure
+                    worker_component = sub_components.get("worker")
+
+                available_components = (
+                    list(sub_components.keys())
+                    if "components" not in sub_components
+                    else list(components_group.get("sub_components", {}).keys())
+                )
+                assert worker_component is not None, (
+                    f"Worker component missing from health response. "
+                    f"Available: {available_components}"
+                )
+
+                # Worker component should have required structure
+                assert "name" in worker_component
+                assert worker_component["name"] == "worker"
+                assert "healthy" in worker_component
+                assert "message" in worker_component
+                assert isinstance(worker_component["healthy"], bool)
+
+                # Worker should have queue sub-components
+                if "sub_components" in worker_component:
+                    worker_sub_components = worker_component["sub_components"]
+
+                    # Should have queues component
+                    if "queues" in worker_sub_components:
+                        queues_component = worker_sub_components["queues"]
+                        assert "name" in queues_component
+                        assert "healthy" in queues_component
+                        assert "message" in queues_component
+
+                        # Check for individual queue health if available
+                        if "sub_components" in queues_component:
+                            queue_sub_components = queues_component["sub_components"]
+
+                            # Should have system and load_test queues
+                            for queue_name in ["system", "load_test"]:
+                                if queue_name in queue_sub_components:
+                                    queue_comp = queue_sub_components[queue_name]
+                                    assert "name" in queue_comp
+                                    assert "healthy" in queue_comp
+                                    assert "message" in queue_comp
+
+                                    # Verify queue metadata exists
+                                    if "metadata" in queue_comp:
+                                        metadata = queue_comp["metadata"]
+                                        assert "queue_type" in metadata
+                                        assert metadata["queue_type"] == queue_name
+
+    @pytest.mark.asyncio
+    async def test_basic_health_includes_worker_in_components(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that basic health endpoint includes worker in components dict."""
+
+        response = await async_client.get("/health/")
+        assert response.status_code in [200, 503]
+
+        data = response.json()
+
+        if response.status_code == 200:
+            components = data["components"]
+
+            # Should have aegis root component with worker
+            assert "aegis" in components
+            aegis_component = components["aegis"]
+
+            if "sub_components" in aegis_component:
+                sub_components = aegis_component["sub_components"]
+
+                # Check if using grouped structure
+                if "components" in sub_components:
+                    components_group = sub_components["components"]
+                    if "sub_components" in components_group:
+                        worker_component = components_group["sub_components"].get(
+                            "worker"
+                        )
+                else:
+                    # Legacy direct structure
+                    worker_component = sub_components.get("worker")
+
+                assert worker_component is not None, (
+                    "Worker component should appear in basic health response"
+                )
+                assert worker_component["name"] == "worker"
+                assert isinstance(worker_component["healthy"], bool)
+
+{%- endif %}

aegis/templates/copier-aegis-project/{{ project_slug }}/tests/api/test_scheduler_endpoints.py.jinja

@@ -0,0 +1,214 @@
+{%- if scheduler_backend != "memory" %}
+"""
+Tests for scheduler API endpoints.
+
+These tests focus on the HTTP endpoints for scheduled task management,
+ensuring API responses match expected format and handle errors correctly.
+"""
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from unittest.mock import AsyncMock, patch
+from httpx import AsyncClient, ASGITransport
+
+from app.integrations.main import create_integrated_app
+from app.services.scheduler.models import ScheduledTask, TaskStatistics
+
+
+class TestSchedulerEndpoints:
+    """Test scheduler API endpoints with various states."""
+
+    @pytest.fixture
+    async def async_client(self) -> AsyncGenerator[AsyncClient, None]:
+        """Async HTTP client for testing."""
+        app = create_integrated_app()
+
+        # Manually trigger startup for component registration
+        from app.components.backend.hooks import backend_hooks
+        await backend_hooks.discover_lifespan_hooks()
+        await backend_hooks.execute_startup_hooks()
+
+        transport = ASGITransport(app=app)
+        async with AsyncClient(
+            transport=transport, base_url="http://test"
+        ) as client:
+            yield client
+
+        # Clean up after test
+        await backend_hooks.execute_shutdown_hooks()
+
+    @pytest.mark.asyncio
+    async def test_list_scheduled_jobs_endpoint_accessible(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /api/v1/scheduler/jobs endpoint is accessible."""
+        response = await async_client.get("/api/v1/scheduler/jobs")
+
+        # Should return a valid response (200 for success, 503 for unavailable,
+        # 500 for dependency issues)
+        assert response.status_code in [200, 500, 503]
+        data = response.json()
+
+        if response.status_code == 200:
+            # Verify response structure matches ScheduledTaskListResponse
+            assert "tasks" in data
+            assert "total_count" in data
+            assert isinstance(data["tasks"], list)
+            assert isinstance(data["total_count"], int)
+        elif response.status_code == 503:
+            # 503 when scheduler unavailable
+            assert "detail" in data
+            assert "scheduler_unavailable" in data["detail"].get("error", "")
+        elif response.status_code == 500:
+            # 500 for dependency/internal issues
+            assert "detail" in data
+            assert "internal_error" in data["detail"].get("error", "")
+
+    @pytest.mark.asyncio
+    async def test_get_scheduled_job_not_found(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /api/v1/scheduler/jobs/{job_id} returns 404 for non-existent job."""
+        response = await async_client.get("/api/v1/scheduler/jobs/non_existent_job")
+
+        # Should return 404 for non-existent job, 503 if scheduler unavailable,
+        # or 500 for dependency issues
+        assert response.status_code in [404, 500, 503]
+        data = response.json()
+
+        assert "detail" in data
+        if response.status_code == 404:
+            assert "job_not_found" in data["detail"].get("error", "")
+        elif response.status_code == 503:
+            assert "scheduler_unavailable" in data["detail"].get("error", "")
+        elif response.status_code == 500:
+            assert "internal_error" in data["detail"].get("error", "")
+
+    @pytest.mark.asyncio
+    async def test_scheduler_statistics_endpoint_accessible(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /api/v1/scheduler/statistics endpoint is accessible."""
+        response = await async_client.get("/api/v1/scheduler/statistics")
+
+        # Should return a valid response (200 for success, 503 for unavailable,
+        # 500 for dependency issues)
+        assert response.status_code in [200, 500, 503]
+        data = response.json()
+
+        if response.status_code == 200:
+            # Verify response structure matches ScheduledTaskStatisticsResponse
+            assert "statistics" in data
+            stats = data["statistics"]
+            assert "total_tasks" in stats
+            assert "active_tasks" in stats
+            assert "paused_tasks" in stats
+            assert isinstance(stats["total_tasks"], int)
+            assert isinstance(stats["active_tasks"], int)
+            assert isinstance(stats["paused_tasks"], int)
+        elif response.status_code == 503:
+            # 503 when scheduler unavailable
+            assert "detail" in data
+            assert "scheduler_unavailable" in data["detail"].get("error", "")
+        elif response.status_code == 500:
+            # 500 for dependency/internal issues
+            assert "detail" in data
+            assert "internal_error" in data["detail"].get("error", "")
+
+    @pytest.mark.asyncio
+    async def test_scheduler_endpoints_return_proper_content_type(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test all scheduler endpoints return JSON content type."""
+        endpoints = [
+            "/api/v1/scheduler/jobs",
+            "/api/v1/scheduler/jobs/test_job",
+            "/api/v1/scheduler/statistics"
+        ]
+
+        for endpoint in endpoints:
+            response = await async_client.get(endpoint)
+            assert "application/json" in response.headers.get("content-type", "")
+
+    @pytest.mark.asyncio
+    async def test_scheduler_job_detail_response_structure(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test job detail response has correct structure when job exists."""
+        # Try to get any existing job first
+        list_response = await async_client.get("/api/v1/scheduler/jobs")
+
+        if list_response.status_code == 200:
+            data = list_response.json()
+            tasks = data.get("tasks", [])
+
+            if tasks:
+                # Test detail endpoint with first available job
+                job_id = tasks[0]["job_id"]
+                url = f"/api/v1/scheduler/jobs/{job_id}"
+                detail_response = await async_client.get(url)
+
+                if detail_response.status_code == 200:
+                    detail_data = detail_response.json()
+                    assert "task" in detail_data
+
+                    task = detail_data["task"]
+                    # Verify task structure matches ScheduledTask model
+                    required_fields = [
+                        "job_id",
+                        "name",
+                        "function",
+                        "schedule",
+                        "trigger_type",
+                        "status",
+                    ]
+                    for field in required_fields:
+                        assert field in task, f"Missing required field: {field}"
+
+                    # Verify field types
+                    assert isinstance(task["job_id"], str)
+                    assert isinstance(task["name"], str)
+                    assert isinstance(task["function"], str)
+                    assert isinstance(task["schedule"], str)
+                    valid_trigger_types = ["interval", "cron", "date", "unknown"]
+                    assert task["trigger_type"] in valid_trigger_types
+                    assert task["status"] in ["active", "paused"]
+
+    @pytest.mark.asyncio
+    async def test_scheduler_dependency_injection_works(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that dependency injection properly provides ScheduledTaskManager."""
+        # Mock the service layer to return predictable data
+        mock_tasks = [
+            ScheduledTask(
+                job_id="test_job",
+                name="Test Job",
+                function="test.module.function",
+                schedule="Every 5m",
+                trigger_type="interval",
+                status="active",
+                max_instances=1,
+                coalesce=True
+            )
+        ]
+
+        manager_path = "app.components.backend.api.scheduler.ScheduledTaskManager"
+        with patch(manager_path) as mock_manager_class:
+            mock_manager = AsyncMock()
+            mock_manager.list_tasks.return_value = mock_tasks
+            mock_manager_class.return_value = mock_manager
+
+            response = await async_client.get("/api/v1/scheduler/jobs")
+
+            # Verify the dependency was called
+            mock_manager_class.assert_called_once()
+            mock_manager.list_tasks.assert_called_once()
+
+            # Verify response structure
+            assert response.status_code == 200
+            data = response.json()
+            assert len(data["tasks"]) == 1
+            assert data["tasks"][0]["job_id"] == "test_job"
+{%- endif %}

aegis/templates/copier-aegis-project/{{ project_slug }}/tests/api/test_worker_endpoints.py.jinja

@@ -0,0 +1,165 @@
+{%- if include_worker %}
+"""
+Tests for worker API endpoints.
+
+These tests focus on the worker HTTP endpoints that handle task enqueuing,
+ensuring TaskRequest model works correctly with task_kwargs field and
+validates the API contract.
+"""
+
+from collections.abc import AsyncIterator
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from app.integrations.main import create_integrated_app
+
+
+class TestWorkerEndpoints:
+    """Test worker API endpoints for task enqueuing."""
+
+    @pytest.fixture
+    async def async_client(self) -> AsyncIterator[AsyncClient]:
+        """Async HTTP client for testing."""
+        app = create_integrated_app()
+
+        # Manually trigger startup for health check registration
+        from app.components.backend.hooks import backend_hooks
+        await backend_hooks.discover_lifespan_hooks()
+        await backend_hooks.execute_startup_hooks()
+
+        transport = ASGITransport(app=app)
+        async with AsyncClient(
+            transport=transport, base_url="http://test"
+        ) as client:
+            yield client
+
+    @patch("app.components.worker.pools.create_pool")
+    async def test_enqueue_task_with_kwargs(self, mock_create_pool, async_client):
+        """Test task enqueueing with task_kwargs field."""
+        # Clear cache to ensure fresh mock
+        from app.components.worker.pools import clear_pool_cache
+        await clear_pool_cache()
+
+        # Mock pool and job
+        mock_pool = AsyncMock()
+        mock_job = MagicMock()
+        mock_job.job_id = "test-job-123"
+        mock_pool.enqueue_job.return_value = mock_job
+
+        # Mock the get_queue_pool function to return our mocked pool
+        mock_create_pool.return_value = mock_pool
+
+        # Test data with task_kwargs
+        task_request = {
+            "task_name": "cpu_intensive_task",
+            "queue_type": "system",
+            "args": ["arg1", "arg2"],
+            "task_kwargs": {
+                "keyword_arg": "value",
+                "another_kwarg": 123
+            },
+            "delay_seconds": None
+        }
+
+        # Make the API call
+        response = await async_client.post(
+            "/api/v1/tasks/enqueue",
+            json=task_request
+        )
+
+        # Verify response
+        assert response.status_code == 200
+        response_data = response.json()
+        assert response_data["task_id"] == "test-job-123"
+        assert response_data["task_name"] == "cpu_intensive_task"
+        assert response_data["queue_type"] == "system"
+
+        # Verify that enqueue_job was called with task_kwargs unpacked
+        mock_pool.enqueue_job.assert_called_once_with(
+            "cpu_intensive_task",
+            "arg1",
+            "arg2",
+            _queue_name="arq:queue:system",
+            _defer_by=None,
+            keyword_arg="value",
+            another_kwarg=123
+        )
+
+    @patch("app.components.worker.pools.create_pool")
+    async def test_enqueue_task_without_kwargs(self, mock_create_pool, async_client):
+        """Test task enqueueing without task_kwargs (empty dict)."""
+        # Clear cache to ensure fresh mock
+        from app.components.worker.pools import clear_pool_cache
+        await clear_pool_cache()
+
+        # Mock pool and job
+        mock_pool = AsyncMock()
+        mock_job = MagicMock()
+        mock_job.job_id = "test-job-456"
+        mock_pool.enqueue_job.return_value = mock_job
+        mock_create_pool.return_value = mock_pool
+
+        # Test data without task_kwargs (should default to empty dict)
+        task_request = {
+            "task_name": "io_simulation_task",
+            "queue_type": "system",
+            "args": [],
+        }
+
+        # Make the API call
+        response = await async_client.post(
+            "/api/v1/tasks/enqueue",
+            json=task_request
+        )
+
+        # Verify response
+        assert response.status_code == 200
+        response_data = response.json()
+        assert response_data["task_id"] == "test-job-456"
+
+        # Verify enqueue_job called with no extra kwargs
+        mock_pool.enqueue_job.assert_called_once_with(
+            "io_simulation_task",
+            _queue_name="arq:queue:system",
+            _defer_by=None
+        )
+
+    async def test_enqueue_task_invalid_queue_type(self, async_client):
+        """Test error handling for invalid queue type."""
+        task_request = {
+            "task_name": "cpu_intensive_task",
+            "queue_type": "invalid_queue",
+            "args": [],
+            "task_kwargs": {}
+        }
+
+        response = await async_client.post(
+            "/api/v1/tasks/enqueue",
+            json=task_request
+        )
+
+        # Should return 400 for invalid queue type
+        assert response.status_code == 400
+        response_data = response.json()
+        assert "detail" in response_data
+        assert response_data["detail"]["error"] == "invalid_queue_type"
+
+    async def test_task_request_model_validation(self, async_client):
+        """Test TaskRequest model validation."""
+        # Missing required task_name field
+        invalid_request = {
+            "queue_type": "system",
+            "args": [],
+            "task_kwargs": {}
+        }
+
+        response = await async_client.post(
+            "/api/v1/tasks/enqueue",
+            json=invalid_request
+        )
+
+        # Should return 422 for validation error
+        assert response.status_code == 422
+{% endif %}