---
sourceDocument: Australia API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/api-reference

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Cloud Runner TestRunnerApi -- Scoped, Global

# Cloud Runner TestRunnerApi -- Scoped, Global {#ariaid-title1}

Release version: Australia  
Updated March 12, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 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=australia&pubname=australia-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/9F_1A2QGU7GKevV~BJr30Q#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/KbUlmQq1tnnk77Jw_xdt4g#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/9oscoiavfdlFEcozWQrVRw#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 any generated tests that are running.
{#cr-TestRunnerAPI-cancelJob_S__table_epx_lv4_g1c__entry__3}

| Name | Type | Description |
|-|-|-|
| snboqId | String | Sys_id of the Browser Orchestration Queue (BOQ) \[sn_atf_tg_sn_boq\] record associated with the test runner job to cancel. |
[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 cancel a test job using snboqId:

    var testRunnerApi = new sn_atf_tg.TestRunnerApi();

    // Cancel job using snboqId
    var cancelResult = testRunnerApi.cancelJob('f6e5d4c3b2a1908070605040302010ab', null);

    if (cancelResult.status === 'success') {
      gs.info('Test job cancelled successfully');
    } else {
      gs.error('Failed to cancel test job: ' + cancelResult.message);
    }

Output:

    Test job cancelled successfully

## 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}

| Name | Type | Description |
|-|-|-|
| snboqId | String | Sys_id of the Browser Orchestration Queue (BOQ) \[sn_atf_tg_sn_boq\] record associated with the test runner job to retrieve. |
[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 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 sys_id passed in -- The JSON object provided doesn't have a BOQ ID entry. Verify that the JSON object is structured as `{snboqId: "<sys_id>"}`. * 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. {#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": "<sys_id>"
    });

    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 | 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 | Returns 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": "<sys_id>"
    });

    gs.info(JSON.stringify(CloudRunnerAPI.TestRunnerAPI.progress({"snboqId": snboqId})));

    CloudRunnerAPI.TestRunnerAPI.cancelJob({"snboqId": snboqId});

Output:

    {progress: 64, state: running}

## TestRunnerApi -- cancelJobByTracker(String rootTrackerId) {#ariaid-title5}

Cancels 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.
{#cr-TestRunnerAPI-cancelJobByTracker__table_fl4_zlb_zjc__entry__3}

| Name | Type | Description |
|-|-|-|
| rootTrackerId | String | Sys_id of the `sys_execution_tracker` for the run you want to cancel. |
[Table 7. Parameters]

{#cr-TestRunnerAPI-cancelJobByTracker__table_fl4_zlb_zjc} {#cr-TestRunnerAPI-cancelJobByTracker__table_gl4_zlb_zjc__entry__2}

| Type | Description |
|-|-|
| None | Void. Same cancellation effect as cancelJob(). |
[Table 8. Returns]

{#cr-TestRunnerAPI-cancelJobByTracker__table_gl4_zlb_zjc}  
The following example cancels the run job for the given rootTrackerID.

    sn_atf_tg.CloudRunnerAPI.TestRunnerAPI.cancelJobByTracker({
        rootTrackerId: "7a6b5c4d3e2f7a6b5c4d3e2f7a6b5c4d"
    });

    // No return value; run is marked completed/cancelled.

## TestRunnerApi -- progressFromTracker(String rootTrackerId) {#ariaid-title6}

Looks up the run job according to a given rootTrackerId instead of snboqId.
{#cr-TestRunnerAPI-progressFromTracker__table_u4w_vmb_zjc__entry__3}

| Name | Type | Description |
|-|-|-|
| rootTrackerId | String | Sys_id of the `sys_execution_tracker` for the run you want to look up. |
[Table 9. Parameters]

{#cr-TestRunnerAPI-progressFromTracker__table_u4w_vmb_zjc} {#cr-TestRunnerAPI-progressFromTracker__table_v4w_vmb_zjc__entry__2}

| Type | Description |
|-|-|
| Object | `{ progress: number, state: string }` --- same shape as `progress`. |
[Table 10. Returns]

{#cr-TestRunnerAPI-progressFromTracker__table_v4w_vmb_zjc}  
The following example retrieves the run progress for the given rootTrackerID.

    var status = sn_atf_tg.CloudRunnerAPI.TestRunnerAPI.progressFromTracker({
        rootTrackerId: "7a6b5c4d3e2f7a6b5c4d3e2f7a6b5c4d"
    });

Output:

    { progress: 40, state: "running" }

## TestRunnerApi -- startJob(String testId) {#ariaid-title7}

Starts the run without waiting for the sn_boq record.
{#cr-TestRunnerAPI-startJobAsync__table_ywl_xkb_zjc__entry__3}

| Name | Type | Description |
|-|-|-|
| testId | String | Sys_id of the Test \[sys_atf_test\] or Test Suites \[sys_atf_test_suite\] table record to run. |
[Table 11. Parameters]

{#cr-TestRunnerAPI-startJobAsync__table_ywl_xkb_zjc} {#cr-TestRunnerAPI-startJobAsync__table_zwl_xkb_zjc__entry__2}

| Type | Description |
|-|-|
| String | Returns a rootTrackerId, which is the sys_id of the `sys_execution_tracker` for the run. Can be passed in the progressFromTracker() method. |
[Table 12. Returns]

{#cr-TestRunnerAPI-startJobAsync__table_zwl_xkb_zjc}  
The following example starts a suite run without waiting on the browser job record.

    var rootTrackerId = sn_atf_tg.CloudRunnerAPI.TestRunnerAPI.startJobAsync({
        testId: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
    });

Output:

    "7a6b5c4d3e2f7a6b5c4d3e2f7a6b5c4d"  (rootTrackerId)