Cloud Runner Test Runner REST API

Manages tests to be executed in a cloud runner for Automated Test Framework (ATF).

The Cloud Runner Test Runner API requires the ATF Test Generator and Cloud Runner (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 an ATF test or test suite in the Cloud Runner browser.
• Check the progress of the test job.
• Cancel the test job.

The Cloud Runner Test Runner API may be used in tandem with the Cloud Runner Test Generation REST API and Cloud Runner Test User REST API. 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 TestRunnerApi – Scoped, Global.

Parent Topic:REST API reference

Cloud Runner Test Runner - GET /now/sn_atf_tg/test_runner_progress

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

URL format

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

Supported request parameters

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.

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.

Response body parameters (JSON or XML)

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

{
  "result": { 
    "message": "String" 
  } 
}

Retrieve test progress using snboqId

The following request retrieves the test runner job progress of the Browser Orchestration Queue (BOQ) [sn_atf_tg_sn_boq] record.

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

The response indicates that the test is 100% complete.

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

Retrieve test progress using rootTrackerId

The following request retrieves the test runner job progress of the Execution Tracker [sys_execution_tracker] record.

curl "https://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress?rootTrackerId=0a1b2c3d4e5f67890a1b2c3d4e5f6789" \
--request GET \
--header "Accept:application/json" \
--user "username:password"

The response indicates that the test is 45% complete.

{ 
  "result": { 
    "progress": 45, 
    "state": "running" 
    "message": "Test execution in progress.",
  } 
}

Invalid or missing rootTrackerId or snboqId value

The following example demonstrates the response if the request has a missing or invalid rootTrackerId or snboqId value.

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

Response body (400 Bad Request):

{
  "error": {
    "message": "Invalid request. Either snboqId or rootTrackerId must be provided.",
    "status": "failure"
  }
}

Cloud Runner Test Runner - POST /now/sn_atf_tg/cancel_test_runner

Sets the test runner job to complete status and cancels any generated tests that are running.

URL format

Default URL: GET /now/sn_atf_tg/cancel_test_runner

Supported request parameters

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.

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.

Response body parameters (JSON or XML)

  "result": { 
    "message": String
  }

Cancel the test runner job using snboqId

The following example shows how to cancel a test runner request using the sys_id of the BOQ [sn_atf_tg_sn_boq] record.

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

The response message indicating that the test runner is successfully canceled.

{
  "result": {
    "status": "success",
    "message": "Test run cancelled successfully."
  }
}

Cancel the test runner job using rootTrackerId

The following example shows how to cancel a test runner request according to the sys_id of the Execution Tracker [sys_execution_tracker] record.

curl "https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_runner" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username:password" \
--data '{
  "rootTrackerId": "0a1b2c3d4e5f67890a1b2c3d4e5f6789"
}'

Successful response body (200):

{
  "result": {
    "status": "success",
    "message": "Test run cancelled successfully."
  }
}

Error when neither rootTrackerId or snboqId is passed

The following example shows the response message that's returned when neither rootTrackerId or snboqId are provided in the request.

curl "https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_runner" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username:password" \
--data '{}'

Response body (400 Bad Request):

{
  "error": {
    "message": "Invalid request. Either snboqId or rootTrackerId must be provided.",
    "status": "failure"
  }
}

Cloud Runner Test Runner - POST /now/sn_atf_tg/test_runner

Inserts a test runner job into the Browser Orchestration Queue (BOQ) table record for given test or test suite, which is then run on the cloud runner. Optionally choose to wait to insert the record before processing a response.

URL format

Default URL: POST api/now/sn_atf_tg/test_runner

Supported request parameters

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.

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.

Response body parameters (JSON or XML)

{ 
  "result": { 
    "snboqId": "String" 
  } 
}

  "result": { 
    "message": "String"
  }

cURL request

The following request inserts a test runner job into the BOQ [sn_atf_tg_sn_boq] table.

curl "https://instance.service-now.com/api/now/sn_atf_tg/test_runner" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\"testId\":\"<sys_id of ATF test or test suite>\"}" \ 
--user "username:password"

The response body returns the sys_id of the test runner job that was successfully inserted.

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

Synchronous request (sync=true)

curl "https://instance.service-now.com/api/now/sn_atf_tg/test_runner" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username:password" \
--data '{
  "testId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "browser": "Chrome",
  "sync": true
}'

Successful response (200):

{
  "result": {
    "snboqId": "f6e5d4c3b2a1908070605040302010ab",
    "status": "success",
    "message": "Test run started successfully."
  }
}

Asynchronous request (sync=false)

curl "https://instance.service-now.com/api/now/sn_atf_tg/test_runner" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username:password" \
--data '{
  "testId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "browser": "Chrome",
  "sync": false
}'

Successful response (200):

{
  "result": {
    "rootTrackerId": "0a1b2c3d4e5f67890a1b2c3d4e5f6789",
    "status": "success",
    "message": "Test run started successfully."
  }
}

Synchronous request where the SNBOQ record doesn't insert in time.

curl "https://instance.service-now.com/api/now/sn_atf_tg/test_runner" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username:password" \
--data '{
  "testId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "browser": "Chrome"
}'

Response (202 Accepted):

{
  "result": {
    "rootTrackerId": "0a1b2c3d4e5f67890a1b2c3d4e5f6789",
    "status": "accepted",
    "message": "The test run has been initiated but the Browser Orchestration Queue record was not inserted in time. The test will most likely continue to run."
  }
}