Create Test Plan(Appium2)

10 min

This endpoint creates a new test plan for an Appium2 project.

The request must include the project ID, plan name, user ID, plan type, and test run type. Mobile app IDs and environment definitions can also be provided when needed.

Endpoint Information

URL: {gateway-url}/plans

Method: POST

Authentication: Required (Bearer Token)

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token used for authentication. Example: Bearer <your_access_token>
Content-Type	Yes	Must be application/json.
X-Company-Id	Yes	The company ID used by the gateway to authorize and route the request.

Request Body

{
  "planName": "Sample Appium2 Test Plan",
  "type": "APPIUM",
  "projectId": 709,
  "userId": 1,
  "testRunType": "CROSS",
  "groupPlan": false,
  "description": "This is a sample Appium2 test plan.",
  "enabled": true,
  "deleted": false,
  "planParallelTestLimit": 5,
  "failedTestRetryCount": 2,
  "maxExecutionTime": 3600,
  "screenShotType": "YES",
  "videoEnabled": true,
  "uninstallApp": false,
  "clearAppData": false,
  "androidMobileAppId": null,
  "iosMobileAppId": 118,
  "isSigned": true,
  "alertsEnabled": false,
  "testDispatchMethodType": "ONE_BY_ONE"
}

Request Body Parameters

Field	Type	Required	Description
planName	String	Yes	The name of the test plan.
type	String	Yes	Plan type. For Appium2 projects, send APPIUM.
projectId	Long	Yes	The ID of the Appium2 project where the plan will be created.
userId	Long	Yes	The ID of the user creating the plan.
testRunType	String	Yes	Test run mode. Supported values: CROSS, SEQUENCE.
groupPlan	Boolean	No	Indicates whether the plan is a group plan.
description	String	No	Description of the test plan.
enabled	Boolean	No	Indicates whether the plan is active.
deleted	Boolean	No	Indicates whether the plan is marked as deleted.
planParallelTestLimit	Integer	No	Maximum parallel test limit for this plan.
failedTestRetryCount	Integer	No	Number of retries for failed tests.
maxExecutionTime	Integer	No	Maximum execution time in seconds.
screenShotType	String	No	Screenshot behavior. Supported values: YES, NO, ONLY_FAILURE. Default is YES.
videoEnabled	Boolean	No	Indicates whether video recording is enabled.
uninstallApp	Boolean	No	Indicates whether the mobile app should be uninstalled after execution.
clearAppData	Boolean	No	Indicates whether app data should be cleared before execution.
androidMobileAppId	Long	No	Android mobile app ID.
iosMobileAppId	Long	No	iOS mobile app ID.
isSigned	Boolean	No	Indicates whether the selected iOS app is signed.
alertsEnabled	Boolean	No	Indicates whether alerts are enabled for this plan.
testDispatchMethodType	String	No	Dispatch strategy. Supported values: ONE_BY_ONE, ALL_IN_ONE. Default is ONE_BY_ONE.
planEnvironmentsRequest	Array	No	Environment definitions to attach to the plan during creation.

Response

{
  "data": {
    "id": 766,
    "planName": "Sample Appium2 Test Plan",
    "groupPlan": false,
    "description": "This is a sample Appium2 test plan.",
    "enabled": true,
    "deleted": false,
    "planParallelTestLimit": 5,
    "periodId": null,
    "projectId": 709,
    "projectName": "Appium2GaugeProject",
    "projectTestFramework": "APPIUM2",
    "userId": 1,
    "companyId": 1,
    "failedTestRetryCount": 2,
    "maxExecutionTime": 3600,
    "testRunType": "CROSS",
    "screenShotType": "YES",
    "videoEnabled": true,
    "uninstallApp": false,
    "clearAppData": false,
    "iosMobileApp": {
      "id": 118,
      "mobileAppName": "demo",
      "mobileAppHash": "demo",
      "mobileAppMetadata": "demo",
      "operatingSystem": "IOS",
      "createdAt": "2026-08-18T12:08:41.165927056Z"
    },
    "androidMobileApp": null,
    "isSigned": true,
    "testFileType": "APPIUM_GAUGE",
    "testRunnerTool": "MAVEN",
    "testDispatchMethodType": "ONE_BY_ONE",
    "alertsEnabled": false
  }
}

Response Fields

Field	Type	Description
data	Object	Created test plan payload.
data.id	Long	Created test plan ID.
data.projectTestFramework	String	Framework of the related project. For Appium2 projects, this value is APPIUM2.
data.iosMobileApp	Object	Selected iOS mobile app summary, if provided.
data.androidMobileApp	Object	Selected Android mobile app summary, if provided.

Error Response Format

{
  "instance": "/plans",
  "status": 400,
  "title": "Bad Request",
  "type": "https://errors.testinium.com/validation",
  "timestamp": "2026-08-18T12:08:41.165927056Z",
  "errorType": "VALIDATION",
  "errors": [
    {
      "code": 20005,
      "message": "must not be null",
      "field": "planName"
    }
  ]
}

HTTP Error Codes

HTTP Code	Error Message	Description
400	Bad Request	Request body is invalid, required fields are missing, enum values are invalid, or Appium2 group plan validation failed.
401	Unauthorized	Authentication is missing or invalid.
403	Forbidden	User does not have permission for this operation or company.
404	Not Found	Project, mobile app, or another referenced resource could not be found.
409	Conflict	A plan with the same name already exists in the project.
500	Internal Server Error	An unexpected error occurred on the server side.
503	Service Unavailable	Routed service is unavailable or cannot be reached through the gateway.

Application Error Codes

Code	HTTP Status	Source	Description
10000	404	Project	Project not found.
10009	404	Project	Mobile app not found.
10011	409	Project	Plan name already exists.
10012	400	Project	For Appium2 group plans, environment count cannot be greater than planParallelTestLimit.
10001	401	Gateway	Authentication is required.
10002	401	Gateway	Token is invalid or cannot be verified.
10003	403	Gateway	Authorization failed for the requested resource.
10004	400	Gateway	A required header, such as X-Company-Id, is missing or invalid.
10008	503	Gateway	Routed service is unavailable.
20005	400	Common Validation	Request body validation failed.
20007	400	Common Validation	Invalid enum value.
20009	405	Common Validation	HTTP method is not supported.

Example Request

curl --location '{gateway-url}/plans' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Company-Id: <company_id>' \
  --data '{
    "planName": "Sample Appium2 Test Plan",
    "type": "APPIUM",
    "projectId": 709,
    "userId": 1,
    "testRunType": "CROSS",
    "groupPlan": false,
    "description": "This is a sample Appium2 test plan.",
    "enabled": true,
    "deleted": false,
    "planParallelTestLimit": 5,
    "failedTestRetryCount": 2,
    "maxExecutionTime": 3600,
    "screenShotType": "YES",
    "videoEnabled": true,
    "uninstallApp": false,
    "clearAppData": false,
    "androidMobileAppId": null,
    "iosMobileAppId": 118,
    "isSigned": true,
    "alertsEnabled": false,
    "testDispatchMethodType": "ONE_BY_ONE"
  }'