{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":491,"path":"api-reference/rest-apis/cloudrunner-testrunner-api.md","title":"Cloud Runner Test Runner REST API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Cloud Runner Test Runner REST API\n\nManages tests to be executed in a cloud runner for Automated Test Framework \\(ATF\\).\n\nThe Cloud Runner Test Runner API requires the [ATF Test Generator and Cloud Runner](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/atf-tg-cr-intro.md) \\(sn\\_atf\\_tg\\) plugin. The methods available with this API run in the **now** namespace and can be called using API Name, **One-click regression testing for ATF**, in the REST API Explorer. The admin role is required to access this API.\n\nYou can use this API for the following tasks:\n\n-   Start an ATF test or test suite in the Cloud Runner browser.\n-   Check the progress of the test job.\n-   Cancel the test job.\n\nThe Cloud Runner Test Runner API may be used in tandem with the [Cloud Runner Test Generation REST API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/cloudrunner-testgeneration-api.md) and [Cloud Runner Test User REST API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/cloudrunner-testuser-api.md). For instance, you can generate a test \\(Cloud Runner Test Generation API\\) and then get the progress of the test in the browser orchestration queue \\(Cloud Runner TEST Generation API\\) and check the number of tests that passed or failed.\n\nTo view the Server API reference documentation of this API, see [Cloud Runner TestRunnerApi – Scoped, Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/cloudrnr-TestRunnerAPI-scoped.md).\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Cloud Runner Test Runner - GET /now/sn\\_atf\\_tg/test\\_runner\\_progress\n\nProvides the status of each test ran for a provided Browser Orchestration Queue \\(BOQ\\) record.\n\n### URL format\n\nDefault URL: GET `/api/now/sn_atf_tg/test_runner_progress`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsnboqId\n\n</td><td>\n\nRequired if **rootTrackerId** isn't passed.\n\n Sys\\_id of the Browser Orchestration Queue \\(BOQ\\) \\[sn\\_atf\\_tg\\_sn\\_boq\\] record associated with the test runner job to retrieve.\n\n Data type: String\n\n</td></tr><tr><td>\n\nrootTrackerId\n\n</td><td>\n\nRequired if **snboqId** isn't passed. Sys\\_id of the top-level record in the Execution Tracker \\[sys\\_execution\\_tracker\\] table that represents the test run to retrieve.\n\nData type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_vdy_gwz_31c\"><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td>\n\nSuccessfully retrieved the progress of the BOQ job.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError getting BOQ record status. Returns one of the following messages:-   No BOQ ID passed in – No BOQ ID was provided. Add the BOQ ID to the request body.\n-   Unable to find BOQ record – Invalid Sys ID. Verify that the sys\\_id of the BOQ record is valid and the record exists.\n\n</td></tr><tr><td>\n\n403\n\n</td><td>\n\nError granting user access to the endpoint. Ensure that the user has the admin role.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the progress results of the test runner job or a message explaining why the request failed.Data type: Object\n\n```\n\"result\": { \n    \"progress\": 100, \n    \"state\": \"completed\" \n  }\n```\n\nOr:\n\n```\n{\n  \"result\": { \n    \"message\": \"String\" \n  } \n}\n```\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nError message detailing why the test runner progress can't be retrieved. The message parameter isn't returned in a successful response.Data type: String\n\n</td></tr><tr><td>\n\nresult.progress\n\n</td><td>\n\nPercentage that indicates how close to completion a test is while in a running state.Data type: Number\n\n</td></tr><tr><td>\n\nresult.state\n\n</td><td>\n\nCurrent status of the BOQ record. Possible values:\n\n-   `Browsers requested`: A request has been sent to the cloud infrastructure to start browsers for test generation or test running.\n-   `Completed`: The test task is complete.\n-   `Failed state`: The test task failed.\n-   `Pending`: The requested test activity has been created and waiting to be executed.\n-   `Processing`: The instance is scanning for records to ensure that the execution trackers are marked for cloud runner before the request is sent to the cloud infrastructure.\n-   `Running`: The cloud infrastructure browsers find and execute pending tests.\n\nData type: String\n\n</td></tr></tbody>\n</table>### Retrieve test progress using snboqId\n\nThe following request retrieves the test runner job progress of the Browser Orchestration Queue \\(BOQ\\) \\[sn\\_atf\\_tg\\_sn\\_boq\\] record.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress?snboqId=f6e5d4c3b2a1908070605040302010ab\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username:password\"\n```\n\nThe response indicates that the test is 100% complete.\n\n```\n{ \n  \"result\": { \n    \"progress\": 100, \n    \"state\": \"completed\" \n  } \n}\n```\n\n### Retrieve test progress using rootTrackerId\n\nThe following request retrieves the test runner job progress of the Execution Tracker \\[sys\\_execution\\_tracker\\] record.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress?rootTrackerId=0a1b2c3d4e5f67890a1b2c3d4e5f6789\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username:password\"\n\n```\n\nThe response indicates that the test is 45% complete.\n\n```\n{ \n  \"result\": { \n    \"progress\": 45, \n    \"state\": \"running\" \n    \"message\": \"Test execution in progress.\",\n  } \n}\n```\n\n### Invalid or missing rootTrackerId or snboqId value\n\nThe following example demonstrates the response if the request has a missing or invalid rootTrackerId or snboqId value.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username:password\"\n```\n\nResponse body \\(400 Bad Request\\):\n\n```\n{\n  \"error\": {\n    \"message\": \"Invalid request. Either snboqId or rootTrackerId must be provided.\",\n    \"status\": \"failure\"\n  }\n}\n```\n\n## Cloud Runner Test Runner - POST /now/sn\\_atf\\_tg/cancel\\_test\\_runner\n\nSets the test runner job to complete status and cancels any generated tests that are running.\n\n### URL format\n\nDefault URL: GET `/now/sn_atf_tg/cancel_test_runner`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsnboqId\n\n</td><td>\n\nRequired if **rootTrackerId** isn't passed.\n\n Sys\\_id of the Browser Orchestration Queue \\(BOQ\\) \\[sn\\_atf\\_tg\\_sn\\_boq\\] record associated with the test runner job to cancel.\n\n Data type: String\n\n</td></tr><tr><td>\n\nrootTrackerId\n\n</td><td>\n\nRequired if **snboqId** isn't passed. Sys\\_id of the top-level record in the Execution Tracker \\[sys\\_execution\\_tracker\\] table that represents the test run to cancel.\n\nData type: String\n\n</td></tr></tbody>\n</table>### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_ism_z2j_41c\" class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td id=\"entry-200-status-code\">\n\nSuccessful. The request was successfully processed.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError canceling job. Returns one of the following messages:-   No BOQ ID passed in – No BOQ ID was provided. Add the BOQ ID to the request body.\n-   Unable to find BOQ record – Invalid Sys ID. Verify that the sys\\_id of the BOQ record is valid and the record exists.\n\n</td></tr><tr><td>\n\n403\n\n</td><td>\n\nError granting user access to the endpoint. Ensure that the user has the admin role.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the results of the request.Data type: Object\n\n```\n\n  \"result\": { \n    \"message\": String\n  }\n```\n\n</td></tr><tr><td>\n\nresult.status\n\n</td><td>\n\nSuccess status of the cancellation.Data type: String\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nMessage detailing whether the test cancellation was successful.Data type: String\n\n</td></tr></tbody>\n</table>### Cancel the test runner job using snboqId\n\nThe following example shows how to cancel a test runner request using the sys\\_id of the BOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\] record.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_runner\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username:password\" \\\n--data '{\n  \"snboqId\": \"f6e5d4c3b2a1908070605040302010ab\"\n}'\n```\n\nThe response message indicating that the test runner is successfully canceled.\n\n```\n{\n  \"result\": {\n    \"status\": \"success\",\n    \"message\": \"Test run cancelled successfully.\"\n  }\n}\n```\n\n### Cancel the test runner job using rootTrackerId\n\nThe following example shows how to cancel a test runner request according to the sys\\_id of the Execution Tracker \\[sys\\_execution\\_tracker\\] record.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_runner\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username:password\" \\\n--data '{\n  \"rootTrackerId\": \"0a1b2c3d4e5f67890a1b2c3d4e5f6789\"\n}'\n```\n\nSuccessful response body \\(200\\):\n\n```\n{\n  \"result\": {\n    \"status\": \"success\",\n    \"message\": \"Test run cancelled successfully.\"\n  }\n}\n```\n\n### Error when neither rootTrackerId or snboqId is passed\n\nThe following example shows the response message that's returned when neither **rootTrackerId** or **snboqId** are provided in the request.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_runner\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username:password\" \\\n--data '{}'\n```\n\nResponse body \\(400 Bad Request\\):\n\n```\n{\n  \"error\": {\n    \"message\": \"Invalid request. Either snboqId or rootTrackerId must be provided.\",\n    \"status\": \"failure\"\n  }\n}\n```\n\n## Cloud Runner Test Runner - POST /now/sn\\_atf\\_tg/test\\_runner\n\nInserts a test runner job into the Browser Orchestration Queue \\(BOQ\\) table record for given test or test suite, which is then run on the cloud runner. Optionally choose to wait to insert the record before processing a response.\n\n### URL format\n\nDefault URL: POST `api/now/sn_atf_tg/test_runner`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ntestId\n\n</td><td>\n\nSys\\_id of the test \\[sys\\_atf\\_test\\] or test suite \\[sys\\_atf\\_test\\_suite\\] to run on the cloud runner.\n\n</td></tr><tr><td>\n\nsync\n\n</td><td>\n\nOptional. Flag that indicates whether to wait to process the job before the Browser Orchestration Queue \\[sn\\_atf\\_tg\\_sn\\_boq\\] record is inserted.Valid values:\n\n-   true: Wait for the record to be inserted before responding. Returns the **snboqId** value in the response.\n-   false: Return a response immediately without waiting for the insertion. Returns the **rootTrackerId** \\(sys\\_id of the entire test\\) value in the response.\n\nDefault: true\n\n</td></tr></tbody>\n</table>### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_gcx_1fj_41c\" class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td>\n\nSuccessfully inserted a test runner BOQ job.\n\n</td></tr><tr><td>\n\n202\n\n</td><td>\n\nIf the BOQ record doesn't get inserted in time due to a timeout issue, the test continues running. In other words, the BOQ job accepted but not yet confirmed.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError starting the test runner job. Returns one of the following messages:-   Unable to find test or test suite with Sys ID &lt;testId&gt; – Invalid test ID. Ensure that the sys\\_id of the test \\(sys\\_atf\\_test\\) or test suite \\(sys\\_atf\\_test\\_suite\\) record is valid and the record exists.\n-   No Test ID passed in – No test ID was passed. Add the test ID to the request body.\n\n</td></tr><tr><td>\n\n403\n\n</td><td>\n\nError granting user access to the endpoint. Ensure that the user has the admin role.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the results of the request.Data type: Object\n\n```\n{ \n  \"result\": { \n    \"snboqId\": \"String\" \n  } \n}\n```\n\nOr:\n\n```\n\n  \"result\": { \n    \"message\": \"String\"\n  }\n```\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nError message detailing why the test runner can't be started.Data type: String\n\n</td></tr><tr><td>\n\nresult.snboqId\n\n</td><td>\n\nReturned when `sync=true` \\(or defaulted\\) in the request. Sys\\_id of the BOQ record that is inserted when test runner starts.Data type: String\n\nTable: BOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\]\n\n</td></tr><tr><td>\n\nresult.rootTrackerId\n\n</td><td>\n\nReturned when `sync=false` in the request. Sys\\_id of the Execution Tracker \\[sys\\_execution\\_tracker\\] record for the entire test run.\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following request inserts a test runner job into the BOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\] table.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner\" \\ \n--request POST \\ \n--header \"Accept:application/json\" \\ \n--header \"Content-Type:application/json\" \\ \n--data \"{\\\"testId\\\":\\\"<sys_id of ATF test or test suite>\\\"}\" \\ \n--user \"username:password\"\n```\n\nThe response body returns the sys\\_id of the test runner job that was successfully inserted.\n\n```\n{ \n  \"result\": { \n    \"snboqId\": \"<sys_id of newly inserted SNBOQ record>\" \n  } \n}\n```\n\nSynchronous request \\(`sync=true`\\)\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username:password\" \\\n--data '{\n  \"testId\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6\",\n  \"browser\": \"Chrome\",\n  \"sync\": true\n}'\n```\n\nSuccessful response \\(200\\):\n\n```\n{\n  \"result\": {\n    \"snboqId\": \"f6e5d4c3b2a1908070605040302010ab\",\n    \"status\": \"success\",\n    \"message\": \"Test run started successfully.\"\n  }\n}\n```\n\nAsynchronous request \\(`sync=false`\\)\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username:password\" \\\n--data '{\n  \"testId\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6\",\n  \"browser\": \"Chrome\",\n  \"sync\": false\n}'\n```\n\nSuccessful response \\(200\\):\n\n```\n{\n  \"result\": {\n    \"rootTrackerId\": \"0a1b2c3d4e5f67890a1b2c3d4e5f6789\",\n    \"status\": \"success\",\n    \"message\": \"Test run started successfully.\"\n  }\n}\n```\n\nSynchronous request where the SNBOQ record doesn't insert in time.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_runner\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username:password\" \\\n--data '{\n  \"testId\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6\",\n  \"browser\": \"Chrome\"\n}'\n```\n\nResponse \\(202 Accepted\\):\n\n```\n{\n  \"result\": {\n    \"rootTrackerId\": \"0a1b2c3d4e5f67890a1b2c3d4e5f6789\",\n    \"status\": \"accepted\",\n    \"message\": \"The test run has been initiated but the Browser Orchestration Queue record was not inserted in time. The test will most likely continue to run.\"\n  }\n}\n```\n\n"}}