schema for external list test reports api (#308)

* schema

* PR comment

openapi.yaml

@@ -19,7 +19,7 @@ components:
           properties:
             source:
               type: string
-              enum: ["github"]
+              enum: [ "github" ]
               example: "github"
             issueNumber:
               type: integer
@@ -45,7 +45,7 @@ components:
               properties:
                 type:
                   type: string
-                  enum: ["USER"]
+                  enum: [ "USER" ]
                   example: "USER"
                 userId:
                   type: string
@@ -59,7 +59,7 @@ components:
           properties:
             source:
               type: string
-              enum: ["azureDevOps"]
+              enum: [ "azureDevOps" ]
               example: "azureDevOps"
             accessToken:
               type: string
@@ -91,7 +91,7 @@ components:
               properties:
                 type:
                   type: string
-                  enum: ["USER"]
+                  enum: [ "USER" ]
                   example: "USER"
                 userId:
                   type: string
@@ -105,7 +105,7 @@ components:
           properties:
             source:
               type: string
-              enum: ["discovery"]
+              enum: [ "discovery" ]
               example: "discovery"
             description:
               type: string
@@ -116,13 +116,13 @@ components:
                   properties:
                     type:
                       type: string
-                      enum: ["INITIAL"]
+                      enum: [ "INITIAL" ]
                       example: "INITIAL"
                 - type: object
                   properties:
                     type:
                       type: string
-                      enum: ["USER"]
+                      enum: [ "USER" ]
                       example: "USER"
                     userId:
                       type: string
@@ -132,7 +132,7 @@ components:
           properties:
             source:
               type: string
-              enum: ["manual"]
+              enum: [ "manual" ]
               example: "manual"
             description:
               type: string
@@ -142,7 +142,7 @@ components:
               properties:
                 type:
                   type: string
-                  enum: ["USER"]
+                  enum: [ "USER" ]
                   example: "USER"
                 userId:
                   type: string
@@ -152,15 +152,15 @@ components:
           properties:
             source:
               type: string
-              enum: ["scheduled"]
+              enum: [ "scheduled" ]
               example: "scheduled"
             triggeredBy:
               type: object
               nullable: true
               properties:
                 type:
                   type: string
-                  enum: ["USER"]
+                  enum: [ "USER" ]
                   example: "USER"
                 userId:
                   type: string
@@ -170,7 +170,7 @@ components:
           properties:
             source:
               type: string
-              enum: ["proposal"]
+              enum: [ "proposal" ]
               example: "proposal"
             description:
               type: string
@@ -181,13 +181,13 @@ components:
                   properties:
                     type:
                       type: string
-                      enum: ["INITIAL"]
+                      enum: [ "INITIAL" ]
                       example: "INITIAL"
                 - type: object
                   properties:
                     type:
                       type: string
-                      enum: ["USER"]
+                      enum: [ "USER" ]
                       example: "USER"
                     userId:
                       type: string
@@ -234,7 +234,7 @@ components:
       properties:
         source:
           type: string
-          enum: ["manual"]
+          enum: [ "manual" ]
           description: The source of the test trigger.
           example: "manual"
         description:
@@ -246,7 +246,7 @@ components:
           properties:
             type:
               type: string
-              enum: ["USER"]
+              enum: [ "USER" ]
               description: The type of entity triggering the test.
               example: "USER"
             userId:
@@ -255,6 +255,51 @@ components:
               description: The unique identifier of the user who triggered the test.
               example: "2e2bb27b-a19c-47ce-a9b6-cd1bd31622dc"
 
+    TestResult:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier for the test result.
+          example: "826c15af-644b-4b28-89b4-f50ff34e46b7"
+        testTargetId:
+          type: string
+          format: uuid
+          description: Unique identifier of the test report this result belongs to.
+          example: "3435918b-3d29-4ebd-8c68-9a540532f45a"
+        testCaseId:
+          type: string
+          format: uuid
+          description: Unique identifier of the test case this result belongs to.
+          example: "5b844cf1-d597-4048-9e74-7c0f9ce3e2ee"
+        createdAt:
+          type: string
+          format: date-time
+          description: The timestamp when the test result was created.
+          example: "2024-09-06T13:01:51.686Z"
+        updatedAt:
+          type: string
+          format: date-time
+          description: The timestamp when the test result was last updated.
+          example: "2024-09-06T13:01:51.686Z"
+        status:
+          type: string
+          enum: [ "WAITING", "PASSED", "FAILED", "ERROR" ]
+          description: The status of the specific test result, will be WAITING as long as the result is running, FAILED if the execution failed, PASSED if it succeeded, and ERROR if an internal error occurred.
+        errorMessage:
+          type: string
+          nullable: true
+          description: The error that has occurred during execution - only set if the status is FAILED or ERROR.
+          example: "TimeoutError: locator.click: Timeout 30000ms exceeded.
+Call log:
+  - waiting for getByText('run locally')"
+        traceUrl:
+          type: string
+          nullable: true
+          description: Link to the playwright trace of the test execution - only set once the test result is finished (PASSED or FAILED).
+          example: "https://storage.googleapis.com/automagically-traces/826c15af-644b-4b28-89b4-f50ff34e46b7-trace.zip"
+
     TestReport:
       type: object
       properties:
@@ -285,10 +330,14 @@ components:
           example: "https://en.wikipedia.org/"
         status:
           type: string
-          enum: ["WAITING", "PASSED", "FAILING"]
+          enum: [ "WAITING", "PASSED", "FAILED" ]
           description: The status of the test report, will be WAITING as long as any result is running, FAILED if the report is done but has any failed result and PASSED if all test results are done and successful
         context:
           $ref: "#/components/schemas/TestReportContext"
+        testResults:
+          type: array
+          items:
+            $ref: "#/components/schemas/TestResult"
 
     TestReportResponse:
       type: object
@@ -332,13 +381,40 @@ components:
               type: string
               description: the address of the remote endpoint. IP and port
               example: 34.45.23.22:23455
+    ZodResponse:
+      type: array
+      items:
+        type: object
+        properties:
+          code:
+            type: string
+            example: "invalid_type"
+            description: "What error code happened while parsing the request"
+          expected:
+            type: string
+            description: "What the expected type was"
+            example: "object"
+          received:
+            type: "string"
+            description: "What the actual passed type was"
+            example: "string"
+          path:
+            type: array
+            items:
+              type: string
+              description: "The json path to the wrong parameter"
+              example: "key"
+          message:
+            type: string
+            description: "Human-readable message of the error that occurred while parsing."
+            example: "Expected object, received string"
 paths:
   /apiKey/v2/execute:
     post:
       summary: Execute all tests of the given test target with a given URL
       description: This endpoint triggers a test execution by sending an test target id and a URL.
       security:
-        - ApiKeyAuth: []
+        - ApiKeyAuth: [ ]
       requestBody:
         required: true
         content:
@@ -354,6 +430,10 @@ paths:
                 $ref: "#/components/schemas/TestReportResponse"
         "400":
           description: Invalid request parameters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ZodResponse"
         "401":
           description: Invalid or missing API key
         "500":
@@ -379,7 +459,7 @@ paths:
             format: uuid
           description: ID of the test report to fetch
       security:
-        - ApiKeyAuth: []
+        - ApiKeyAuth: [ ]
       responses:
         "200":
           description: Test Report information
@@ -389,6 +469,93 @@ paths:
                 $ref: "#/components/schemas/TestReport"
         "400":
           description: Invalid request parameters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ZodResponse"
+        "401":
+          description: Invalid or missing API key
+        "500":
+          description: Internal server error
+
+  /apiKey/v2/test-targets/{testTargetId}/test-reports:
+    get:
+      summary: Retrieve paginated information about test reports.
+      description: Allow fetching the history of test reports for your test target.
+      parameters:
+        - in: path
+          name: testTargetId
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: ID of the test target for which to fetch the history for
+        - in: query
+          name: key
+          required: false
+          schema:
+            type: object
+            properties:
+              createdAt:
+                type: string
+                format: date-time
+                description: The timestamp of the key of the next page to fetch - See [Keyset Pagination](https://use-the-index-luke.com/no-offset)
+                example: "2024-09-06T13:01:51.686Z"
+        - in: query
+          name: filter
+          required: false
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                key:
+                  type: string
+                  description: "The name of the property to filter for, e.g. an environmentId"
+                  example: "environmentId"
+                operator:
+                  type: string
+                  enum: ["EQUALS"]
+                  description: How to compare the property in question, only EQUALS is supported so far.
+                value:
+                  type: string
+                  format: uuid
+                  description: The value to compare with to find matches.
+                  example: "3435918b-3d29-4ebd-8c68-9a540532f45a"
+      security:
+        - ApiKeyAuth: [ ]
+      responses:
+        "200":
+          description: Test Reports information
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/TestReport"
+                  key:
+                    type: object
+                    properties:
+                      createdAt:
+                        type: string
+                        format: date-time
+                        description: The timestamp of the key of the next page to fetch - use this in the query when fetching the next page of reports - See [Keyset Pagination](https://use-the-index-luke.com/no-offset)
+                        example: "2024-09-06T13:01:51.686Z"
+                  hasNextPage:
+                    type: boolean
+                    description: If the query in question has another page to retrieve
+
+
+        "400":
+          description: Invalid request parameters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ZodResponse"
+
         "401":
           description: Invalid or missing API key
         "500":
@@ -397,7 +564,7 @@ paths:
   /apiKey/v1/private-location/register:
     put:
       security:
-        - ApiKeyAuth: []
+        - ApiKeyAuth: [ ]
       summary: register a private location
       description: "registers a private location worker"
       requestBody:
@@ -421,7 +588,7 @@ paths:
   /apiKey/v1/private-location/unregister:
     put:
       security:
-        - ApiKeyAuth: []
+        - ApiKeyAuth: [ ]
       summary: unregister a private location
       description: "unregisters a private location worker"
       requestBody: