feat: add external test runs list and detail views

Agent-Logs-Url: https://github.com/bg-playground/BGSTM/sessions/294d8d86-ccd0-403f-8efe-8eea70b4325f

Co-authored-by: bg-playground <259109604+bg-playground@users.noreply.github.com>

Author: Copilot

backend/app/api/external_results.py

@@ -18,7 +18,7 @@
 import uuid as _uuid_module
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
 from sqlalchemy.ext.asyncio import AsyncSession
 from streaming_form_data import StreamingFormDataParser
 from streaming_form_data.targets import FileTarget, ValueTarget
@@ -30,18 +30,26 @@
 from app.config import settings
 from app.crud.audit_log import write_audit
 from app.crud.external_case_artifacts import create_artifact
-from app.crud.external_case_results import create_case_result, get_case_result, update_case_result
-from app.crud.external_results import create_session, finish_session_db, get_session
+from app.crud.external_case_results import (
+    create_case_result,
+    get_case_result,
+    list_case_results_for_session,
+    update_case_result,
+)
+from app.crud.external_results import create_session, finish_session_db, get_session, list_sessions
 from app.db.session import get_db
 from app.models.external_case_artifact import ArtifactKind
 from app.models.runner_token import RunnerToken
 from app.schemas.external_results import (
     ArtifactResponse,
     CaseResultCreate,
+    CaseResultListResponse,
     CaseResultResponse,
     CaseResultUpdate,
+    RunStatus,
     SessionCreate,
     SessionFinish,
+    SessionListResponse,
     SessionResponse,
 )
 from app.storage import get_storage
@@ -103,8 +111,9 @@ def _session_to_response(session) -> SessionResponse:
         project_id=session.project_id,
         git_sha=session.git_sha,
         git_branch=session.git_branch,
-        ci_url=session.ci_url,
+        ci_url=str(session.ci_url) if session.ci_url else None,
         metadata=session.run_metadata or {},
+        summary=session.summary or {},
     )
 
 
@@ -248,6 +257,28 @@ async def get_external_session(
     return _session_to_response(session)
 
 
+@router.get(
+    "/external-results/sessions",
+    response_model=SessionListResponse,
+)
+async def list_external_sessions(
+    project_id: UUID | None = Query(None),
+    status: RunStatus | None = Query(None),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(25, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    _auth=Depends(get_runner_or_user_auth),
+) -> SessionListResponse:
+    """Return a paginated list of sessions, newest first."""
+    sessions, total = await list_sessions(db, project_id=project_id, status=status, skip=skip, limit=limit)
+    return SessionListResponse(
+        sessions=[_session_to_response(s) for s in sessions],
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
+
+
 # ---------------------------------------------------------------------------
 # POST /external-results/case — create a case result
 # ---------------------------------------------------------------------------
@@ -416,6 +447,33 @@ async def get_external_case_result(
     return _case_result_to_response(case_result)
 
 
+@router.get(
+    "/external-results/session/{session_id}/cases",
+    response_model=CaseResultListResponse,
+)
+async def list_external_session_cases(
+    session_id: UUID,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(200, ge=1, le=500),
+    db: AsyncSession = Depends(get_db),
+    _auth=Depends(get_runner_or_user_auth),
+) -> CaseResultListResponse:
+    """Return all case results for a given session."""
+    session = await get_session(db, session_id)
+    if session is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"code": "session.not_found", "message": f"Session {session_id} does not exist.", "details": None},
+        )
+    cases, total = await list_case_results_for_session(db, session_id=session_id, skip=skip, limit=limit)
+    return CaseResultListResponse(
+        cases=[_case_result_to_response(c) for c in cases],
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
+
+
 # ---------------------------------------------------------------------------
 # POST /external-results/artifact — upload an artifact
 # ---------------------------------------------------------------------------

backend/app/crud/external_case_results.py

@@ -4,7 +4,7 @@
 from typing import Any
 from uuid import UUID
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.dialects.postgresql import insert as postgresql_insert
 from sqlalchemy.dialects.sqlite import insert as sqlite_insert
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -347,3 +347,26 @@ async def get_case_result(
 
     case_result.requirement_ids = await _get_requirement_ids_for_test_case(db, test_case_id=case_result.test_case_id)
     return case_result
+
+
+async def list_case_results_for_session(
+    db: AsyncSession,
+    *,
+    session_id: UUID,
+    skip: int = 0,
+    limit: int = 200,
+) -> tuple[list[ExternalCaseResult], int]:
+    """Return all case results for a given session, ordered by created_at asc."""
+    stmt = (
+        select(ExternalCaseResult)
+        .where(ExternalCaseResult.session_id == session_id)
+        .order_by(ExternalCaseResult.created_at.asc())
+        .offset(skip)
+        .limit(limit)
+    )
+    count_stmt = select(func.count()).select_from(ExternalCaseResult).where(ExternalCaseResult.session_id == session_id)
+    total = (await db.execute(count_stmt)).scalar_one()
+    rows = (await db.execute(stmt)).scalars().all()
+    for row in rows:
+        row.requirement_ids = await _get_requirement_ids_for_test_case(db, test_case_id=row.test_case_id)
+    return list(rows), total

backend/app/crud/external_results.py

@@ -3,7 +3,7 @@
 from datetime import datetime, timedelta, timezone
 from uuid import UUID
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.external_results import ExternalRunSession, RunStatus
@@ -137,3 +137,26 @@ async def get_session(
     """Return a single ExternalRunSession by primary key, or None."""
     result = await db.execute(select(ExternalRunSession).where(ExternalRunSession.id == session_id))
     return result.scalar_one_or_none()
+
+
+async def list_sessions(
+    db: AsyncSession,
+    *,
+    project_id: UUID | None = None,
+    status: RunStatus | None = None,
+    skip: int = 0,
+    limit: int = 25,
+) -> tuple[list[ExternalRunSession], int]:
+    """Return a paginated list of sessions and total count."""
+    stmt = select(ExternalRunSession).order_by(ExternalRunSession.started_at.desc())
+    count_stmt = select(func.count()).select_from(ExternalRunSession)
+    if project_id is not None:
+        stmt = stmt.where(ExternalRunSession.project_id == project_id)
+        count_stmt = count_stmt.where(ExternalRunSession.project_id == project_id)
+    if status is not None:
+        stmt = stmt.where(ExternalRunSession.status == status)
+        count_stmt = count_stmt.where(ExternalRunSession.status == status)
+    stmt = stmt.offset(skip).limit(limit)
+    total = (await db.execute(count_stmt)).scalar_one()
+    rows = (await db.execute(stmt)).scalars().all()
+    return list(rows), total

backend/app/schemas/external_results.py

@@ -95,6 +95,7 @@ class SessionResponse(BaseModel):
     git_branch: str | None = None
     ci_url: HttpUrl | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
+    summary: dict[str, Any] | None = None
 
 
 _TERMINAL_STATUSES = {RunStatus.passed, RunStatus.failed, RunStatus.aborted}
@@ -197,6 +198,24 @@ class CaseResultResponse(BaseModel):
     )
 
 
+class SessionListResponse(BaseModel):
+    """Response for GET /external-results/sessions."""
+
+    sessions: list[SessionResponse]
+    total: int
+    skip: int
+    limit: int
+
+
+class CaseResultListResponse(BaseModel):
+    """Response for GET /external-results/session/{id}/cases."""
+
+    cases: list[CaseResultResponse]
+    total: int
+    skip: int
+    limit: int
+
+
 class CaseResultUpdate(BaseModel):
     """Payload for ``PATCH /api/v1/external-results/case/{id}``."""
 

backend/tests/integration/test_external_results_session.py

@@ -174,6 +174,55 @@ def test_create_without_runner_defaults_to_bgstm_playwright_core(self, db_sessio
         data = resp.json()
         assert data["runner"].startswith("@bgstm/playwright-core@")
 
+    def test_list_sessions_returns_paginated_and_filtered_data(self, db_session, write_token, project_id):
+        _model, plaintext = write_token
+        headers = _auth_header(plaintext)
+
+        with TestClient(app) as client:
+            first_payload = dict(_session_payload(project_id), ci_url=f"https://ci.example.com/runs/{uuid.uuid4()}")
+            second_payload = dict(
+                _session_payload(project_id),
+                git_branch="release",
+                git_sha="def456",
+                ci_url=f"https://ci.example.com/runs/{uuid.uuid4()}",
+            )
+
+            first_resp = client.post("/api/v1/external-results/session", json=first_payload, headers=headers)
+            second_resp = client.post("/api/v1/external-results/session", json=second_payload, headers=headers)
+            assert first_resp.status_code == 201, first_resp.text
+            assert second_resp.status_code == 201, second_resp.text
+
+            first_id = first_resp.json()["id"]
+            second_id = second_resp.json()["id"]
+
+            finish_resp = client.patch(
+                f"/api/v1/external-results/session/{first_id}",
+                json={"status": "passed", "summary": {"total": 7, "passed": 7}},
+                headers=headers,
+            )
+            assert finish_resp.status_code == 200, finish_resp.text
+
+            list_resp = client.get("/api/v1/external-results/sessions?skip=0&limit=25", headers=headers)
+            assert list_resp.status_code == 200, list_resp.text
+            list_data = list_resp.json()
+            assert list_data["total"] == 2
+            assert list_data["skip"] == 0
+            assert list_data["limit"] == 25
+            returned_ids = [s["id"] for s in list_data["sessions"]]
+            assert first_id in returned_ids
+            assert second_id in returned_ids
+            finished_row = next(s for s in list_data["sessions"] if s["id"] == first_id)
+            assert finished_row["summary"] == {"total": 7, "passed": 7}
+
+            filtered_resp = client.get(
+                "/api/v1/external-results/sessions?status=passed&skip=0&limit=25",
+                headers=headers,
+            )
+            assert filtered_resp.status_code == 200, filtered_resp.text
+            filtered_data = filtered_resp.json()
+            assert filtered_data["total"] == 1
+            assert [s["id"] for s in filtered_data["sessions"]] == [first_id]
+
 
 # ---------------------------------------------------------------------------
 # Auth: 401 without credentials

backend/tests/test_external_results_case.py

@@ -538,3 +538,58 @@ async def test_auth_requirements(self, db_session, write_token, read_token):
         assert get_with_user.status_code == 200
         assert get_with_runner.status_code == 200
         assert get_unknown.status_code == 404
+
+    @pytest.mark.asyncio
+    async def test_list_session_cases_returns_paginated_rows_and_404_for_unknown_session(
+        self, db_session, write_token, read_token
+    ):
+        _write_model, write_plaintext = write_token
+        _read_model, read_plaintext = read_token
+
+        with TestClient(app) as client:
+            session_id = _create_session(client, write_plaintext)
+            first = client.post(
+                "/api/v1/external-results/case",
+                json={
+                    "session_id": session_id,
+                    "external_id": f"case-a-{uuid.uuid4()}",
+                    "title": "case-a",
+                    "outcome": "passed",
+                    "duration_ms": 12,
+                    "requirement_ids": [],
+                },
+                headers=_auth_header(write_plaintext),
+            )
+            second = client.post(
+                "/api/v1/external-results/case",
+                json={
+                    "session_id": session_id,
+                    "external_id": f"case-b-{uuid.uuid4()}",
+                    "title": "case-b",
+                    "outcome": "failed",
+                    "duration_ms": 34,
+                    "error_message": "assertion failed",
+                    "requirement_ids": [],
+                },
+                headers=_auth_header(write_plaintext),
+            )
+            assert first.status_code == 201, first.text
+            assert second.status_code == 201, second.text
+
+            list_resp = client.get(
+                f"/api/v1/external-results/session/{session_id}/cases?skip=0&limit=200",
+                headers=_auth_header(read_plaintext),
+            )
+            assert list_resp.status_code == 200, list_resp.text
+            list_data = list_resp.json()
+            assert list_data["total"] == 2
+            assert list_data["skip"] == 0
+            assert list_data["limit"] == 200
+            assert [case["id"] for case in list_data["cases"]] == [first.json()["id"], second.json()["id"]]
+
+            missing_resp = client.get(
+                f"/api/v1/external-results/session/{uuid.uuid4()}/cases",
+                headers=_auth_header(read_plaintext),
+            )
+            assert missing_resp.status_code == 404
+            assert missing_resp.json()["detail"]["code"] == "session.not_found"

frontend/src/App.tsx

@@ -10,6 +10,8 @@ import { SuggestionDashboard } from './pages/SuggestionDashboard';
 import { RequirementsPage } from './pages/RequirementsPage';
 import { TestCasesPage } from './pages/TestCasesPage';
 import { ManualLinksPage } from './pages/ManualLinksPage';
+import { TestRunsPage } from './pages/TestRunsPage';
+import TestRunDetailPage from './pages/TestRunDetailPage';
 import TraceabilityMatrixPage from './pages/TraceabilityMatrixPage';
 import MetricsDashboardPage from './pages/MetricsDashboardPage';
 import { AuditLogPage } from './pages/AuditLogPage';
@@ -38,6 +40,8 @@ function App() {
               <Route path="/" element={<SuggestionDashboard />} />
               <Route path="/requirements" element={<RequirementsPage />} />
               <Route path="/test-cases" element={<TestCasesPage />} />
+              <Route path="/runs" element={<TestRunsPage />} />
+              <Route path="/runs/:sessionId" element={<TestRunDetailPage />} />
               <Route path="/links" element={<ManualLinksPage />} />
               <Route path="/traceability" element={<TraceabilityMatrixPage />} />
               <Route path="/metrics" element={<MetricsDashboardPage />} />