Kubeshop test-suites API

openapi: 3.0.1
info:
  title: Testkube Standalone Agent api test-suites API
  description: API for Testkube Standalone Agent
  contact:
    email: info@testkube.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
servers:
- url: https://api.testkube.io
  description: Testkube Cloud Control Plane API Endpoint
- url: https://<your-testkube-api-host>
  description: Testkube On-Prem API Endpoint
tags:
- name: test-suites
  description: Test suites orchestration operations
paths:
  /test-suites:
    post:
      tags:
      - test-suites
      summary: Create new test suite
      description: Create new test suite action
      operationId: createTestSuite
      requestBody:
        description: test details body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestSuiteUpsertRequest'
          text/yaml:
            schema:
              type: string
      responses:
        200:
          description: successful operation
          content:
            text/yaml:
              schema:
                type: string
        201:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuite'
        400:
          description: problem with test suite definition - probably some bad input occurs (invalid JSON body or similar)
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
    get:
      tags:
      - test-suites
      summary: Get all test suites
      description: Returns array of test suites
      operationId: listTestSuites
      parameters:
      - $ref: '#/components/parameters/Selector'
      - $ref: '#/components/parameters/TextSearch'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestSuite'
            text/yaml:
              schema:
                type: string
        400:
          description: problem with input for CRD generation
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with listing test suites from kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
    delete:
      tags:
      - test-suites
      summary: Delete test suites
      description: Deletes all or labeled test suites
      operationId: deleteTestSuites
      parameters:
      - $ref: '#/components/parameters/Selector'
      responses:
        204:
          description: no content
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with read information from kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suites/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      tags:
      - test-suites
      summary: Get test suite by ID
      description: Returns test suite with given name
      operationId: getTestSuiteByID
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuite'
            text/yaml:
              schema:
                type: string
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: could not get execution result from the database
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
    patch:
      parameters:
      - $ref: '#/components/parameters/ID'
      tags:
      - test-suites
      summary: Update test suite
      description: Update test based on test suite content or git based data
      operationId: updateTestSuite
      requestBody:
        description: test suite details body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestSuiteUpdateRequest'
          text/yaml:
            schema:
              type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuite'
        400:
          description: problem with test suite definition - probably some bad input occurs (invalid JSON body or similar)
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
    delete:
      tags:
      - test-suites
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/SkipDeleteCRD'
      summary: Delete test suite
      description: Deletes a test suite
      operationId: deleteTestSuite
      responses:
        204:
          description: no content
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with read information from kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suites/{id}/tests:
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      tags:
      - test-suites
      summary: List tests for test suite
      description: List available tests for test suite
      operationId: listTestSuiteTests
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Test'
            text/yaml:
              schema:
                type: string
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with read information from kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suites/{id}/abort:
    post:
      tags:
      - test-suites
      parameters:
      - $ref: '#/components/parameters/ID'
      summary: Abort all executions of a test suite
      description: Abort all test executions of a test suite
      operationId: abortTestSuiteExecutions
      responses:
        204:
          description: no content
        404:
          description: no execution found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with aborting test suite execution
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with read information from kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suite-with-executions:
    get:
      tags:
      - test-suites
      summary: Get all test suite with executions
      description: Returns array of test suite with executions
      operationId: listTestSuiteWithExecutions
      parameters:
      - $ref: '#/components/parameters/Selector'
      - $ref: '#/components/parameters/TextSearch'
      - $ref: '#/components/parameters/TestExecutionsStatusFilter'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageIndex'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestSuiteWithExecutionSummary'
            text/yaml:
              schema:
                type: string
        400:
          description: problem with input
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with getting test suite with executions from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with getting test suite from Kubernetes clusteer
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suite-with-executions/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      tags:
      - test-suites
      summary: Get test suite by ID with execution
      description: Returns test suite with given name with execution
      operationId: getTestSuiteByIDWithExecution
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuiteWithExecution'
            text/yaml:
              schema:
                type: string
        500:
          description: problem with getting test suite with execution from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suites/{id}/executions:
    post:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/LastNDays'
      - $ref: '#/components/parameters/TestSuiteExecutionName'
      tags:
      - test-suites
      summary: Starts new test suite execution
      description: New test suite execution returns new execution details on successful execution start
      operationId: executeTestSuite
      requestBody:
        description: body passed to configure execution
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestSuiteExecutionRequest'
      responses:
        201:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuiteExecutionsResult'
        400:
          description: problem with request body
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with test suite execution
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageIndex'
      - $ref: '#/components/parameters/TestExecutionsStatusFilter'
      - $ref: '#/components/parameters/StartDateFilter'
      - $ref: '#/components/parameters/EndDateFilter'
      tags:
      - test-suites
      summary: Get all test suite executions
      description: Returns array of all available test suite executions
      operationId: listTestSuiteExecutions
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuiteExecutionsResult'
        500:
          description: problem with getting test suite executions from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suites/{id}/executions/{executionID}:
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/executionID'
      tags:
      - test-suites
      summary: Get test suite execution
      description: Returns test suite execution with given executionID
      operationId: getTestSuiteExecution
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSuiteExecution'
        404:
          description: test not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with getting test suite executions from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with communicating with Kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
    patch:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/executionID'
      tags:
      - test-suites
      summary: Aborts testsuite execution
      description: Aborts testsuite execution with given executionID
      operationId: abortTestSuiteExecution
      responses:
        204:
          description: no content
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with read information from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suites/{id}/executions/{executionID}/artifacts:
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/executionID'
      tags:
      - test-suites
      summary: Get test suite execution artifacts
      description: Returns test suite execution artifacts with given executionID
      operationId: getTestSuiteExecutionArtifactsByTestsuite
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artifact'
        404:
          description: test suite not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with getting test suite executions from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suite-executions:
    post:
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Selector'
      - $ref: '#/components/parameters/ConcurrencyLevel'
      tags:
      - test-suites
      summary: Starts new test suite executions
      description: New test suite executions returns new executions details on successful executions start
      operationId: executeTestSuites
      requestBody:
        description: body passed to configure executions
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestSuiteExecutionRequest'
      responses:
        201:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestSuiteExecutionsResult'
        400:
          description: problem with request body
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        502:
          description: problem with communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        500:
          description: problem with test suites executions
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
  /test-suite-executions/{executionID}/artifacts:
    get:
      parameters:
      - $ref: '#/components/parameters/executionID'
      tags:
      - test-suites
      summary: Get test suite execution artifacts
      description: Returns test suite execution artifacts with given executionID
      operationId: getTestSuiteExecutionArtifacts
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artifact'
        500:
          description: problem with getting test suite executions from storage
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
components:
  schemas:
    RunningContext:
      description: running context for test or test suite execution
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: One of possible context types
          enum:
          - userCLI
          - userUI
          - testsuite
          - testtrigger
          - scheduler
          - testworkflow
        context:
          type: string
          description: Context value depending from its type
    TestSuiteUpsertRequest:
      description: test suite create request body
      type: object
      required:
      - name
      - namespace
      allOf:
      - $ref: '#/components/schemas/TestSuite'
      - $ref: '#/components/schemas/ObjectRef'
    Artifact:
      type: object
      description: API server artifact
      properties:
        name:
          type: string
          description: artifact file path
        size:
          type: integer
          description: file size in bytes
        executionName:
          type: string
          description: execution name that produced the artifact
          example: test-1
        status:
          type: string
          enum:
          - ready
          - processing
          - failed
    TestSuiteStepExecutionSummary:
      description: Test suite execution summary
      type: object
      required:
      - id
      - name
      - status
      properties:
        id:
          type: string
          example: 62f395e004109209b50edfc4
        name:
          type: string
          description: execution name
          example: run:testkube/test1
        testName:
          type: string
          description: test name
          example: test1
        status:
          $ref: '#/components/schemas/ExecutionStatus'
        type:
          $ref: '#/components/schemas/TestSuiteStepType'
    TestSuiteExecutionSummary:
      description: Test execution summary
      type: object
      required:
      - id
      - name
      - testSuiteName
      - status
      properties:
        id:
          type: string
          description: execution id
          format: bson objectId
          example: 62f395e004109209b50edfc1
        name:
          type: string
          description: execution name
          example: test-suite1.needlessly-sweet-imp
        testSuiteName:
          type: string
          description: name of the test suite
          example: test-suite1
        status:
          $ref: '#/components/schemas/TestSuiteExecutionStatus'
        startTime:
          type: string
          description: test suite execution start time
          format: date-time
        endTime:
          type: string
          description: test suite execution end time
          format: date-time
        duration:
          type: string
          description: test suite execution duration
          example: 00:00:09
        durationMs:
          type: integer
          description: test suite execution duration in ms
          example: 9009
        execution:
          type: array
          items:
            $ref: '#/components/schemas/TestSuiteBatchStepExecutionSummary'
        labels:
          type: object
          description: test suite and execution labels
          additionalProperties:
            type: string
          example:
            env: prod
            app: backend
    TestSuiteWithExecution:
      description: Test suite with latest execution result
      type: object
      required:
      - testSuite
      properties:
        testSuite:
          $ref: '#/components/schemas/TestSuite'
        latestExecution:
          $ref: '#/components/schemas/TestSuiteExecution'
    TestStatus:
      type: object
      description: test status
      properties:
        latestExecution:
          $ref: '#/components/schemas/ExecutionCore'
    ArtifactRequest:
      description: artifact request body with test artifacts
      type: object
      properties:
        storageClassName:
          type: string
          description: artifact storage class name for container executor
          example: artifact-volume-local
        volumeMountPath:
          type: string
          description: artifact volume mount path for container executor
        dirs:
          type: array
          items:
            type: string
          description: artifact directories for scraping
        masks:
          type: array
          items:
            type: string
          description: regexp to filter scraped artifacts, single or comma separated
        storageBucket:
          type: string
          description: artifact bucket storage
          example: test1-artifacts
        omitFolderPerExecution:
          type: boolean
          description: don't use a separate folder for execution artifacts
        sharedBetweenPods:
          type: boolean
          description: whether to share volume between pods
        useDefaultStorageClassName:
          type: boolean
          description: whether to use default storage class name
        sidecarScraper:
          type: boolean
          description: run scraper as pod sidecar container
    Variables:
      type: object
      description: execution variables passed to executor converted to vars for usage in tests
      additionalProperties:
        $ref: '#/components/schemas/Variable'
      example:
        var1:
          name: var1
          type: basic
          value: value1
        secret1:
          name: secret1
          type: secret
          value: secretvalue1
    ExecutionsTotals:
      type: object
      description: various execution counters
      required:
      - results
      - passed
      - failed
      - queued
      - running
      - paused
      properties:
        results:
          type: integer
          description: the total number of executions available
        passed:
          type: integer
          description: the total number of passed executions available
        failed:
          type: integer
          description: the total number of failed executions available
        queued:
          type: integer
          description: the total number of queued executions available
        running:
          type: integer
          description: the total number of running executions available
    TestSuiteStepExecutionResultV2:
      description: execution result returned from executor
      type: object
      properties:
        step:
          $ref: '#/components/schemas/TestSuiteStepV2'
        test:
          $ref: '#/components/schemas/ObjectRef'
          description: object name and namespace
        execution:
          $ref: '#/components/schemas/Execution'
          description: test step execution
    PodRequest:
      description: pod request body
      type: object
      properties:
        resources:
          $ref: '#/components/schemas/PodResourcesRequest'
          description: pod resources request parameters
        podTemplate:
          type: string
          description: pod template extensions
        podTemplateReference:
          type: string
          description: name of the template resource
    DownloadArtifactOptions:
      description: options to download artifacts from previous steps
      type: object
      properties:
        allPreviousSteps:
          type: boolean
          default: false
        previousStepNumbers:
          type: array
          description: previous step numbers starting from 1
          items:
            type: integer
        previousTestNames:
          type: array
          description: previous test names
          items:
            type: string
    ConfigMapRef:
      required:
      - name
      - key
      type: object
      description: Testkube internal reference for data in Kubernetes config maps
      properties:
        namespace:
          type: string
          description: object kubernetes namespace
        name:
          type: string
          description: object name
        key:
          type: string
          description: object key
    TestSuiteStepExecuteTestV2:
      allOf:
      - $ref: '#/components/schemas/ObjectRef'
    Test:
      type: object
      properties:
        name:
          type: string
          description: test name
          example: test1
        namespace:
          type: string
          description: test namespace
          example: testkube
        description:
          type: string
          description: test description
          example: this test is used for that purpose
        type:
          type: string
          description: test type
          example: postman/collection
        content:
          $ref: '#/components/schemas/TestContent'
          description: test content
        source:
          type: string
          description: reference to test source resource
          example: my-private-repository-test
        created:
          type: string
          format: date-time
          example: '2022-07-30T06:54:15Z'
        labels:
          type: object
          description: test labels
          additionalProperties:
            type: string
          example:
            env: prod
            app: backend
        schedule:
          type: string
          description: schedule to run test
          example: '* * * * *'
        readOnly:
          type: boolean
          description: if test is offline and cannot be executed
        uploads:
          type: array
          items:
            type: string
          description: list of file paths that will be needed from uploads
          example:
          - settings/config.txt
        executionRequest:
          $ref: '#/components/schemas/ExecutionRequest'
        status:
          $ref: '#/components/schemas/TestStatus'
    ExecutionCore:
      type: object
      description: test execution core
      properties:
        id:
          type: string
          description: execution id
          format: bson objectId
          example: 62f395e004109209b50edfc4
        number:
          type: integer
          description: execution number
          example: 1
        startTime:
          type: string
          description: test start time
          format: date-time
        endTime:
          type: string
          description: test end time
          format: date-time
        status:
          $ref: '#/components/schemas/ExecutionStatus'
    TestSuiteExecutionRequest:
      description: test suite execution request body
      type: object
      properties:
        name:
          type: string
          description: test execution custom name
          example: testing with 1000 users
        number:
          type: integer
          description: test suite execution number
          example: 1
        namespace:
          type: string
          description: test kubernetes namespace ("testkube" when not set)
          example: testkube
        variables:
          $ref: '#/components/schemas/Variables'
        secretUUID:
          type: string
          description: secret uuid
          readOnly: true
          example: 7934600f-b367-48dd-b981-4353304362fb
        labels:
          type: object
          description: test suite labels
          additionalProperties:
            type: string
          example:
            users: '3'
            prefix: some-
        executionLabels:
          type: object
          description: execution labels
          additionalProperties:
            type: string
          example:
            users

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kubeshop/refs/heads/main/openapi/kubeshop-test-suites-api-openapi.yml