---
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 User REST API

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

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

Manages test user jobs to be executed in a cloud runner for Automated Test Framework (ATF).
The Cloud Runner Test User 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 user test job.
* Set the cloud user.
* Check if the user specified is valid.
* Check the progress of the user test job.
* Cancel the test job.
{#cloudrunner-testuser-api__cloudrnr-TestUserAPI-scoped_ul_vwb_wvn_31c}

The Cloud Runner Test Runner API may be used in tandem with the [Cloud Runner Test Generation REST API](https://servicenow-prod.fluidtopics.net/5qhFvUFabNBrgM2O~A8heQ#cloudrunner-testgeneration-api "Manages test job generation 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 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.

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

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

### URL format

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

### Supported request parameters

{#cr-TestUserAPI-GET-test-user-progress__entry__2}

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

{#cr-TestUserAPI-GET-test-user-progress__entry__6}

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

{#cr-TestUserAPI-GET-test-user-progress__entry__10}

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

### 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-TestUserAPI-GET-test-user-progress__entry__14}{#cr-TestUserAPI-GET-test-user-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-TestUserAPI-GET-test-user-progress__entry__18}

| Header | Description |
|-|-|
| None |   |
[Table 5. 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-TestUserAPI-GET-test-user-progress__table_u3v_zh3_j1c__entry__2}

| Status code | Description |
|-|-|
| 200 | Successfully retrieved the progress of the test user 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-TestUserAPI-GET-test-user-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-TestUserAPI-GET-test-user-progress__table_u3v_zh3_j1c}

### Response body parameters (JSON or XML)

{#cr-TestUserAPI-GET-test-user-progress__entry__30}

| Name | Description |
|-|-|
| result | Object containing the progress results of the test runner job or a message explaining why the request failed. "result": { "progress": 100, "state": "completed" } {#cr-TestUserAPI-GET-test-user-progress__codeblock_tqb_gth_41c} Or: "result": { "message": "String" } Data type: Object |
| result.message | Error message detailing why the test runner progress cannot be retrieved. The message parameter is not returned in a successful response. Data type: String |
| result.progress | A percentage indicating how close to completion a test is while in a running state. Data type: Number |
| result.state | The current status of the BOQ record. Possible values: * Pending -- The requested test activity has been created and waiting to be executed. * 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. * Running -- Cloud infrastructure browsers find and execute pending tests. * Completed -- The test task is complete. * Failed state -- The test task failed. {#cr-TestUserAPI-GET-test-user-progress__ul_hph_y5h_41c} Data type: String |
[ ]

### cURL request

The following request example shows how to check the progress of a test user job.

    curl "https://instance.service-now.com/api/now/sn_atf_tg/test_user_progress?snboqId=<sys_id of SNBOQ record>" \ 
    --request GET \ 
    --header "Accept:application/json" \ 
    --user "username:password"

Response body:

    { 
      "result": { 
        "progress": 100, 
        "state": "completed" 
      } 
    }

## Cloud Runner Test User - GET /now/sn_atf_tg/is_valid_cloud_user {#ariaid-title3}

Checks whether a provided user is a valid cloud user.
This method checks if the user passes the following criteria:

* Exists,
* Is active,
* Is not locked out,
* Needs a password reset,
* Is an admin,
* Is read-only,
* Is web services-only

### URL format

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

### Supported request parameters

{#cr-TestUserAPI-GET-is_valid_cloud_user__entry__2}

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

{#cr-TestUserAPI-GET-is_valid_cloud_user__entry__6}

| Name | Description |
|-|-|
| username | Required. User name of the sys_user to check if the user passes the following baseline criteria. * Exists, * Is active, * Is not locked out, * Needs a password reset, * Is an admin, * Is read-only, * Is web services-only {#cr-TestUserAPI-GET-is_valid_cloud_user__ul_orh_qnl_p1c} If any of these conditions fail, the API returns a false boolean with a message about which criteria failed. Data type: String |
[Table 8. Query parameters]

{#cr-TestUserAPI-GET-is_valid_cloud_user__entry__10}

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

### 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-TestUserAPI-GET-is_valid_cloud_user__entry__14}{#cr-TestUserAPI-GET-is_valid_cloud_user__accept-RESTAPI}

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

{#cr-TestUserAPI-GET-is_valid_cloud_user__entry__18}

| 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-TestUserAPI-GET-is_valid_cloud_user__table_u3v_zh3_j1c__entry__2}

| Status code | Description |
|-|-|
| 200 | Returns true or false if the user is valid and satisfies cloud user criteria. |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 12. Status codes]

{#cr-TestUserAPI-GET-is_valid_cloud_user__table_u3v_zh3_j1c}

### Response body parameters (JSON or XML)

{#cr-TestUserAPI-GET-is_valid_cloud_user__entry__28}

| Name | Description |
|-|-|
| result | Object containing the results of the request. "result": { "validUser": Boolean } {#cr-TestUserAPI-GET-is_valid_cloud_user__codeblock_hhp_4k2_p1c} Data type: Object |
| result.validUser | Flag that indicates whether the user satisfies cloud user criteria. When true, the user satisfies the criteria. Data type: Boolean |
[ ]

### cURL request

The following request checks if the provided sys_user meets the criteria to use cloud
functionality.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/is_valid_cloud_user?username=<username of sys_user to check>" \ 
    --request GET \ 
    --header "Accept:application/json" \ 
    --user "username:password"

Response body:

    { 
      "result": { 
        "validUser": <Boolean value indicating whether user is valid cloud user> 
      } 
    }

## Cloud Runner Test User - POST /now/sn_atf_tg/test_user {#ariaid-title4}

Inserts a test user job into the BOQ \[sn_atf_tg_sn_boq\] table for a given user name, which is then run on cloud runner.

### URL format

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

### Supported request parameters

{#cr-TestUserAPI-POST-test-user__entry__2}

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

{#cr-TestUserAPI-POST-test-user__entry__6}

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

{#cr-TestUserAPI-POST-test-user__entry__10}

| Name | Description |
|-|-|
| username | Required. Username of the sys_user to test the end-to-end infrastructure of the cloud runner. Data type: String |
[Table 15. Request body parameters (XML or JSON)]

### 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-TestUserAPI-POST-test-user__table_xh4_cfj_41c__entry__2}{#cr-TestUserAPI-POST-test-user__accept-RESTAPI}{#cr-TestUserAPI-POST-test-user__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-TestUserAPI-POST-test-user__table_xh4_cfj_41c} {#cr-TestUserAPI-POST-test-user__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 17. 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-TestUserAPI-POST-test-user__entry__24}

| Status code | Description |
|-|-|
| 200 | Successfully inserted a test user BOQ job. |
| 400 | Error starting test user job. If an empty user name is provided or a user can't be found in sys_user table, the server throws an error. |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 18. Status codes]

### Response body parameters (JSON or XML)

{#cr-TestUserAPI-POST-test-user__entry__32}

| Name | Description |
|-|-|
| result | Object containing the results of the request. "result": { "snboqId": String } Or: "result": { "message": "String" } Data type: Object |
| result.message | Error message detailing why the username cannot be assigned test capabilities. The message parameter is not returned in a successful response. Data type: String |
| result.snboqId | Sys_id of the BOQ record that is inserted when test user job starts successfully. Located in the BOQ \[sn_atf_tg_sn_boq\] table. Data type: String |
[ ]

### cURL request

The following request example shows how to insert a test user job into the BOQ
\[sn_atf_tg_sn_boq\] table for a given username.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_user" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data "{\"username\":\"<username of sys_user to test cloud infrastructure>\"}" \ 
    --user "username:password"

The response returns a sys_id of the BOQ record that is inserted when test user job
starts.

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

The following example returns a 400 error message when no user name or an invalid user name is passed.

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

Response:

    {
      "result": {
        "message": "Unable to set cloud user as cloud user not valid"
      }
    }

## Cloud Runner Test User - POST /now/sn_atf_tg/cancel_test_user {#ariaid-title5}

Sets the test user job status in the Browser Orchestration Queue (BOQ) \[sn_atf_tg_sn_boq\] table to complete.

### URL format

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

### Supported request parameters

{#cr-TestUserAPI-POST-cancel-test-user__entry__2}

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

{#cr-TestUserAPI-POST-cancel-test-user__entry__6}

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

{#cr-TestUserAPI-POST-cancel-test-user__entry__10}

| Name | Description |
|-|-|
| snboqId | Required. Sys_id of the BOQ record to cancel associated with the test user job. Located in the SNBOQ \[sn_atf_tg_sn_boq\] table. Data Type: String |
[Table 21. Request body parameters (XML or JSON)]

### 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-TestUserAPI-POST-cancel-test-user__table_m4k_dfj_41c__entry__2}{#cr-TestUserAPI-POST-cancel-test-user__accept-RESTAPI}{#cr-TestUserAPI-POST-cancel-test-user__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 22. Request headers]

{#cr-TestUserAPI-POST-cancel-test-user__table_m4k_dfj_41c} {#cr-TestUserAPI-POST-cancel-test-user__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 23. 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-TestUserAPI-POST-cancel-test-user__table_u3v_zh3_j1c__entry__2}

| 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-TestUserAPI-POST-cancel-test-user__ul_fzp_ztk_p1c} |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 24. Status codes]

{#cr-TestUserAPI-POST-cancel-test-user__table_u3v_zh3_j1c}

### Response body parameters (JSON or XML)

{#cr-TestUserAPI-POST-cancel-test-user__entry__32}

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

### cURL request

The following request demonstrates how to cancel a test user job in the Browser
Orchestration Queue \[sn_atf_tg_sn_boq\] table.

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

Successful response body:

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

## Cloud Runner Test User - POST /now/sn_atf_tg/select_cloud_user {#ariaid-title6}

Starts an end-to-end test user job on cloud runner. If the user is able to log in with the admin role, the cloud user property defaults to this user for future test runs and test generations.

### URL format

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

### Supported request parameters

{#cr-TestUserAPI-POST-select-cloud-user__entry__2}

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

{#cr-TestUserAPI-POST-select-cloud-user__entry__6}

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

{#cr-TestUserAPI-POST-select-cloud-user__entry__10}

| Name | Description |
|-|-|
| username | Required. User name of the sys_user to test and set the cloud user for future test runner and test generation jobs. Data type: String |
[Table 27. Request body parameters (XML or JSON)]

### 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-TestUserAPI-POST-select-cloud-user__table_g43_2fj_41c__entry__2}{#cr-TestUserAPI-POST-select-cloud-user__accept-RESTAPI}{#cr-TestUserAPI-POST-select-cloud-user__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 28. Request headers]

{#cr-TestUserAPI-POST-select-cloud-user__table_g43_2fj_41c} {#cr-TestUserAPI-POST-select-cloud-user__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 29. 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-TestUserAPI-POST-select-cloud-user__table_u3v_zh3_j1c__entry__2}

| Status code | Description |
|-|-|
| 200 | Successfully tested the end to end cloud runner infrastructure and set the cloud user for future test run and test generation jobs. |
| 400 | Error testing the full end to end cloud runner infrastructure and setting the cloud user. Ensure that the user name isn't empty or that the user exists in the sys_user table for a given user name. |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 30. Status codes]

{#cr-TestUserAPI-POST-select-cloud-user__table_u3v_zh3_j1c}

### Response body parameters (JSON or XML)

{#cr-TestUserAPI-POST-select-cloud-user__entry__32}

| Name | Description |
|-|-|
| result | Object containing the results of the request. "result": { "message": "String" } {#cr-TestUserAPI-POST-select-cloud-user__codeblock_hhp_4k2_p1c} Data type: Object |
| result.message | Message detailing whether the user was successfully selected for future test runs and test generations on the cloud runner infrastructure. Data type: String |
[ ]

### cURL request

The following example shows how to request a specific user to be selected for future test
runs and test generations on the cloud runner infrastructure.

    curl "https://instance.service-now.com/api/now/sn_atf_tg/select_cloud_user" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data "{\"username\":\"<username of sys_user to set as cloud user>\"}" \ 
    --user "username:password"

The response body returns a success message indicating that the cloud user is successfully
selected for test runs and generations.

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