semantic update

backend/src/api/routes/__tests__/test_datasets.py

@@ -1,8 +1,10 @@
 # [DEF:backend.src.api.routes.__tests__.test_datasets:Module]
 # @TIER: STANDARD
+# @SEMANTICS: datasets, api, tests, pagination, mapping, docs
 # @PURPOSE: Unit tests for Datasets API endpoints
 # @LAYER: API
 # @RELATION: TESTS -> backend.src.api.routes.datasets
+# @INVARIANT: Endpoint contracts remain stable for success and validation failure paths.
 
 import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
@@ -14,6 +16,7 @@ client = TestClient(app)
 
 
 # [DEF:test_get_datasets_success:Function]
+# @PURPOSE: Validate successful datasets listing contract for an existing environment.
 # @TEST: GET /api/datasets returns 200 and valid schema
 # @PRE: env_id exists
 # @POST: Response matches DatasetsResponse schema

backend/src/api/routes/__tests__/test_reports_api.py

@@ -0,0 +1,139 @@
+# [DEF:backend.tests.test_reports_api:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: tests, reports, api, contract, pagination, filtering
+# @PURPOSE: Contract tests for GET /api/reports defaults, pagination, and filtering behavior.
+# @LAYER: Domain (Tests)
+# @RELATION: TESTS -> backend.src.api.routes.reports
+# @INVARIANT: API response contract contains {items,total,page,page_size,has_next,applied_filters}.
+
+from datetime import datetime, timedelta, timezone
+from types import SimpleNamespace
+
+from fastapi.testclient import TestClient
+
+from src.app import app
+from src.core.task_manager.models import Task, TaskStatus
+from src.dependencies import get_current_user, get_task_manager
+
+
+class _FakeTaskManager:
+    def __init__(self, tasks):
+        self._tasks = tasks
+
+    def get_all_tasks(self):
+        return self._tasks
+
+
+def _admin_user():
+    admin_role = SimpleNamespace(name="Admin", permissions=[])
+    return SimpleNamespace(username="test-admin", roles=[admin_role])
+
+
+def _make_task(task_id: str, plugin_id: str, status: TaskStatus, started_at: datetime, finished_at: datetime = None, result=None):
+    return Task(
+        id=task_id,
+        plugin_id=plugin_id,
+        status=status,
+        started_at=started_at,
+        finished_at=finished_at,
+        params={"environment_id": "env-1"},
+        result=result or {"summary": f"{plugin_id} {status.value.lower()}"},
+    )
+
+
+def test_get_reports_default_pagination_contract():
+    now = datetime.utcnow()
+    tasks = [
+        _make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=10), now - timedelta(minutes=9)),
+        _make_task("t-2", "superset-migration", TaskStatus.FAILED, now - timedelta(minutes=8), now - timedelta(minutes=7)),
+        _make_task("t-3", "llm_dashboard_validation", TaskStatus.RUNNING, now - timedelta(minutes=6), None),
+    ]
+
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports")
+        assert response.status_code == 200
+
+        data = response.json()
+        assert set(["items", "total", "page", "page_size", "has_next", "applied_filters"]).issubset(data.keys())
+        assert data["page"] == 1
+        assert data["page_size"] == 20
+        assert data["total"] == 3
+        assert isinstance(data["items"], list)
+        assert data["applied_filters"]["sort_by"] == "updated_at"
+        assert data["applied_filters"]["sort_order"] == "desc"
+    finally:
+        app.dependency_overrides.clear()
+
+
+def test_get_reports_filter_and_pagination():
+    now = datetime.utcnow()
+    tasks = [
+        _make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=30), now - timedelta(minutes=29)),
+        _make_task("t-2", "superset-backup", TaskStatus.FAILED, now - timedelta(minutes=20), now - timedelta(minutes=19)),
+        _make_task("t-3", "superset-migration", TaskStatus.FAILED, now - timedelta(minutes=10), now - timedelta(minutes=9)),
+    ]
+
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports?task_types=backup&statuses=failed&page=1&page_size=1")
+        assert response.status_code == 200
+
+        data = response.json()
+        assert data["total"] == 1
+        assert data["page"] == 1
+        assert data["page_size"] == 1
+        assert data["has_next"] is False
+        assert len(data["items"]) == 1
+        assert data["items"][0]["task_type"] == "backup"
+        assert data["items"][0]["status"] == "failed"
+    finally:
+        app.dependency_overrides.clear()
+
+
+def test_get_reports_handles_mixed_naive_and_aware_datetimes():
+    naive_now = datetime.utcnow()
+    aware_now = datetime.now(timezone.utc)
+    tasks = [
+        _make_task("t-naive", "superset-backup", TaskStatus.SUCCESS, naive_now - timedelta(minutes=5), naive_now - timedelta(minutes=4)),
+        _make_task("t-aware", "superset-migration", TaskStatus.FAILED, aware_now - timedelta(minutes=3), aware_now - timedelta(minutes=2)),
+    ]
+
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports?sort_by=updated_at&sort_order=desc")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["total"] == 2
+        assert len(data["items"]) == 2
+    finally:
+        app.dependency_overrides.clear()
+
+
+def test_get_reports_invalid_filter_returns_400():
+    now = datetime.utcnow()
+    tasks = [_make_task("t-1", "superset-backup", TaskStatus.SUCCESS, now - timedelta(minutes=5), now - timedelta(minutes=4))]
+
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports?task_types=bad_type")
+        assert response.status_code == 400
+        body = response.json()
+        assert "detail" in body
+    finally:
+        app.dependency_overrides.clear()
+
+
+# [/DEF:backend.tests.test_reports_api:Module]

backend/src/api/routes/__tests__/test_reports_detail_api.py

@@ -0,0 +1,83 @@
+# [DEF:backend.tests.test_reports_detail_api:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: tests, reports, api, detail, diagnostics
+# @PURPOSE: Contract tests for GET /api/reports/{report_id} detail endpoint behavior.
+# @LAYER: Domain (Tests)
+# @RELATION: TESTS -> backend.src.api.routes.reports
+
+from datetime import datetime, timedelta
+from types import SimpleNamespace
+
+from fastapi.testclient import TestClient
+
+from src.app import app
+from src.core.task_manager.models import Task, TaskStatus
+from src.dependencies import get_current_user, get_task_manager
+
+
+class _FakeTaskManager:
+    def __init__(self, tasks):
+        self._tasks = tasks
+
+    def get_all_tasks(self):
+        return self._tasks
+
+
+def _admin_user():
+    role = SimpleNamespace(name="Admin", permissions=[])
+    return SimpleNamespace(username="test-admin", roles=[role])
+
+
+def _make_task(task_id: str, plugin_id: str, status: TaskStatus, result=None):
+    now = datetime.utcnow()
+    return Task(
+        id=task_id,
+        plugin_id=plugin_id,
+        status=status,
+        started_at=now - timedelta(minutes=2),
+        finished_at=now - timedelta(minutes=1) if status != TaskStatus.RUNNING else None,
+        params={"environment_id": "env-1"},
+        result=result or {"summary": f"{plugin_id} result"},
+    )
+
+
+def test_get_report_detail_success():
+    task = _make_task(
+        "detail-1",
+        "superset-migration",
+        TaskStatus.FAILED,
+        result={"error": {"message": "Step failed", "next_actions": ["Check mapping", "Retry"]}},
+    )
+
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager([task])
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports/detail-1")
+        assert response.status_code == 200
+
+        data = response.json()
+        assert "report" in data
+        assert data["report"]["report_id"] == "detail-1"
+        assert "diagnostics" in data
+        assert "next_actions" in data
+    finally:
+        app.dependency_overrides.clear()
+
+
+def test_get_report_detail_not_found():
+    task = _make_task("detail-2", "superset-backup", TaskStatus.SUCCESS)
+
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager([task])
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports/unknown-id")
+        assert response.status_code == 404
+    finally:
+        app.dependency_overrides.clear()
+
+
+# [/DEF:backend.tests.test_reports_detail_api:Module]

backend/src/api/routes/__tests__/test_reports_openapi_conformance.py

@@ -0,0 +1,81 @@
+# [DEF:backend.tests.test_reports_openapi_conformance:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: tests, reports, openapi, conformance
+# @PURPOSE: Validate implemented reports payload shape against OpenAPI-required top-level contract fields.
+# @LAYER: Domain (Tests)
+# @RELATION: TESTS -> specs/020-task-reports-design/contracts/reports-api.openapi.yaml
+# @INVARIANT: List and detail payloads include required contract keys.
+
+from datetime import datetime
+from types import SimpleNamespace
+
+from fastapi.testclient import TestClient
+
+from src.app import app
+from src.core.task_manager.models import Task, TaskStatus
+from src.dependencies import get_current_user, get_task_manager
+
+
+class _FakeTaskManager:
+    def __init__(self, tasks):
+        self._tasks = tasks
+
+    def get_all_tasks(self):
+        return self._tasks
+
+
+def _admin_user():
+    role = SimpleNamespace(name="Admin", permissions=[])
+    return SimpleNamespace(username="test-admin", roles=[role])
+
+
+def _task(task_id: str, plugin_id: str, status: TaskStatus):
+    now = datetime.utcnow()
+    return Task(
+        id=task_id,
+        plugin_id=plugin_id,
+        status=status,
+        started_at=now,
+        finished_at=now if status != TaskStatus.RUNNING else None,
+        params={"environment_id": "env-1"},
+        result={"summary": f"{plugin_id} {status.value.lower()}"},
+    )
+
+
+def test_reports_list_openapi_required_keys():
+    tasks = [
+        _task("r-1", "superset-backup", TaskStatus.SUCCESS),
+        _task("r-2", "superset-migration", TaskStatus.FAILED),
+    ]
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports")
+        assert response.status_code == 200
+
+        body = response.json()
+        required = {"items", "total", "page", "page_size", "has_next", "applied_filters"}
+        assert required.issubset(body.keys())
+    finally:
+        app.dependency_overrides.clear()
+
+
+def test_reports_detail_openapi_required_keys():
+    tasks = [_task("r-3", "llm_dashboard_validation", TaskStatus.SUCCESS)]
+    app.dependency_overrides[get_current_user] = lambda: _admin_user()
+    app.dependency_overrides[get_task_manager] = lambda: _FakeTaskManager(tasks)
+
+    try:
+        client = TestClient(app)
+        response = client.get("/api/reports/r-3")
+        assert response.status_code == 200
+
+        body = response.json()
+        assert "report" in body
+    finally:
+        app.dependency_overrides.clear()
+
+
+# [/DEF:backend.tests.test_reports_openapi_conformance:Module]