--- title: Run Test Plan slug: suite-documentation/mYi3-run-test-plan docTags: createdAt: 2026-08-27T07:34:40.303Z --- ## Endpoint Information - **URL**: `{gateway-url}/queue` - **Method**: `POST` - **Authentication**: Required (`Bearer Token`) - **Company Header**: Required (`X-Company-Id`) ## Headers | Header | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------------------------------------------------- | | `Authorization` | String | Yes | Bearer token used for authentication. Example: `Bearer `. | | `X-Company-Id` | Long | Yes | The company ID used to scope the request. | | `Content-Type` | String | Yes | Must be `application/json`. | | `Accept` | String | No | Recommended value: `application/json`. | ## Request Body ```json { "planId": 681, "userId": 1, "forceRun": false, "schedulerTriggered": false, "description": "Triggered from API" } ``` ## Request Body Parameters | Parameter | Type | Required | Description | | -------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `planId` | Long | Yes | The unique ID of the test plan to execute. | | `userId` | Long | Yes | The unique ID of the user who runs the plan. | | `forceRun` | Boolean | No | Indicates whether the run should skip environment registration validation. Default value is `false`. This does not bypass the already-running execution control. | | `schedulerTriggered` | Boolean | No | Indicates whether the run request was triggered by the scheduler. If `true`, the created execution is marked as scheduled. Default value is `false`. | | `description` | String | No | Optional execution description. | ## Response Body If the run request is processed successfully, the endpoint returns HTTP `200 OK` with an empty JSON object. ```json {} ``` ## Response Fields This endpoint does not return response fields. The response does not include `data`, `result.code`, or `result.message`. ## Behavior Notes - This endpoint starts a test plan execution. - The service validates the test plan by `planId` and the user by `userId`. - The plan and user lookup are scoped by `X-Company-Id`. - The plan must be enabled and not deleted. - The plan must have at least one scenario. - The plan must have at least one active environment when the selected execution type requires an environment. - If another execution is already active for the same plan, the request fails with conflict. - If `forceRun` is `false`, the service validates whether selected environments are registered/available for execution. - If `forceRun` is `true`, environment registration validation is skipped. - `forceRun` does not skip the already-running execution control. - If `schedulerTriggered` is `true`, the created test execution is marked as scheduled. - For Enterprise project type, build-service validation is skipped by the queue service. - For non-Enterprise project type, a build must be assigned before execution. ## Error Response Format Error responses use the common problem detail format. ```json { "instance": "/queue", "status": 404, "title": "Not Found", "type": "https://errors.testinium.com/exception", "timestamp": "2026-08-27T07:12:26.871905643Z", "errorType": "EXCEPTION", "errors": { "code": 10000, "message": "Plan with id 681 not found!" } } ``` ## Validation Error Response Example ```json { "instance": "/queue", "status": 400, "title": "Bad Request", "type": "https://errors.testinium.com/validation", "timestamp": "2026-08-27T07:12:26.871905643Z", "errorType": "VALIDATION", "errors": [ { "code": 20005, "message": "must not be null", "field": "planId" } ] } ``` ## Confirmation Error Response Example This response can be returned when selected environments are not registered and `forceRun` is `false`. ```json { "instance": "/queue", "status": 422, "title": "Unprocessable Entity", "type": "https://errors.testinium.com/confirmation", "timestamp": "2026-08-27T07:12:26.871905643Z", "errorType": "CONFIRMATION", "errors": { "code": 10008, "message": "Environment is not registered" } } ``` ## Error Codes | HTTP Code | Error Message | Description | | --------- | ----------------------- | ---------------------------------------------------------------------------------------------- | | 400 | `BAD_REQUEST` | The request body is invalid, required fields are missing, or a required header is missing. | | 401 | `UNAUTHORIZED` | Authentication failed, authentication is required, or the token is invalid. | | 403 | `FORBIDDEN` | The user does not have permission to access the requested company or resource. | | 404 | `NOT_FOUND` | The requested plan, user, plan environment, test result, or test execution could not be found. | | 409 | `CONFLICT` | The test plan already has an active execution. | | 410 | `GONE` | The requested plan or related entity is disabled or deleted. | | 422 | `UNPROCESSABLE_ENTITY` | The plan cannot be executed because required execution data is missing or invalid. | | 503 | `SERVICE_UNAVAILABLE` | The queue service or a downstream service is unavailable. | | 500 | `INTERNAL_SERVER_ERROR` | An unexpected error occurred on the server side. | ## Application Error Codes | Code | Error Type | HTTP Code | Source | Description | | ------- | -------------- | --------- | ------- | ----------------------------------------------------------------------------- | | `10000` | `EXCEPTION` | 404 | Queue | The requested test plan could not be found. | | `10001` | `EXCEPTION` | 404 | Queue | The test plan has no active environment. | | `10002` | `EXCEPTION` | 404 | Queue | The requested user could not be found or does not have company access. | | `10004` | `EXCEPTION` | 410 | Queue | The requested entity is not enabled. | | `10005` | `EXCEPTION` | 410 | Queue | The requested entity is deleted. | | `10007` | `EXCEPTION` | 422 | Queue | Required mobile app file is missing for the plan. | | `10008` | `CONFIRMATION` | 422 | Queue | One or more selected environments are not registered. | | `10012` | `EXCEPTION` | 409 | Queue | The test plan already has an active execution. | | `10013` | `EXCEPTION` | 422 | Queue | The test plan has no scenarios. | | `10014` | `EXCEPTION` | 422 | Queue | Build is not assigned. Applies to non-Enterprise project type. | | `20005` | `VALIDATION` | 400 | Common | Request body validation failed. For example, `planId` or `userId` is missing. | | `20009` | `EXCEPTION` | 405 | Common | The HTTP method is not supported. | | `90003` | `EXCEPTION` | 4xx / 5xx | Common | A downstream service failed to process the request. | | `10000` | `EXCEPTION` | 401 | Gateway | Authentication failed. | | `10001` | `EXCEPTION` | 401 | Gateway | Authentication is required to access this resource. | | `10002` | `EXCEPTION` | 401 | Gateway | The provided token is invalid. | | `10003` | `EXCEPTION` | 403 | Gateway | The user is not authorized for the requested resource. | | `10004` | `EXCEPTION` | 400 | Gateway | A required header is missing. For example, `X-Company-Id` is not provided. | | `10005` | `EXCEPTION` | 401 | Gateway | A required token claim is missing. | | `10007` | `EXCEPTION` | 403 | Gateway | The user does not have access to the requested resource. | | `10008` | `EXCEPTION` | 503 | Gateway | The routed queue service is unavailable. | ## Example Request ```bash curl --location '{gateway-url}/queue' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-Company-Id: ' \ --data '{ "planId": , "userId": , "forceRun": false, "schedulerTriggered": false, "description": "Triggered from API" }' ``` ## Example Force Run Request ```bash curl --location '{gateway-url}/queue' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-Company-Id: ' \ --data '{ "planId": , "userId": , "forceRun": true, "schedulerTriggered": false, "description": "Forced from API" }' ```