Kubeshop test-suites API

openapi: 3.2.0
info:
  title: Testkube Test Suites API
  description: Testkube provides a Kubernetes-native framework for test definition, execution and results
  contact:
    email: contact@testkube.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
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'
components:
  schemas:
    TestSuiteStepV2:
      type: object
      required:
      - name
      - type
      - stopTestOnFailure
      properties:
        stopTestOnFailure:
          type: boolean
          default: true
        execute:
          $ref: '#/components/schemas/TestSuiteStepExecuteTestV2'
        delay:
          $ref: '#/components/schemas/TestSuiteStepDelayV2'
    TestSuiteStepExecutionRequest:
      description: test step execution request body
      type: object
      readOnly: true
      properties:
        executionLabels:
          type: object
          description: test execution labels
          additionalProperties:
            type: string
          example:
            users: '3'
            prefix: some-
        variables:
          $ref: '#/components/schemas/Variables'
        command:
          type: array
          description: executor image command
          items:
            type: string
          example:
          - curl
        args:
          type: array
          description: additional executor binary arguments
          items:
            type: string
          example:
          - --repeats
          - '5'
          - --insecure
        args_mode:
          type: string
          description: usage mode for arguments
          enum:
          - append
          - override
          - replace
        sync:
          type: boolean
          description: whether to start execution sync or async
        httpProxy:
          type: string
          description: http proxy for executor containers
          example: user:pass@my.proxy.server:8080
        httpsProxy:
          type: string
          description: https proxy for executor containers
          example: user:pass@my.proxy.server:8081
        negativeTest:
          type: boolean
          description: whether to run test as negative test
          example: false
        jobTemplate:
          type: string
          description: job template extensions
        jobTemplateReference:
          type: string
          description: name of the template resource
        cronJobTemplate:
          type: string
          description: cron job template extensions
        cronJobTemplateReference:
          type: string
          description: name of the template resource
        scraperTemplate:
          type: string
          description: scraper template extensions
        scraperTemplateReference:
          type: string
          description: name of the template resource
        pvcTemplate:
          type: string
          description: pvc template extensions
        pvcTemplateReference:
          type: string
          description: name of the template resource
        runningContext:
          $ref: '#/components/schemas/RunningContext'
          description: running context for the test execution
        disableWebhooks:
          type: boolean
          description: whether webhooks on the execution of this step are disabled
          default: false
          example:
          - true
          - false
    TestSuiteBatchStepExecutionResult:
      description: execution result returned from executor
      type: object
      properties:
        step:
          $ref: '#/components/schemas/TestSuiteBatchStep'
        execute:
          type: array
          items:
            $ref: '#/components/schemas/TestSuiteStepExecutionResult'
        startTime:
          type: string
          description: step start time
          format: date-time
        endTime:
          type: string
          description: step end time
          format: date-time
        duration:
          type: string
          description: step duration
          example: 2m
    TestSuiteExecutionStatus:
      type: string
      enum:
      - queued
      - running
      - passed
      - failed
      - aborting
      - aborted
      - timeout
    TestSuiteWithExecution:
      description: Test suite with latest execution result
      type: object
      required:
      - testSuite
      properties:
        testSuite:
          $ref: '#/components/schemas/TestSuite'
        latestExecution:
          $ref: '#/components/schemas/TestSuiteExecution'
    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'
    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'
    PodResourcesRequest:
      description: pod resources request specification
      type: object
      properties:
        requests:
          $ref: '#/components/schemas/ResourceRequest'
          description: pod resources requests
        limits:
          $ref: '#/components/schemas/ResourceRequest'
          description: pod resources limits
    RepositoryParameters:
      description: repository parameters for tests in git repositories
      type: object
      properties:
        branch:
          type: string
          description: branch/tag name for checkout
          example: main
        commit:
          type: string
          description: commit id (sha) for checkout
          example: b928cbb7186944ab9275937ec1ac3d3738ca2e1d
        path:
          type: string
          description: if needed we can checkout particular path (dir or file) in case of BIG/mono repositories
          example: test/perf
        workingDir:
          type: string
          description: if provided we checkout the whole repository and run test from this directory
          example: /
    LocalObjectReference:
      description: Reference to Kubernetes object
      type: object
      properties:
        name:
          type: string
    ExecutionRequest:
      description: test execution request body
      type: object
      properties:
        id:
          type: string
          description: execution id
          format: bson objectId
          example: 62f395e004109209b50edfc1
        name:
          type: string
          description: test execution custom name
          example: testing with 1000 users
        testSuiteName:
          type: string
          description: unique test suite name (CRD Test suite name), if it's run as a part of test suite
          example: test-suite1
        number:
          type: integer
          description: test execution number
        executionLabels:
          type: object
          description: test execution labels
          additionalProperties:
            type: string
          example:
            users: '3'
            prefix: some-
        namespace:
          type: string
          description: test kubernetes namespace ("testkube" when not set)
          example: testkube
        isVariablesFileUploaded:
          type: boolean
          description: in case the variables file is too big, it will be uploaded
          example: false
        variablesFile:
          type: string
          description: variables file content - need to be in format for particular executor (e.g. postman envs file)
        variables:
          $ref: '#/components/schemas/Variables'
        testSecretUUID:
          type: string
          description: test secret uuid
          readOnly: true
          example: 7934600f-b367-48dd-b981-4353304362fb
        testSuiteSecretUUID:
          type: string
          description: test suite secret uuid, if it's run as a part of test suite
          readOnly: true
          example: 7934600f-b367-48dd-b981-4353304362fb
        command:
          type: array
          description: executor image command
          items:
            type: string
          example:
          - curl
        args:
          type: array
          description: additional executor binary arguments
          items:
            type: string
          example:
          - --repeats
          - '5'
          - --insecure
        args_mode:
          type: string
          description: usage mode for arguments
          enum:
          - append
          - override
          - replace
        image:
          type: string
          description: container image, executor will run inside this image
          example: kubeshop/testkube-executor-custom:1.10.11-dev-0a9c91
        imagePullSecrets:
          type: array
          description: container image pull secrets
          items:
            $ref: '#/components/schemas/LocalObjectReference'
        envs:
          deprecated: true
          type: object
          description: 'Environment variables passed to executor. Deprecated: use Basic Variables instead'
          additionalProperties:
            type: string
          example:
            record: 'true'
            prefix: some-
        secretEnvs:
          deprecated: true
          type: object
          description: 'Execution variables passed to executor from secrets. Deprecated: use Secret Variables instead'
          additionalProperties:
            type: string
          example:
            secret_key_name1: secret-name
            secret_Key_name2: secret-name
        sync:
          type: boolean
          description: whether to start execution sync or async
        httpProxy:
          type: string
          description: http proxy for executor containers
          example: user:pass@my.proxy.server:8080
        httpsProxy:
          type: string
          description: https proxy for executor containers
          example: user:pass@my.proxy.server:8081
        negativeTest:
          type: boolean
          description: whether to run test as negative test
          example: false
        isNegativeTestChangedOnRun:
          type: boolean
          description: whether negativeTest was changed by user
          example: false
        activeDeadlineSeconds:
          type: integer
          format: int64
          description: duration in seconds the test may be active, until its stopped
          example: 1
        uploads:
          type: array
          items:
            type: string
          description: list of file paths that need to be copied into the test from uploads
          example:
          - settings/config.txt
        bucketName:
          type: string
          description: minio bucket name to get uploads from
          example: execution-c01d7cf6-ec3f-47f0-9556-a5d6e9009a43
        artifactRequest:
          $ref: '#/components/schemas/ArtifactRequest'
          description: configuration parameters for storing test artifacts
        jobTemplate:
          type: string
          description: job template extensions
        jobTemplateReference:
          type: string
          description: name of the template resource
        cronJobTemplate:
          type: string
          description: cron job template extensions
        cronJobTemplateReference:
          type: string
          description: name of the template resource
        contentRequest:
          $ref: '#/components/schemas/TestContentRequest'
          description: adjusting parameters for test content
        preRunScript:
          type: string
          description: script to run before test execution
          example: echo -n '$SECRET_ENV' > ./secret_file
        postRunScript:
          type: string
          description: script to run after test execution
          example: sleep 30
        executePostRunScriptBeforeScraping:
          type: boolean
          description: execute post run script before scraping (prebuilt executor only)
        sourceScripts:
          type: boolean
          description: run scripts using source command (container executor only)
        scraperTemplate:
          type: string
          description: scraper template extensions
        scraperTemplateReference:
          type: string
          description: name of the template resource
        pvcTemplate:
          type: string
          description: pvc template extensions
        pvcTemplateReference:
          type: string
          description: name of the template resource
        envConfigMaps:
          type: array
          description: config map references
          items:
            $ref: '#/components/schemas/EnvReference'
        envSecrets:
          type: array
          description: secret references
          items:
            $ref: '#/components/schemas/EnvReference'
        runningContext:
          $ref: '#/components/schemas/RunningContext'
          description: running context for the test execution
        testExecutionName:
          type: string
          description: test execution name started the test execution
        downloadArtifactExecutionIDs:
          type: array
          description: execution ids for artifacts to download
          items:
            type: string
        downloadArtifactTestNames:
          type: array
          description: test names for artifacts to download from latest executions
          items:
            type: string
        slavePodRequest:
          $ref: '#/components/schemas/PodRequest'
          description: configuration parameters for executed slave pods
        executionNamespace:
          type: string
          description: namespace for test execution (Pro edition only)
        disableWebhooks:
          type: boolean
          description: whether webhooks on this execution are disabled
          default: false
          example:
          - true
          - false
    AssertionResult:
      description: execution result data
      type: object
      properties:
        name:
          type: string
          example: assertion1
        status:
          type: string
          enum:
          - passed
          - failed
        errorMessage:
          type:
          - string
          - 'null'
    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'
    TestSuiteExecutionCore:
      type: object
      description: test suite execution core
      properties:
        id:
          type: string
          description: execution id
          format: bson objectId
          example: 62f395e004109209b50edfc4
        startTime:
          type: string
          description: test suite execution start time
          format: date-time
        endTime:
          type: string
          description: test suite execution end time
          format: date-time
        status:
          $ref: '#/components/schemas/TestSuiteExecutionStatus'
    SecretRef:
      required:
      - name
      - key
      type: object
      description: Testkube internal reference for secret storage in Kubernetes secrets
      properties:
        namespace:
          type: string
          description: object kubernetes namespace
        name:
          type: string
          description: object name
        key:
          type: string
          description: object key
    TestContent:
      type: object
      properties:
        type:
          type: string
          description: "type of sources a runner can get data from.\n  string: String content (e.g. Postman JSON file).\n  file-uri: content stored on the webserver.\n  git-file: the file stored in the Git repo in the given repository.path field (Deprecated: use git instead).\n  git-dir: the entire git repo or git subdirectory depending on the  repository.path field (Testkube does a shadow clone and sparse checkout to limit IOs in the case of monorepos). (Deprecated: use git instead).\n  git: automatically provisions either a file, directory or whole git repository depending on the repository.path field.\n"
          enum:
          - string
          - file-uri
          - git-file
          - git-dir
          - git
        repository:
          $ref: '#/components/schemas/Repository'
        data:
          type: string
          description: test content data as string
        uri:
          type: string
          description: test content
          example: https://github.com/kubeshop/testkube
    TestSuiteStep:
      type: object
      properties:
        test:
          type: string
          description: object name
          example: name
        delay:
          type: string
          format: duration
          example: 1s
          description: delay duration in time units
        executionRequest:
          $ref: '#/components/schemas/TestSuiteStepExecutionRequest'
          description: test suite step execution request parameters
    TestSuiteUpdateRequest:
      description: test suite update body
      type:
      - object
      - 'null'
      allOf:
      - $ref: '#/components/schemas/TestSuite'
      - $ref: '#/components/schemas/ObjectRef'
    VariableType:
      type: string
      enum:
      - basic
      - secret
    TestSuiteStepDelayV2:
      type: object
      required:
      - duration
      properties:
        duration:
          type: integer
          default: 0
          description: delay duration in milliseconds
    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
    Execution:
      type: object
      description: test execution
      properties:
        id:
          type: string
          description: execution id
          format: bson objectId
          example: 62f395e004109209b50edfc4
        testName:
          type: string
          description: unique test name (CRD Test name)
          example: example-test
        testSuiteName:
          type: string
          description: unique test suite name (CRD Test suite name), if it's run as a part of test suite
          example: test-suite1
        testNamespace:
          type: string
          description: test namespace
          example: testkube
  

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