h2orb 0.1.1__py3-none-any.whl

h2orb/__init__.py

@@ -0,0 +1,4 @@
+"""H2ORB – H2O Result Browser package."""
+
+__version__ = "0.1.0"
+

h2orb/__main__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import uvicorn
+
+from h2orb.config import get_settings
+
+
+def main() -> None:
+    settings = get_settings()
+    uvicorn.run(
+        "h2orb.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.environment == "development",
+        log_level=settings.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()
+

h2orb/api/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP API exposed by the application."""
+

h2orb/api/dependencies.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from fastapi import Request
+
+from h2orb.aqua.client import AquaClient
+
+
+def get_aqua_client(request: Request) -> AquaClient:
+    return request.app.state.aqua_client
+

h2orb/api/routes.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+
+from h2orb.api.dependencies import get_aqua_client
+from h2orb.aqua.client import AquaApiError, AquaClient, AquaConfigurationError
+from h2orb.config import get_settings
+from h2orb.services.navigation import map_projects, map_scenarios, map_subfolders
+from h2orb.services.report import build_markdown_report, build_report
+
+router = APIRouter()
+templates = Jinja2Templates(directory=Path(__file__).resolve().parents[1] / "templates")
+
+
+@router.get("/", response_class=HTMLResponse)
+async def index(request: Request) -> HTMLResponse:
+    settings = get_settings()
+    return templates.TemplateResponse(
+        request=request,
+        name="index.html",
+        context={
+            "app_name": settings.app_name,
+            "environment": settings.environment,
+        },
+    )
+
+
+@router.get("/health", tags=["operations"])
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@router.get("/api/v1/status", tags=["application"])
+def application_status() -> dict[str, str]:
+    return {
+        "application": "ready",
+        "aquaIntegration": "awaiting-swagger-mapping",
+    }
+
+
+@router.get("/api/v1/aqua/projects", tags=["aqua"])
+async def aqua_projects(
+    client: Annotated[AquaClient, Depends(get_aqua_client)],
+) -> dict[str, object]:
+    try:
+        payload = await client.get_project_tree([], include_projects=True)
+    except AquaConfigurationError as exc:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, str(exc)) from exc
+    except AquaApiError as exc:
+        raise HTTPException(status.HTTP_502_BAD_GATEWAY, str(exc)) from exc
+    return {"items": map_projects(payload)}
+
+
+@router.get("/api/v1/aqua/projects/{project_id}/folders", tags=["aqua"])
+async def aqua_folders(
+    project_id: int,
+    client: Annotated[AquaClient, Depends(get_aqua_client)],
+    folder_id: Annotated[int, Query(ge=0)] = 0,
+) -> dict[str, object]:
+    try:
+        payload = await client.get_project_tree([f"{project_id}_{folder_id}"])
+    except AquaConfigurationError as exc:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, str(exc)) from exc
+    except AquaApiError as exc:
+        raise HTTPException(status.HTTP_502_BAD_GATEWAY, str(exc)) from exc
+    return {"items": map_subfolders(payload)}
+
+
+@router.get("/api/v1/aqua/projects/{project_id}/scenarios", tags=["aqua"])
+async def aqua_scenarios(
+    project_id: int,
+    client: Annotated[AquaClient, Depends(get_aqua_client)],
+    folder_id: Annotated[int, Query(ge=0)] = 0,
+) -> dict[str, object]:
+    try:
+        items = await client.get_all_test_scenarios(project_id, folder_id)
+    except AquaConfigurationError as exc:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, str(exc)) from exc
+    except AquaApiError as exc:
+        raise HTTPException(status.HTTP_502_BAD_GATEWAY, str(exc)) from exc
+    scenarios = map_scenarios(items)
+    return {"count": len(scenarios), "items": scenarios}
+
+
+@router.get("/api/v1/aqua/projects/{project_id}/report", tags=["aqua"])
+async def aqua_report(
+    project_id: int,
+    client: Annotated[AquaClient, Depends(get_aqua_client)],
+    folder_id: Annotated[int, Query(ge=0)] = 0,
+) -> dict[str, object]:
+    settings = get_settings()
+    try:
+        raw_scenarios = await client.get_all_test_scenarios(project_id, folder_id)
+        scenarios = map_scenarios(raw_scenarios)
+        report = await build_report(
+            client,
+            scenarios,
+            selected_folder_id=folder_id,
+            aqua_web_base_url=str(settings.aqua_web_base_url),
+            noise_marker=settings.noise_marker,
+        )
+    except AquaConfigurationError as exc:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, str(exc)) from exc
+    except AquaApiError as exc:
+        raise HTTPException(status.HTTP_502_BAD_GATEWAY, str(exc)) from exc
+    return {"projectId": project_id, "folderId": folder_id, **report}
+
+
+@router.post("/api/v1/report/markdown", tags=["application"])
+async def markdown_report(payload: dict[str, object]) -> dict[str, str]:
+    tree = payload.get("tree")
+    if not isinstance(tree, dict):
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "Missing report tree")
+    generated_at = str(payload.get("generatedAt") or "")
+    language = str(payload.get("language") or "de")
+    if language not in {"de", "en"}:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "Unsupported language")
+    raw_keys = payload.get("summaryKeys") or []
+    if not isinstance(raw_keys, list) or not all(isinstance(key, str) for key in raw_keys):
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, "Invalid summary keys")
+    return {
+        "markdown": build_markdown_report(
+            tree,
+            generated_at=generated_at,
+            language=language,
+            summary_keys=raw_keys,
+        )
+    }

h2orb/aqua/__init__.py

@@ -0,0 +1,2 @@
+"""AQUA REST API integration."""
+

h2orb/aqua/client.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import ssl
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from h2orb.config import Settings
+
+
+class AquaApiError(RuntimeError):
+    """Raised when AQUA cannot fulfil a request."""
+
+
+class AquaConfigurationError(RuntimeError):
+    """Raised when required AQUA connection settings are missing."""
+
+
+@dataclass(slots=True)
+class _OAuthToken:
+    access_token: str
+    refresh_token: str | None
+    expires_at: float
+
+    def is_valid(self) -> bool:
+        return time.monotonic() < self.expires_at
+
+
+class AquaClient:
+    """Shared asynchronous AQUA client safe for concurrent application requests.
+
+    Endpoint-specific methods are added after mapping the v26.29.0.0 Swagger document.
+    Keeping raw requests private prevents AQUA transport details leaking into services.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self._username = settings.aqua_username
+        self._password = settings.aqua_password
+        self._token: _OAuthToken | None = None
+        self._token_lock = asyncio.Lock()
+        verify: bool | ssl.SSLContext = settings.aqua_verify_tls
+        if settings.aqua_verify_tls and settings.aqua_ca_bundle is not None:
+            verify = ssl.create_default_context(cafile=str(settings.aqua_ca_bundle))
+        self._client = httpx.AsyncClient(
+            base_url=str(settings.aqua_base_url).rstrip("/") + "/",
+            verify=verify,
+            timeout=httpx.Timeout(settings.aqua_timeout_seconds),
+            limits=httpx.Limits(
+                max_connections=settings.aqua_max_connections,
+                max_keepalive_connections=settings.aqua_max_connections,
+            ),
+            headers={"Accept": "application/json"},
+            trust_env=False,
+        )
+
+    async def close(self) -> None:
+        try:
+            if self._token is not None:
+                await self._client.delete(
+                    "api/Session",
+                    headers={"Authorization": f"Bearer {self._token.access_token}"},
+                )
+        except httpx.HTTPError:
+            pass
+        finally:
+            self._token = None
+            await self._client.aclose()
+
+    async def get_project_tree(
+        self,
+        parent_folders: list[str],
+        *,
+        include_projects: bool = False,
+        include_archived: bool = False,
+    ) -> dict[str, Any]:
+        return await self._get(
+            "api/Navigation/Tree",
+            parentFolders=json.dumps(parent_folders),
+            includeProjects=include_projects,
+            includeArchived=include_archived,
+        )
+
+    async def get_test_scenarios(
+        self,
+        project_id: int,
+        folder_id: int = 0,
+        *,
+        include_subfolders: bool = True,
+        start_at: int = 0,
+        max_results: int = 50,
+    ) -> dict[str, Any]:
+        return await self._get(
+            "api/TestScenario/ItemList",
+            projectId=project_id,
+            folderId=folder_id,
+            includeSubfolders=include_subfolders,
+            includeArchived=False,
+            startAt=start_at,
+            maxResults=max_results,
+        )
+
+    async def get_all_test_scenarios(
+        self,
+        project_id: int,
+        folder_id: int = 0,
+        *,
+        include_subfolders: bool = True,
+        page_size: int = 200,
+    ) -> list[dict[str, Any]]:
+        items: list[dict[str, Any]] = []
+        start_at = 0
+        while True:
+            page = await self.get_test_scenarios(
+                project_id,
+                folder_id,
+                include_subfolders=include_subfolders,
+                start_at=start_at,
+                max_results=page_size,
+            )
+            page_items = page.get("Items") or []
+            items.extend(page_items)
+            total = int(page.get("Count", len(items)))
+            if not page_items or len(items) >= total:
+                return items
+            start_at += len(page_items)
+
+    async def get_test_jobs(self, scenario_id: int) -> list[dict[str, Any]]:
+        return await self._get(f"api/TestScenario/{scenario_id}/TestJob")
+
+    async def get_scenario_executions(
+        self,
+        scenario_id: int,
+        *,
+        start_at: int = 0,
+        max_results: int = 100,
+    ) -> dict[str, Any]:
+        return await self._get(
+            f"api/TestScenario/{scenario_id}/Execution",
+            startAt=start_at,
+            maxResults=max_results,
+            orderBy="ExecutionDate DESC",
+            includeStatistics=True,
+        )
+
+    async def get_all_scenario_executions(
+        self, scenario_id: int, *, page_size: int = 200
+    ) -> list[dict[str, Any]]:
+        items: list[dict[str, Any]] = []
+        start_at = 0
+        while True:
+            page = await self.get_scenario_executions(
+                scenario_id, start_at=start_at, max_results=page_size
+            )
+            page_items = page.get("Items") or []
+            items.extend(item for item in page_items if not item.get("Irrelevant"))
+            total = int(page.get("Count", len(items)))
+            if not page_items or start_at + len(page_items) >= total:
+                return items
+            start_at += len(page_items)
+
+    async def get_test_execution(self, execution_id: int) -> dict[str, Any]:
+        return await self._get(
+            f"api/TestExecution/{execution_id}",
+            richTextFormatToInclude="None",
+        )
+
+    async def get_defect(
+        self, defect_id: int, *, with_enclosure: bool = False
+    ) -> dict[str, Any]:
+        return await self._get(
+            f"api/Defect/{defect_id}",
+            withEnclosure=with_enclosure,
+        )
+
+    async def get_execution_relations(self, execution_id: int) -> dict[str, Any]:
+        return await self._get(f"api/TestExecution/{execution_id}/Relation")
+
+    async def _get(self, path: str, **params: Any) -> Any:
+        return await self._request("GET", path, params=params or None)
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        token = await self._access_token()
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                headers={"Authorization": f"Bearer {token}"},
+                **kwargs,
+            )
+            if response.status_code == httpx.codes.UNAUTHORIZED:
+                self._token = None
+                token = await self._access_token()
+                response = await self._client.request(
+                    method,
+                    path,
+                    headers={"Authorization": f"Bearer {token}"},
+                    **kwargs,
+                )
+            response.raise_for_status()
+        except httpx.HTTPError as exc:
+            status = exc.response.status_code if isinstance(exc, httpx.HTTPStatusError) else None
+            suffix = f" with status {status}" if status is not None else ""
+            raise AquaApiError(f"AQUA request failed{suffix}") from exc
+        return response.json()
+
+    async def _access_token(self) -> str:
+        if self._token is not None and self._token.is_valid():
+            return self._token.access_token
+
+        async with self._token_lock:
+            if self._token is not None and self._token.is_valid():
+                return self._token.access_token
+            self._token = await self._request_token()
+            return self._token.access_token
+
+    async def _request_token(self) -> _OAuthToken:
+        if not self._username or not self._password:
+            raise AquaConfigurationError(
+                "ARB_AQUA_USERNAME and ARB_AQUA_PASSWORD must be configured"
+            )
+
+        try:
+            response = await self._client.post(
+                "api/token",
+                data={
+                    "grant_type": "password",
+                    "username": self._username,
+                    "password": self._password,
+                },
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            response.raise_for_status()
+            payload = response.json()
+            access_token = payload["access_token"]
+        except (httpx.HTTPError, KeyError, ValueError, TypeError) as exc:
+            raise AquaApiError("AQUA authentication failed") from exc
+
+        expires_in = max(float(payload.get("expires_in", 300)), 1.0)
+        return _OAuthToken(
+            access_token=access_token,
+            refresh_token=payload.get("refresh_token"),
+            expires_at=time.monotonic() + max(expires_in - 30.0, 1.0),
+        )

h2orb/check_connection.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import asyncio
+
+from h2orb.aqua.client import AquaClient
+from h2orb.config import get_settings
+
+
+async def check_connection() -> int:
+    client = AquaClient(get_settings())
+    try:
+        data = await client.get_project_tree([], include_projects=True)
+        project_count = len(data.get("Projects") or [])
+        print(f"AQUA connection successful; visible projects: {project_count}")
+        return 0
+    finally:
+        await client.close()
+
+
+def main() -> None:
+    raise SystemExit(asyncio.run(check_connection()))
+
+
+if __name__ == "__main__":
+    main()

h2orb/config.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field, HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="ARB_",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_name: str = "H2ORB – H2O Result Browser"
+    environment: str = "development"
+    host: str = "127.0.0.1"
+    port: int = Field(default=8000, ge=1, le=65535)
+    log_level: str = "INFO"
+
+    aqua_base_url: HttpUrl = HttpUrl("https://aqua.example.invalid")
+    aqua_web_base_url: HttpUrl = HttpUrl("https://app.aqua-cloud.io/aquaWebNG")
+    noise_marker: str = "[NOISE]"
+    aqua_username: str | None = None
+    aqua_password: str | None = None
+    aqua_verify_tls: bool = True
+    aqua_ca_bundle: Path | None = None
+    aqua_timeout_seconds: float = Field(default=30.0, gt=0)
+    aqua_max_connections: int = Field(default=20, ge=1)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+

h2orb/domain/__init__.py

@@ -0,0 +1,2 @@
+"""Framework-independent business model."""
+

h2orb/domain/models.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+
+
+class TestKind(StrEnum):
+    MANUAL = "manual"
+    AUTOMATED = "automated"
+
+
+class ExecutionStatus(StrEnum):
+    PASSED = "Passed"
+    FAILED = "Failed"
+    ABORTED = "Aborted"
+    NOT_EXECUTED = "Not Executed"
+    BLOCKED = "Blocked"
+    NOT_COMPLETED = "Not Completed"
+    NOT_APPLICABLE = "Not Applicable"
+    UNKNOWN = "Unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class Defect:
+    defect_id: int | str
+    formatted_id: str | None = None
+    name: str | None = None
+    url: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScenarioExecution:
+    scenario_id: int | str
+    scenario_name: str
+    test_case_id: int | str
+    test_case_name: str
+    test_kind: TestKind
+    status: ExecutionStatus
+    executed_at: datetime | None = None
+    defects: tuple[Defect, ...] = ()
+    scenario_url: str | None = None
+    test_case_url: str | None = None
+
+    @property
+    def has_defect(self) -> bool:
+        return bool(self.defects)
+
+    @property
+    def failure_class(self) -> str | None:
+        if self.status is not ExecutionStatus.FAILED:
+            return None
+        return "F" if self.has_defect else "X"
+
+
+@dataclass(slots=True)
+class StatusTotals:
+    total: int = 0
+    by_status: dict[ExecutionStatus, int] = field(default_factory=dict)
+    failed_with_defect: int = 0
+    failed_without_defect: int = 0
+
+    def add(self, execution: ScenarioExecution) -> None:
+        self.total += 1
+        self.by_status[execution.status] = self.by_status.get(execution.status, 0) + 1
+        if execution.failure_class == "F":
+            self.failed_with_defect += 1
+        elif execution.failure_class == "X":
+            self.failed_without_defect += 1
+
+    def percentage(self, count: int) -> float:
+        return round(count * 100 / self.total, 2) if self.total else 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class ReportTotals:
+    overall: StatusTotals
+    manual: StatusTotals
+    automated: StatusTotals
+    by_scenario: dict[int | str, StatusTotals]

h2orb/main.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from h2orb.api.routes import router
+from h2orb.aqua.client import AquaClient
+from h2orb.config import get_settings
+
+PACKAGE_DIR = Path(__file__).resolve().parent
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    settings = get_settings()
+    app.state.aqua_client = AquaClient(settings)
+    try:
+        yield
+    finally:
+        await app.state.aqua_client.close()
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    application = FastAPI(
+        title=settings.app_name,
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+    application.mount(
+        "/static",
+        StaticFiles(directory=PACKAGE_DIR / "static"),
+        name="static",
+    )
+    application.include_router(router)
+    return application
+
+
+app = create_app()

h2orb/services/__init__.py

@@ -0,0 +1,2 @@
+"""Application services and use cases."""
+

h2orb/services/aggregation.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from h2orb.domain.models import (
+    ReportTotals,
+    ScenarioExecution,
+    StatusTotals,
+    TestKind,
+)
+
+
+def latest_scenario_executions(
+    executions: Iterable[ScenarioExecution],
+) -> list[ScenarioExecution]:
+    """Return one latest execution per scenario/test-case occurrence.
+
+    A test case used in two scenarios deliberately produces two result rows.
+    """
+    latest: dict[tuple[int | str, int | str], ScenarioExecution] = {}
+    for execution in executions:
+        key = (execution.scenario_id, execution.test_case_id)
+        current = latest.get(key)
+        if current is None or _is_newer(execution, current):
+            latest[key] = execution
+    return list(latest.values())
+
+
+def aggregate(executions: Iterable[ScenarioExecution]) -> ReportTotals:
+    overall = StatusTotals()
+    manual = StatusTotals()
+    automated = StatusTotals()
+    by_scenario: dict[int | str, StatusTotals] = {}
+
+    for execution in latest_scenario_executions(executions):
+        overall.add(execution)
+        by_scenario.setdefault(execution.scenario_id, StatusTotals()).add(execution)
+        if execution.test_kind is TestKind.MANUAL:
+            manual.add(execution)
+        else:
+            automated.add(execution)
+
+    return ReportTotals(
+        overall=overall,
+        manual=manual,
+        automated=automated,
+        by_scenario=by_scenario,
+    )
+
+
+def visible_details(
+    executions: Iterable[ScenarioExecution], *, show_passed: bool
+) -> list[ScenarioExecution]:
+    latest = latest_scenario_executions(executions)
+    if show_passed:
+        return latest
+    return [execution for execution in latest if execution.status.value != "Passed"]
+
+
+def _is_newer(candidate: ScenarioExecution, current: ScenarioExecution) -> bool:
+    if candidate.executed_at is None:
+        return False
+    if current.executed_at is None:
+        return True
+    return candidate.executed_at > current.executed_at
+