---
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 Test Generation REST API

# Cloud Runner Test Generation REST API {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 minutes to read

Manages test job generation to be executed in a cloud runner for Automated Test Framework (ATF).
The Cloud Runner Test Generation API requires 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. 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.  
You can use this API for the following tasks:

* Start the test generation job.
* Check the progress of the test generation job.
* Cancel the test generation job.
{#cloudrunner-testgeneration-api__cloudrnr-TestGenerationAPI-scoped_ul_vwb_wvn_31c}

The Cloud Runner Test Generation API may be used in tandem with the [Cloud Runner Test Runner REST API](https://servicenow-prod.fluidtopics.net/0NNkQL458LbArup1UztlGw#cloudrunner-testrunner-api "Manages tests to be executed in a cloud runner for Automated Test Framework (ATF).") and [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)."). For instance, you can call the Test
Generation API to run a test and then get the progress of the test in the browser orchestration
queue (Cloud Runner TEST Generation API) and then check the number of tests that passed or
failed.

To view the Server API reference documentation of this API, see [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 Test Generation - GET /now/sn_atf_tg/test_generation_progress {#ariaid-title2}

Provides the status of each generated test for a provided Browser Orchestration Queue (BOQ) record.

### URL format {#cr-TestGenAPI-GET-test-gen-progress__section_mdy_gwz_31c}

Default URL: GET /api/now/sn_atf_tg/test_generation_progress

### Supported request parameters {#cr-TestGenAPI-GET-test-gen-progress__section_ndy_gwz_31c}

{#cr-TestGenAPI-GET-test-gen-progress__table_ody_gwz_31c__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 1. Path parameters]

{#cr-TestGenAPI-GET-test-gen-progress__table_ody_gwz_31c} {#cr-TestGenAPI-GET-test-gen-progress__table_pdy_gwz_31c__entry__2}

| Name | Description |
|-|-|
| snboqId | Required. The BOQ record sys_id of the test generation job to get the progress of. Located in the BOQ \[sn_atf_tg_sn_boq\] table. Data type: String |
[Table 2. Query parameters]

{#cr-TestGenAPI-GET-test-gen-progress__table_pdy_gwz_31c} {#cr-TestGenAPI-GET-test-gen-progress__table_qdy_gwz_31c__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 3. Request body parameters (XML or JSON)]

{#cr-TestGenAPI-GET-test-gen-progress__table_qdy_gwz_31c}

### Headers {#cr-TestGenAPI-GET-test-gen-progress__section_rdy_gwz_31c}

The 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://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestGenAPI-GET-test-gen-progress__table_sdy_gwz_31c__entry__2}{#cr-TestGenAPI-GET-test-gen-progress__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 4. Request headers]

{#cr-TestGenAPI-GET-test-gen-progress__table_sdy_gwz_31c} {#cr-TestGenAPI-GET-test-gen-progress__table_tdy_gwz_31c__entry__2}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

{#cr-TestGenAPI-GET-test-gen-progress__table_tdy_gwz_31c}

### Status codes {#cr-TestGenAPI-GET-test-gen-progress__section_udy_gwz_31c}

The 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://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestGenAPI-GET-test-gen-progress__table_vdy_gwz_31c__entry__2}

| Status code | Description |
|-|-|
| 200 | Successfully retrieved the progress of the BOQ job. |
| 400 | Error 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. * Unable to find BOQ record -- Invalid Sys ID. Verify that the sys_id of the BOQ record is valid and the record exists. {#cr-TestGenAPI-GET-test-gen-progress__ul_d5p_btk_p1c} |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 6. Status codes]

{#cr-TestGenAPI-GET-test-gen-progress__table_vdy_gwz_31c}

### Response body parameters (JSON or XML) {#cr-TestGenAPI-GET-test-gen-progress__section_wdy_gwz_31c}

{#cr-TestGenAPI-GET-test-gen-progress__table_xdy_gwz_31c__entry__2}

| Name | Description |
|-|-|
| result | Object containing the progress results of the generated test job or a message explaining why the request failed. Data type: Object "result": { "testsSucceeded": Number, "testsFailed": Number, "testsPending": Number, "testsInProgress": Number, "testsSkipped": Number } } Or: { "result": { "message": "String" } } |
| result.message | Error message detailing why the test generation progress cannot be retrieved. The message parameter is not returned in a successful response. Data type: String |
| result.testsSucceeded | Number of generated tests that passed. Data type: Number |
| result.testsFailed | Number of generated tests that failed. Data type: Number |
| result.testsPending | Number of use cases that are waiting for generated tests. Data type: Number |
| result.testsInProgress | Number of use cases that tests are created for. Data type: Number |
| result.testsSkipped | Number of tests skipped due to the job cancellation. Data type: Number |
[ ]

{#cr-TestGenAPI-GET-test-gen-progress__table_xdy_gwz_31c}  

### cURL request {#cr-TestGenAPI-GET-test-gen-progress__example_ydy_gwz_31c}

The following GET call returns progress information about generated tests associated with
the snboqId 1234.

    curl "https://instance.service-now.com/api/now/sn_atf_tg/test_generation_progress?snboqId=1234" \ 
    --request GET \ 
    --header "Accept:application/json" \ 
    --user "username":"password"

Output:

    { 
      "result": { 
        "testsSucceeded": 0, 
        "testsFailed": 0, 
        "testsPending": 0, 
        "testsInProgress": 0, 
        "testsSkipped": 161 
      } 
    }

The following example returns a 400 error message when no BOQ ID is passed.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation_progress" \
    --request GET \
    --header "Accept:application/json" \
    --user "username":"password"

Response:

    {
      "result": {
        "message": "No SNBOQ ID passed in, add snboqId to request body"
      }
    }

The following example returns a 400 error message when an invalid BOQ ID is passed.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation_progress?snboqId=invalid_sys_id" \
    --request GET \
    --header "Accept:application/json" \
    --user "username":"password"

Response:

    {
      "result": {
        "message": "Invalid SNBOQ sys_id passed in"
      }
    }

## Cloud Runner Test Generation - POST /now/sn_atf_tg/cancel_test_generation {#ariaid-title3}

Sets the test generation job and its associated update set record to complete status. Cancels the root trackers of any generated tests that are running. If any test jobs are in progress on cancellation, this method sets any of the in-progress test records generated to skipped.
Tests can fail or cancel automatically due to business rules or access control rule (ACL)
issues. View the generated test table for more details about failed or canceled tests.

### URL format

Default URL: POST /api/now/sn_atf_tg/cancel_test_generation

### Supported request parameters

{#cr-TestGenAPI-POST-cancel-test-gen__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 7. Path parameters]

{#cr-TestGenAPI-POST-cancel-test-gen__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 8. Query parameters]

{#cr-TestGenAPI-POST-cancel-test-gen__table_o1y_cwz_31c__entry__2}

| Name | Description |
|-|-|
| snboqId | Required. sys_id of the Browser Orchestration Queue (BOQ) record to cancel. Located in the the BOQ \[sn_atf_tg_sn_boq\] table. Data type: String |
[Table 9. Request body parameters (XML or JSON)]

{#cr-TestGenAPI-POST-cancel-test-gen__table_o1y_cwz_31c}

### Headers

The 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://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestGenAPI-POST-cancel-test-gen__entry__14}{#cr-TestGenAPI-POST-cancel-test-gen__accept-RESTAPI}{#cr-TestGenAPI-POST-cancel-test-gen__content_type-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| Content-Type | Data format of the request body. Supported types: application/json or application/xml. Default: application/json |
[Table 10. Request headers]

{#cr-TestGenAPI-POST-cancel-test-gen__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 11. Response headers]

### Status codes

The 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://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestGenAPI-POST-cancel-test-gen__entry__24}

| Status code | Description |
|-|-|
| 200 | Successfully canceled the BOQ job. |
| 400 | Error 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. * Unable to find BOQ record -- Invalid Sys ID. Verify that the sys_id of the BOQ record is valid and the record exists. {#cr-TestGenAPI-POST-cancel-test-gen__ul_fzp_ztk_p1c} |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 12. Status codes]

### Response body parameters (JSON or XML)

{#cr-TestGenAPI-POST-cancel-test-gen__entry__32}

| Name | Description |
|-|-|
| result | Object containing the results of the cancellation request. Data type: Object "result": { "message": String } |
| result.message | Message detailing whether the test cancellation was successful. Data type: String |
[ ]

### cURL request

The following request cancels the test generation job of a specified BOQ record.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/cancel_test_generation" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data "{\"snboqId\":\"<sys_id of BOQ record>\"}" \ 
    --user "username":"password"

The response body returns a success message of the cancellation.

    { 
      "result": { 
        "message": "success" 
      } 
    }

The following example returns a 400 error message when no BOQ ID is passed.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/cancel_test_generation" \
    --request POST \
    --header "Accept:application/json" \
    --user "username":"password"

Response:

    {
      "result": {
        "message": "No SNBOQ ID passed in, add snboqId to request body"
      }
    }

The following example returns a 400 error message when an invalid BOQ ID is passed.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/cancel_test_generation" \
    --request POST \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data "{\"snboqId\":\"invalid_sys_id\"}" \
    --user "username":"password"

Response:

    {
      "result": {
        "message": "No SNBOQ ID passed in, add snboqId to request body"
      }
    }

## Cloud Runner Test Generation - POST /now/sn_atf_tg/test_generation {#ariaid-title4}

Inserts a record into the Browser Orchestration Queue (BOQ) \[sn_atf_tg_sn_boq\] table to start a test job.

### URL format {#cr-TestGenAPI-POST-test-generation__section_k1y_cwz_31c}

Default URL: POST /api/now/sn_atf_tg/test_generation

### Supported request parameters {#cr-TestGenAPI-POST-test-generation__section_l1y_cwz_31c}

{#cr-TestGenAPI-POST-test-generation__table_m1y_cwz_31c__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 13. Path parameters]

{#cr-TestGenAPI-POST-test-generation__table_m1y_cwz_31c} {#cr-TestGenAPI-POST-test-generation__table_n1y_cwz_31c__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 14. Query parameters]

{#cr-TestGenAPI-POST-test-generation__table_n1y_cwz_31c} {#cr-TestGenAPI-POST-test-generation__table_o1y_cwz_31c__entry__2}

| Name | Description |
|-|-|
| catalogEncodedQuery | Encoded query specifying which catalog items to generate tests on. An empty string defaults to all catalog items. For more information about forming encoded queries, see [Encoded query strings](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). Data type: String |
| email | Email address to alert when test generation is complete. Data type: String |
| maxTestCount | Number of overall tests to generate. Accepted values: Any number between 1 and 9999. Data type: Number Default: 9999 |
| maxTestCountPerItem | Number of tests to generate per catalog item. Accepted values: Any number between 1 and 10. Data type: Number Default: 10 |
| maxTestCountPerTable | Number of tests to generate per table. Accepted values: Any number between 1 and 10. Data type: Number Default: 10 |
| tableEncodedQuery | Encoded query specifying the tables on which to generate tests. An empty string defaults to all tables. For more information about forming encoded queries, see [Encoded query strings](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). Data type: String |
| separateUpdateSetPerScope | Flag that indicates whether to separate generated tests into respective suites, update sets, and scopes, or to place tests into one suite, update set, and scope. Valid values: * true: Tests are placed into their respective suite and update set according to the scope of each table or catalog item. * false: All generated tests are placed in the same suite, update set, and scope. If false, scopeForGeneratingTests is required in the request. {#cr-TestGenAPI-POST-test-generation__ul_l4b_qfj_y1c} Data type: Boolean Default: true |
| scopeForGeneratingTests | Required when separateUpdateSetPerScope is set to false. Sys_id of the scope in which to place all generated tests. Data type: String |
| userEncodedQuery | Encoded query specifying which users to generate tests on. An empty string input defaults to all tables. For more information about forming encoded queries, see [Encoded query strings](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). Data type: String |
[Table 15. Request body parameters (XML or JSON)]

{#cr-TestGenAPI-POST-test-generation__table_o1y_cwz_31c}

### Headers {#cr-TestGenAPI-POST-test-generation__section_vpj_gxz_31c}

The 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://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestGenAPI-POST-test-generation__table_krf_y2j_41c__entry__2}{#cr-TestGenAPI-POST-test-generation__accept-RESTAPI}{#cr-TestGenAPI-POST-test-generation__content_type-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| Content-Type | Data format of the request body. Supported types: application/json or application/xml. Default: application/json |
[Table 16. Request headers]

{#cr-TestGenAPI-POST-test-generation__table_krf_y2j_41c} {#cr-TestGenAPI-POST-test-generation__table_xpj_gxz_31c__entry__2}

| Header | Description |
|-|-|
| None |   |
[Table 17. Response headers]

{#cr-TestGenAPI-POST-test-generation__table_xpj_gxz_31c}

### Status codes {#cr-TestGenAPI-POST-test-generation__section_s1y_cwz_31c}

The 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://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestGenAPI-POST-test-generation__table_t1y_cwz_31c__entry__2}

| Status code | Description |
|-|-|
| 200 | Successfully inserted a test generation BOQ job. Any errors are shown in the BOQ record logs during processing. All inputs default to generate the maximum number of tests for all tables and service catalog items. |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 18. Status codes]

{#cr-TestGenAPI-POST-test-generation__table_t1y_cwz_31c}

### Response body parameters (JSON or XML) {#cr-TestGenAPI-POST-test-generation__section_u1y_cwz_31c}

{#cr-TestGenAPI-POST-test-generation__table_v1y_cwz_31c__entry__2}

| Name | Description |
|-|-|
| result | Object containing the results of the request. "result": { "snboqId": String } Data type: Object |
| result.snboqId | Sys_id of the record inserted in the sn_atf_tg_sn_boq table when the test generation starts. Data type: String |
[ ]

{#cr-TestGenAPI-POST-test-generation__table_v1y_cwz_31c}  

### cURL request {#cr-TestGenAPI-POST-test-generation__example_w1y_cwz_31c}

The following request example starts a new test job in the instance without any request
parameters and inserts the job in the BOQ table.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --user "username":"password"

Response body:

    { 
      "result": { 
        "snboqId": <sys_id of newly inserted BOQ record> 
      } 
    }

The following request example starts a new test job with a maximum test count of 2 and
filters the tests to the Incident table, and then inserts the job in the BOQ table.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_generation" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data "{\"maxTestCount\":\"2\",\"tableEncodedQuery\":\"name=incident\"}" \ 
    --user "username":"password"

{#cr-TestGenAPI-POST-test-generation__codeblock_grj_5ph_41c}

Response body:

    { 
      "result": { 
        "snboqId": <sys_id of newly inserted BOQ record> 
      } 
    }

{#cr-TestGenAPI-POST-test-generation__codeblock_pkx_5ph_41c}