--- sourceDocument: Xanadu API Reference sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference Release : - xanadu ft:locale : - en-US ft:publication_title : - Xanadu API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # Cloud Runner TestRunnerApi -- Scoped, Global # Cloud Runner TestRunnerApi -- Scoped, Global {#ariaid-title1} * Release version: Xanadu * * Updated August 1, 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read Manages tests to be executed in a cloud runner for Automated Test Framework (ATF). This API is part of the CloudRunnerApi script include. You can use this API for the following tasks: * Start an ATF test or test suite in the Cloud Runner browser. * Check the progress of the test job. * Cancel the test job. {#cloudrnr-TestRunnerAPI-scoped__cloudrnr-TestRunnerAPI-scoped_ul_vwb_wvn_31c} In global scope, this API is executed within the sn_atf_tg namespace. You must have the [ATF Test Generator and Cloud Runner](https://www.servicenow.com/docs/access?context=atf-tg-cr-intro&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US) (sn_atf_tg) plugin activated to use this API. See also: * [Cloud Runner TestGenerationApi -- Scoped, Global](https://servicenow-prod.fluidtopics.net/_kJqWdel698sLjVYlxB5XA#cloudrnr-TestGenerationAPI-scoped "Manages test job generation to be executed in a cloud runner for Automated Test Framework (ATF). This API is part of the CloudRunnerApi script include.") * [Cloud Runner TestUserApi -- Scoped, Global](https://servicenow-prod.fluidtopics.net/XWkYqfAwSwvx_nHpgepjdA#cloudrnr-TestUserAPI-scoped "Manages test user jobs to be executed in a cloud runner for Automated Test Framework (ATF). This API is part of the CloudRunnerApi script include.") * [Cloud Runner Test User REST API](https://servicenow-prod.fluidtopics.net/R91Ur5YEmltpH6bfwu0NhQ#cloudrunner-testuser-api "Manages test user jobs to be executed in a cloud runner for Automated Test Framework (ATF).") {#cloudrnr-TestRunnerAPI-scoped__ul_gd4_zsn_31c} ## TestRunnerApi -- cancelJob(String snboqId) {#ariaid-title2} Sets the test runner job to complete status and cancels the root trackers of any generated tests that are running. {#cr-TestRunnerAPI-cancelJob_S__table_epx_lv4_g1c__entry__3}{#cr-TestRunnerAPI-cancelJob_S__cr-snboqId-ph-desc} | Name | Type | Description | |-|-|-| | snboqId | String | Required. The sys_id of the BOQ record in the Browser Orchestration Queue \[sn_atf_tg_sn_boq\] table. | [Table 1. Parameters] {#cr-TestRunnerAPI-cancelJob_S__table_epx_lv4_g1c} {#cr-TestRunnerAPI-cancelJob_S__table_fpx_lv4_g1c__entry__2} | Type | Description | |-|-| | null | Null if successful, error message otherwise. | [Table 2. Returns] {#cr-TestRunnerAPI-cancelJob_S__table_fpx_lv4_g1c} 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. var snboqId = CloudRunnerAPI.TestRunnerAPI.startJob({ "testId": "" }); gs.info(JSON.stringify(CloudRunnerAPI.TestRunnerAPI.progress({"snboqId": snboqId}))); CloudRunnerAPI.TestRunnerAPI.cancelJob({"snboqId": snboqId}); Output: {progress: 64, state: running} ## TestRunnerApi -- progress(String snboqId) {#ariaid-title3} Provides the status of each test ran for a provided Browser Orchestration Queue (BOQ) record. {#cr-TestRunnerAPI-progress_S__table_epx_lv4_g1c__entry__3}{#cr-TestRunnerAPI-progress_S__cr-snboqId-ph-desc} | Name | Type | Description | |-|-|-| | snboqId | String | Required. The sys_id of the BOQ record in the Browser Orchestration Queue \[sn_atf_tg_sn_boq\] table. | [Table 3. Parameters] {#cr-TestRunnerAPI-progress_S__table_epx_lv4_g1c} {#cr-TestRunnerAPI-progress_S__table_fpx_lv4_g1c__entry__2}{#cr-TestRunnerAPI-progress_S__cr-prog-state-ph-desc} | Type | Description | |-|-| | Object | JSON object indicating test progress. { "progress": Number, "state": "String" } | | Object.progress | Indicates test progress percentage complete. Type: Number | | Object.state | State of the BOQ record. Possible values: * Pending -- The requested test activity has been created and is waiting to be executed.{#cr-TestRunnerAPI-progress_S__cr-prog-state-li-pending} {#cr-TestRunnerAPI-progress_S__cr-prog-state-li-pending} * 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. * Browsers requested -- A request has been sent to the cloud infrastructure to start browsers for test generation or test running.{#cr-TestRunnerAPI-progress_S__cr-prog-state-li-brsreq} {#cr-TestRunnerAPI-progress_S__cr-prog-state-li-brsreq} * Running -- Cloud infrastructure browsers find and execute pending tests. * Completed -- The test task is complete.{#cr-TestRunnerAPI-progress_S__cr-prog-state-li-complete} {#cr-TestRunnerAPI-progress_S__cr-prog-state-li-complete} * Failed state -- The test task failed.{#cr-TestRunnerAPI-progress_S__cr-prog-state-li-failed} {#cr-TestRunnerAPI-progress_S__cr-prog-state-li-failed} {#cr-TestRunnerAPI-progress_S__ul_rvl_vsg_l1c} Type: String | | Error | If unsuccessful, possible error messages: * No BOQ ID passed in -- The JSON object provided doesn't have a BOQ ID entry. Verify that the JSON object is structured as `{snboqId: ""}`. * Invalid BOQ sys_id passed in -- The ID provided must be for a BOQ record in the Browser Orchestration Queue \[sn_atf_tg_sn_boq\] table. {#cr-TestRunnerAPI-progress_S__ul_wqr_slb_j1c} | [Table 4. Returns] {#cr-TestRunnerAPI-progress_S__table_fpx_lv4_g1c} 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. var snboqId = CloudRunnerAPI.TestRunnerAPI.startJob({ "testId": "" }); gs.info(JSON.stringify(CloudRunnerAPI.TestRunnerAPI.progress({"snboqId": snboqId}))); CloudRunnerAPI.TestRunnerAPI.cancelJob({"snboqId": snboqId}); Output: {progress: 64, state: running} ## TestRunnerApi -- startJob(String testId) {#ariaid-title4} Starts an ATF test or a test suite on the Cloud Runner browser. {#cr-TestRunnerAPI-startJob_S__table_epx_lv4_g1c__entry__3} | Name | Type | Description | |-|-|-| | testId | String | Required. The sys_id of the ATF test or test suite to be run in the Cloud Runner browser. Located in one of the following tables: * Test \[sys_atf_test\] * Test Suites \[sys_atf_test_suite\] {#cr-TestRunnerAPI-startJob_S__ul_gqc_yj4_l1c} | [Table 5. Parameters] {#cr-TestRunnerAPI-startJob_S__table_epx_lv4_g1c} {#cr-TestRunnerAPI-startJob_S__table_fpx_lv4_g1c__entry__2} | Type | Description | |-|-| | String | The sys_id of the BOQ record in the Browser Orchestration Queue \[sn_atf_tg_sn_boq\] table. | [Table 6. Returns] {#cr-TestRunnerAPI-startJob_S__table_fpx_lv4_g1c} 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. var snboqId = CloudRunnerAPI.TestRunnerAPI.startJob({ "testId": "" }); gs.info(JSON.stringify(CloudRunnerAPI.TestRunnerAPI.progress({"snboqId": snboqId}))); CloudRunnerAPI.TestRunnerAPI.cancelJob({"snboqId": snboqId}); Output: {progress: 64, state: running}