Cloud Runner TestUserApi – Scoped, Global

  • Release version: Yokohama
  • Updated January 30, 2025
  • 6 minutes to read

    • 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.

    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.

    In global scope, this API is executed within the sn_atf_tg namespace. You must have the ATF Test Generator and Cloud Runner (sn_atf_tg) plugin activated to use this API.

    See also:

    TestUserApi – cancelJob(String snboqId)

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

    Table 1. Parameters
    Name Type Description
    snboqId String Required. The sys_id of the BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.
    Table 2. Returns
    Type Description
    null Null if successful, error message otherwise.
    Error If unsuccessful, possible error messages:
    • No BOQ 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 BOQ sys_id passed in – The ID provided must be for a BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.

    The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

    var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

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

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

    Output:

    {progress: 64, state: running}
User is missing the following criteria: 
	User is locked out
False

    TestUserApi – isValidCloudUser(String username)

    Checks whether a provided user is a valid cloud user.

    Table 3. Parameters
    Name Type Description
    username Object Required. User ID of a valid user listed in the Users [sys_user] table. This value is provided as a string in a JSON object. For example, {username: "abel.tuter"}.
    Table 4. Returns
    Type Description
    Boolean

    Flag that indicates whether the user provided is a valid cloud user.

    Valid values:
    • true: The user provided is a valid cloud user.
    • false: The user provided is invalid for one or more of the following reasons:
      • The user wasn’t found.
      • The user is inactive.
      • The user is locked out.
      • The user needs a password reset.
      • The user doesn’t have an admin role.
      • The user has read-only access.
      • The user has web services only access.

    The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

    var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

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

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

    Output:

    {progress: 64, state: running}
User is missing the following criteria: 
	User is locked out
False

    TestUserApi – progress(String snboqId)

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

    Table 5. Parameters
    Name Type Description
    snboqId String Required. The sys_id of the BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.
    Table 6. Returns
    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 BOQ record.
    Possible values:
    • Pending – The requested test activity has been created and is 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.

    Type: String
    Error If unsuccessful, possible error messages:
    • No BOQ 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 BOQ sys_id passed in – The ID provided must be for a BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.

    The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

    var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

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

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

    Output:

    {progress: 64, state: running}
User is missing the following criteria: 
	User is locked out
False

    TestUserApi – selectCloudUser(String username)

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

    Table 7. Parameters
    Name Type Description
    username Object Required. User ID of a valid user listed in the Users [sys_user] table. This value is provided as a string in a JSON object. For example, {username: "abel.tuter"}.
    Table 8. Returns
    Type Description
    Null Null if successful. Error message otherwise.
    Unable to set cloud user as cloud user not valid – This error indicates that the user provided is invalid for one or more of the following reasons:
    • The user wasn’t found.
    • The user is inactive.
    • The user is locked out.
    • The user needs a password reset.
    • The user doesn’t have an admin role.
    • The user has read-only access.
    • The user has web services only access.

    The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

    var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

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

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

    Output:

    {progress: 64, state: running}
User is missing the following criteria: 
	User is locked out
False

    TestUserApi – startJob(String username)

    Starts an end to end test user job on cloud runner.

    Table 9. Parameters
    Name Type Description
    username String Required. User name of sys_user to test the end to end infrastructure of cloud runner.
    Table 10. Returns
    Type Description
    String The sys_id of the BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.

    The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

    var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

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

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

    Output:

    {progress: 64, state: running}
User is missing the following criteria: 
	User is locked out
False