{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":492,"path":"api-reference/rest-apis/cloudrunner-testuser-api.md","title":"Cloud Runner Test User REST API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Cloud Runner Test User REST API\n\nManages test user jobs to be executed in a cloud runner for Automated Test Framework \\(ATF\\).\n\nThe Cloud Runner Test User API requires 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. 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.\n\nYou can use this API for the following tasks:\n\n-   Start the user test job.\n-   Set the cloud user.\n-   Check if the user specified is valid.\n-   Check the progress of the user test job.\n-   Cancel the test job.\n\nThe Cloud Runner Test Runner API may be used in tandem with the [Cloud Runner Test Generation REST API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/cloudrunner-testgeneration-api.md) and [Cloud Runner Test User REST API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/cloudrunner-testuser-api.md). 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.\n\nTo view the Server API reference documentation of this API, see [Cloud Runner TestUserApi – Scoped, Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/cloudrnr-TestUserAPI-scoped.md).\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Cloud Runner Test User - GET /now/sn\\_atf\\_tg/test\\_user\\_progress\n\nProvides the status of the test user job for a provided Browser Orchestration Queue \\(BOQ\\) record.\n\n### URL format\n\nDefault URL: GET `/api/now/sn_atf_tg/test_user_progress`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsnboqId\n\n</td><td>\n\nRequired. BOQ record sys\\_id of the test user job to get the progress of.Data Type: String\n\nTable: BOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\]\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_u3v_zh3_j1c\"><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td>\n\nSuccessfully retrieved the progress of the test user job.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError 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.\n-   Unable to find BOQ record – Invalid Sys ID. Verify that the sys\\_id of the BOQ record is valid and the record exists.\n\n</td></tr><tr><td>\n\n403\n\n</td><td>\n\nError granting user access to the endpoint. Ensure that the user has the admin role.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the progress results of the test runner job or a message explaining why the request failed.```\n\"result\": { \n    \"progress\": 100, \n    \"state\": \"completed\" \n  }\n```\n\nOr:\n\n```\n\"result\": { \n    \"message\": \"String\"\n}\n```\n\nData type: Object\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nError message detailing why the test runner progress cannot be retrieved. The message parameter is not returned in a successful response.Data type: String\n\n</td></tr><tr><td>\n\nresult.progress\n\n</td><td>\n\nPercentage that indicates how close to completion a test is while in a running state.Data type: Number\n\n</td></tr><tr><td>\n\nresult.state\n\n</td><td>\n\nCurrent status of the BOQ record.Possible values:\n\n-   Browsers requested: A request has been sent to the cloud infrastructure to start browsers for test generation or test running.\n-   Completed: The test task is complete.\n-   Failed state: The test task failed.\n-   Pending: The requested test activity has been created and 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-   Running: The cloud infrastructure browsers find and execute pending tests.\n\nData type: String\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following request example shows how to check the progress of a test user job.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_user_progress?snboqId=<sys_id of SNBOQ record>\" \\ \n--request GET \\ \n--header \"Accept:application/json\" \\ \n--user \"username:password\"\n```\n\nResponse body:\n\n```\n{ \n  \"result\": { \n    \"progress\": 100, \n    \"state\": \"completed\" \n  } \n}\n```\n\n## Cloud Runner Test User - GET /now/sn\\_atf\\_tg/is\\_valid\\_cloud\\_user\n\nChecks whether a provided user is a valid cloud user.\n\nThis method checks if the user passes the following criteria:\n\n-   Exists,\n-   Is active,\n-   Is not locked out,\n-   Needs a password reset,\n-   Is an admin,\n-   Is read-only,\n-   Is web services-only\n\n### URL format\n\nDefault URL: GET `/api/now/sn_atf_tg/is_valid_cloud_user`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nusername\n\n</td><td>\n\nRequired. User name of the sys\\_user to check if the user passes the following baseline criteria.-   Exists,\n-   Is active,\n-   Is not locked out,\n-   Needs a password reset,\n-   Is an admin,\n-   Is read-only,\n-   Is web services-only\n\nIf any of these conditions fail, the API returns a false boolean with a message about which criteria failed.\n\nData type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Returns true or false if the user is valid and satisfies cloud user criteria.|\n|403|Error granting user access to the endpoint. Ensure that the user has the admin role.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the results of the request.```\n\n  \"result\": { \n    \"validUser\": Boolean \n  }\n```\n\nData type: Object\n\n</td></tr><tr><td>\n\nresult.validUser\n\n</td><td>\n\nFlag that indicates whether the user satisfies cloud user criteria. When true, the user satisfies the criteria.Data type: Boolean\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following request checks if the provided sys\\_user meets the criteria to use cloud functionality.\n\n```\ncurl \"http://instance.service-now.com/api/now/sn_atf_tg/is_valid_cloud_user?username=<username of sys_user to check>\" \\ \n--request GET \\ \n--header \"Accept:application/json\" \\ \n--user \"username:password\"\n```\n\nResponse body:\n\n```\n{ \n  \"result\": { \n    \"validUser\": <Boolean value indicating whether user is valid cloud user> \n  } \n}\n```\n\n## Cloud Runner Test User - POST /now/sn\\_atf\\_tg/test\\_user\n\nInserts 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.\n\n### URL format\n\nDefault URL: POST `/api/now/sn_atf_tg/test_user`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nusername\n\n</td><td>\n\nRequired. Username of the sys\\_user to test the end-to-end infrastructure of the cloud runner.Data type: String\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_xh4_cfj_41c\" class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td>\n\nSuccessfully inserted a test user BOQ job.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError 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.\n\n</td></tr><tr><td>\n\n403\n\n</td><td>\n\nError granting user access to the endpoint. Ensure that the user has the admin role.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the results of the request.```\n\n  \"result\": { \n    \"snboqId\": String\n  }\n```\n\nOr:\n\n```\n\"result\": { \n    \"message\": \"String\"\n}\n```\n\nData type: Object\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nError message detailing why the username cannot be assigned test capabilities. The message parameter is not returned in a successful response.Data type: String\n\n</td></tr><tr><td>\n\nresult.snboqId\n\n</td><td>\n\nSys\\_id of the BOQ record that is inserted when test user job starts successfully.Data type: String\n\nTable: BOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\]\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following request example shows how to insert a test user job into the BOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\] table for a given username.\n\n```\ncurl \"http://instance.service-now.com/api/now/sn_atf_tg/test_user\" \\ \n--request POST \\ \n--header \"Accept:application/json\" \\ \n--header \"Content-Type:application/json\" \\ \n--data \"{\\\"username\\\":\\\"<username of sys_user to test cloud infrastructure>\\\"}\" \\ \n--user \"username:password\"\n```\n\nThe response returns a sys\\_id of the BOQ record that is inserted when test user job starts.\n\n```\n{ \n  \"result\": { \n    \"snboqId\": \"<sys_id of newly inserted BOQ record>\" \n  } \n}\n```\n\nThe following example returns a 400 error message when no user name or an invalid user name is passed.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/test_user\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--user \"username:password\"\n```\n\nResponse:\n\n```\n{\n  \"result\": {\n    \"message\": \"Unable to set cloud user as cloud user not valid\"\n  }\n}\n```\n\n## Cloud Runner Test User - POST /now/sn\\_atf\\_tg/cancel\\_test\\_user\n\nSets the test user job status in the Browser Orchestration Queue \\(BOQ\\) \\[sn\\_atf\\_tg\\_sn\\_boq\\] table to complete.\n\n### URL format\n\nDefault URL: POST `/api/now/sn_atf_tg/cancel_test_user`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsnboqId\n\n</td><td>\n\nRequired. Sys\\_id of the BOQ record to cancel associated with the test user job.Data Type: String\n\nTable: SNBOQ \\[sn\\_atf\\_tg\\_sn\\_boq\\]\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_m4k_dfj_41c\" class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_u3v_zh3_j1c\"><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td>\n\nSuccessfully canceled the BOQ job.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError 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.\n-   Unable to find BOQ record – Invalid Sys ID. Verify that the sys\\_id of the BOQ record is valid and the record exists.\n\n</td></tr><tr><td>\n\n403\n\n</td><td>\n\nError granting user access to the endpoint. Ensure that the user has the admin role.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the results of the request.```\n\n  \"result\": { \n    \"message\": String\n  }\n```\n\nData type: Object\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nMessage detailing whether the test user cancellation was successful.Data type: String\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following request demonstrates how to cancel a test user job in the Browser Orchestration Queue \\[sn\\_atf\\_tg\\_sn\\_boq\\] table.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_user\" \\ \n--request POST \\ \n--header \"Accept:application/json\" \\ \n--header \"Content-Type:application/json\" \\ \n--data \"{\\\"snboqId\\\":\\\"<sys_id of BOQ record>\\\"}\" \\ \n--user \"username:password\"\n```\n\nSuccessful response body:\n\n```\n{ \n  \"result\": { \n    \"message\": \"success\" \n  } \n}\n```\n\n## Cloud Runner Test User - POST /now/sn\\_atf\\_tg/select\\_cloud\\_user\n\nStarts 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.\n\n### URL format\n\nDefault URL: POST `/api/now/sn_atf_tg/select_cloud_user`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nusername\n\n</td><td>\n\nRequired. User name of the sys\\_user to test and set the cloud user for future test runner and test generation jobs.Data type: String\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_g43_2fj_41c\" class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successfully tested the end to end cloud runner infrastructure and set the cloud user for future test run and test generation jobs.|\n|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.|\n|403|Error granting user access to the endpoint. Ensure that the user has the admin role.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nresult\n\n</td><td>\n\nObject containing the results of the request.```\n\n  \"result\": { \n    \"message\": \"String\"\n  }\n```\n\nData type: Object\n\n</td></tr><tr><td>\n\nresult.message\n\n</td><td>\n\nMessage detailing whether the user was successfully selected for future test runs and test generations on the cloud runner infrastructure.Data type: String\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following example shows how to request a specific user to be selected for future test runs and test generations on the cloud runner infrastructure.\n\n```\ncurl \"https://instance.service-now.com/api/now/sn_atf_tg/select_cloud_user\" \\ \n--request POST \\ \n--header \"Accept:application/json\" \\ \n--header \"Content-Type:application/json\" \\ \n--data \"{\\\"username\\\":\\\"<username of sys_user to set as cloud user>\\\"}\" \\ \n--user \"username:password\"\n```\n\nThe response body returns a success message indicating that the cloud user is successfully selected for test runs and generations.\n\n```\n{ \n  \"result\": { \n    \"message\": \"success\" \n  } \n}\n```\n\n"}}