{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1137,"path":"api-reference/server-api-reference/cloudrnr-TestRunnerAPI-scoped.md","title":"Cloud Runner TestRunnerApi – Scoped, Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# Cloud Runner TestRunnerApi – Scoped, Global\n\nManages tests to be executed in a cloud runner for Automated Test Framework \\(ATF\\). This API is part of the CloudRunnerApi script include.\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\nIn global scope, this API is executed within the sn\\_atf\\_tg namespace. You must have 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 activated to use this API.\n\nSee also:\n\n- [Cloud Runner TestGenerationApi – Scoped, Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/cloudrnr-TestGenerationAPI-scoped.md)\n- [Cloud Runner TestUserApi – Scoped, Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/cloudrnr-TestUserAPI-scoped.md)\n- [Cloud Runner Test User REST API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/cloudrunner-testuser-api.md)\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## TestRunnerApi – cancelJob\\(String snboqId\\)\n\nSets the test runner job to complete status and cancels any generated tests that are running.\n\n|Name|Type|Description|\n|----|----|-----------|\n|snboqId|String|Sys\\_id of the Browser Orchestration Queue \\(BOQ\\) \\[sn\\_atf\\_tg\\_sn\\_boq\\] record associated with the test runner job to cancel.|\n\n|Type|Description|\n|----|-----------|\n|null|Null if successful, error message otherwise.|\n\nThe following example shows how to cancel a test job using snboqId:\n\n```\nvar testRunnerApi = new sn_atf_tg.TestRunnerApi();\n\n// Cancel job using snboqId\nvar cancelResult = testRunnerApi.cancelJob('f6e5d4c3b2a1908070605040302010ab', null);\n\nif (cancelResult.status === 'success') {\n gs.info('Test job cancelled successfully');\n} else {\n gs.error('Failed to cancel test job: ' + cancelResult.message);\n}\n```\n\nOutput:\n\n```\nTest job cancelled successfully\n```\n\n## TestRunnerApi – progress\\(String snboqId\\)\n\nProvides the status of each test ran for a provided Browser Orchestration Queue \\(BOQ\\) record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|snboqId|String|Sys\\_id of the Browser Orchestration Queue \\(BOQ\\) \\[sn\\_atf\\_tg\\_sn\\_boq\\] record associated with the test runner job to retrieve.|\n\n\n
\n\nType\n\n\n\nDescription\n\n
\n\nObject\n\n\n\nJSON object indicating test progress.```\n{\n \"progress\": Number,\n \"state\": \"String\"\n}\n```\n\n
\n\nObject.progress\n\n\n\nIndicates test progress percentage complete.Type: Number\n\n
\n\nObject.state\n\n\n\nState of the record.Possible values:\n\n- `Pending`: The requested test activity has been created and is 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- `Browsers requested`: A request has been sent to the cloud infrastructure to start browsers for test generation or test running.\n- `Running`: Cloud infrastructure browsers find and execute pending tests.\n- `Completed`: The test task is complete.\n- `Failed state`: The test task failed.\n\nType: String\n\n
\n\nError\n\n\n\nIf unsuccessful, possible error messages:- No sys\\_id passed in – The JSON object provided doesn’t have a BOQ ID entry. Verify that the JSON object is structured as `{snboqId: \"\"}`.\n- Invalid sys\\_id passed in – The ID provided must be for a BOQ record in the Browser Orchestration Queue \\[sn\\_atf\\_tg\\_sn\\_boq\\] table.\n\n
The following example shows how to start a test run an ATF test, display the progress, and stop the test run. In the global scope, use the sn\\_atf\\_tg namespace.\n\n```\nvar snboqId = CloudRunnerAPI.TestRunnerAPI.startJob({\n\t\"testId\": \"\"\n});\n\ngs.info(JSON.stringify(CloudRunnerAPI.TestRunnerAPI.progress({\"snboqId\": snboqId})));\n\nCloudRunnerAPI.TestRunnerAPI.cancelJob({\"snboqId\": snboqId});\n```\n\nOutput:\n\n```\n{progress: 64, state: running}\n```\n\n## TestRunnerApi – startJob\\(String testId\\)\n\nStarts an ATF test or a test suite on the Cloud Runner browser.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ntestId\n\n\n\nString\n\n\n\nSys\\_id of the ATF test or test suite to be run in the Cloud Runner browser. Located in one of the following tables:\n\n- Test \\[sys\\_atf\\_test\\]\n- Test Suites \\[sys\\_atf\\_test\\_suite\\]\n\n
|Type|Description|\n|----|-----------|\n|String|Returns the sys\\_id of the BOQ record in the Browser Orchestration Queue \\[sn\\_atf\\_tg\\_sn\\_boq\\] table.|\n\nThe following example shows how to start a test run an ATF test, display the progress, and stop the test run. In the global scope, use the sn\\_atf\\_tg namespace.\n\n```\nvar snboqId = CloudRunnerAPI.TestRunnerAPI.startJob({\n\t\"testId\": \"\"\n});\n\ngs.info(JSON.stringify(CloudRunnerAPI.TestRunnerAPI.progress({\"snboqId\": snboqId})));\n\nCloudRunnerAPI.TestRunnerAPI.cancelJob({\"snboqId\": snboqId});\n```\n\nOutput:\n\n```\n{progress: 64, state: running}\n```\n\n## TestRunnerApi – cancelJobByTracker\\(String rootTrackerId\\)\n\nCancels the run job according to the given rootTrackerId instead of snboqId. This method is useful when the caller only has the tracker id and no sn\\_boq record was ever created.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rootTrackerId|String|Sys\\_id of the `sys_execution_tracker` for the run you want to cancel.|\n\n|Type|Description|\n|----|-----------|\n|None|Void. Same cancellation effect as cancelJob\\(\\).|\n\nThe following example cancels the run job for the given rootTrackerID.\n\n```\nsn_atf_tg.CloudRunnerAPI.TestRunnerAPI.cancelJobByTracker({\n rootTrackerId: \"7a6b5c4d3e2f7a6b5c4d3e2f7a6b5c4d\"\n});\n\n// No return value; run is marked completed/cancelled.\n```\n\n## TestRunnerApi – progressFromTracker\\(String rootTrackerId\\)\n\nLooks up the run job according to a given rootTrackerId instead of snboqId.\n\n|Name|Type|Description|\n|----|----|-----------|\n|rootTrackerId|String|Sys\\_id of the `sys_execution_tracker` for the run you want to look up.|\n\n|Type|Description|\n|----|-----------|\n|Object|`{ progress: number, state: string }` — same shape as `progress`.|\n\nThe following example retrieves the run progress for the given rootTrackerID.\n\n```\nvar status = sn_atf_tg.CloudRunnerAPI.TestRunnerAPI.progressFromTracker({\n rootTrackerId: \"7a6b5c4d3e2f7a6b5c4d3e2f7a6b5c4d\"\n});\n```\n\nOutput:\n\n```\n{ progress: 40, state: \"running\" }\n```\n\n## TestRunnerApi – startJob\\(String testId\\)\n\nStarts the run without waiting for the sn\\_boq record.\n\n|Name|Type|Description|\n|----|----|-----------|\n|testId|String|Sys\\_id of the Test \\[sys\\_atf\\_test\\] or Test Suites \\[sys\\_atf\\_test\\_suite\\] table record to run.|\n\n|Type|Description|\n|----|-----------|\n|String|Returns a rootTrackerId, which is the sys\\_id of the `sys_execution_tracker` for the run. Can be passed in the progressFromTracker\\(\\) method.|\n\nThe following example starts a suite run without waiting on the browser job record.\n\n```\nvar rootTrackerId = sn_atf_tg.CloudRunnerAPI.TestRunnerAPI.startJobAsync({\n testId: \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\"\n});\n```\n\nOutput:\n\n```\n\"7a6b5c4d3e2f7a6b5c4d3e2f7a6b5c4d\" (rootTrackerId)\n```\n\n"}}