From b977acca76fb97f01342d9f2fad20f424ef7f376 Mon Sep 17 00:00:00 2001
From: Murilo Geraldini <murilo.geraldini@profusion.mobi>
Date: Wed, 29 Jan 2025 13:53:41 -0300
Subject: [PATCH] feat(api): add build tests view documentation

Part of #86
Closes #815
---
 .../kernelCI_app/typeModels/buildDetails.py   | 17 ++++-
 backend/kernelCI_app/views/buildTestsView.py  | 18 ++++-
 backend/schema.yml                            | 72 +++++++++++++++++++
 3 files changed, 103 insertions(+), 4 deletions(-)

diff --git a/backend/kernelCI_app/typeModels/buildDetails.py b/backend/kernelCI_app/typeModels/buildDetails.py
index 1be87a05e..73e7407da 100644
--- a/backend/kernelCI_app/typeModels/buildDetails.py
+++ b/backend/kernelCI_app/typeModels/buildDetails.py
@@ -1,4 +1,6 @@
-from typing import Optional, List, Dict, Any
+from datetime import datetime
+from typing import Optional, List, Dict, Any, Union
+from pydantic import BaseModel, RootModel
 
 from kernelCI_app.typeModels.commonDetails import BuildHistoryItem
 
@@ -16,3 +18,16 @@ class BuildDetailsResponse(BuildHistoryItem):
     log_excerpt: Optional[str]
     input_files: Optional[List[Dict[str, Any]]]
     output_files: Optional[List[Dict[str, Any]]]
+
+
+class BuildTestItem(BaseModel):
+    id: str
+    status: Optional[str]
+    duration: Optional[Union[int, float]]
+    path: Optional[str]
+    start_time: Optional[Union[datetime, str]]
+    environment_compatible: Optional[Union[str, List[str]]]
+
+
+class BuildTestsResponse(RootModel):
+    root: List[BuildTestItem]
diff --git a/backend/kernelCI_app/views/buildTestsView.py b/backend/kernelCI_app/views/buildTestsView.py
index c26fa9378..b217a624b 100644
--- a/backend/kernelCI_app/views/buildTestsView.py
+++ b/backend/kernelCI_app/views/buildTestsView.py
@@ -1,11 +1,15 @@
 from django.http import JsonResponse
-from django.views import View
 from http import HTTPStatus
 from kernelCI_app.helpers.errorHandling import create_error_response
+from kernelCI_app.typeModels.buildDetails import BuildTestsResponse
 from kernelCI_app.models import Tests
+from drf_spectacular.utils import extend_schema
+from rest_framework.views import APIView
+from pydantic import ValidationError
 
 
-class BuildTests(View):
+class BuildTests(APIView):
+    @extend_schema(responses=BuildTestsResponse)
     def get(self, request, build_id):
         result = Tests.objects.filter(build_id=build_id).values(
             "id", "duration", "status", "path", "start_time", "environment_compatible"
@@ -17,4 +21,12 @@ def get(self, request, build_id):
                 status_code=HTTPStatus.OK,
             )
 
-        return JsonResponse(list(result), safe=False)
+        try:
+            valid_response = BuildTestsResponse(result)
+        except ValidationError as e:
+            return create_error_response(
+                error_message=e.errors(),
+                status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
+            )
+
+        return JsonResponse(valid_response.model_dump(), safe=False)
diff --git a/backend/schema.yml b/backend/schema.yml
index a0153a67a..b71446350 100644
--- a/backend/schema.yml
+++ b/backend/schema.yml
@@ -26,6 +26,28 @@ paths:
               schema:
                 $ref: '#/components/schemas/BuildDetailsResponse'
           description: ''
+  /api/build/{build_id}/tests:
+    get:
+      operationId: build_tests_retrieve
+      parameters:
+      - in: path
+        name: build_id
+        schema:
+          type: string
+        required: true
+      tags:
+      - build
+      security:
+      - cookieAuth: []
+      - basicAuth: []
+      - {}
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BuildTestsResponse'
+          description: ''
   /api/hardware/{hardware_id}:
     post:
       operationId: hardware_create
@@ -859,6 +881,56 @@ components:
       - unknown_issues
       title: BuildSummary
       type: object
+    BuildTestItem:
+      properties:
+        id:
+          title: Id
+          type: string
+        status:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Status
+        duration:
+          anyOf:
+          - type: integer
+          - type: number
+          - type: 'null'
+          title: Duration
+        path:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Path
+        start_time:
+          anyOf:
+          - format: date-time
+            type: string
+          - type: string
+          - type: 'null'
+          title: Start Time
+        environment_compatible:
+          anyOf:
+          - type: string
+          - items:
+              type: string
+            type: array
+          - type: 'null'
+          title: Environment Compatible
+      required:
+      - id
+      - status
+      - duration
+      - path
+      - start_time
+      - environment_compatible
+      title: BuildTestItem
+      type: object
+    BuildTestsResponse:
+      items:
+        $ref: '#/components/schemas/BuildTestItem'
+      title: BuildTestsResponse
+      type: array
     CommonDetailsBootsResponse:
       properties:
         boots: