Accessing HCL OneTest™ Server

When your test projects have resources that require access to HCL OneTest™ Server, you can enable access when running the test resources from HCL OneTest™ API, command-line client, Ant CLI, Maven CLI, or in a REST API call. With access to HCL OneTest™ Server you can also retrieve secrets defined in the HCL OneTest™ Server project and use the secrets when running tests.

Prerequisites

Before you can access HCL OneTest™ Server, certain tasks must be completed:
  • You must have installed and configured HCL OneTest™ Server. For more information about HCL OneTest™ Server, see Accessing test assets from a server project.
  • Optionally, if you are retrieving secrets, then you must have set up your project in a team space on HCL OneTest™ Server and created a secrets collection containing secrets in that project.
  • You must have logged in to HCL OneTest™ Server and copied the offline user token generated by using the Offline Token option from the HCL OneTest™ Server Header. See Generating an offline user token. You must have retained the token copy because this offline user token is used to access HCL OneTest™ Server.

Generating an offline user token

  1. Log into HCL OneTest™ Server.
  2. Click the image of the user action icon. icon in the HCL OneTest™ Server Header and click the Offline Tokens option.
  3. Click Create Token.
  4. Click within the token field to copy the offline user token to the clipboard.

    You can paste the copied offline user token in a text document to use the offline user token at a later time.

Note: The offline user token that is generated is specific to the member who generated the token and the token is neither stored on the HCL OneTest™ Server nor is retrievable from the HCL OneTest™ Server at a later time.

Using the offline token

The offline user token enables you to connect to HCL OneTest™ Server from HCL OneTest™ API.

After you enable access to HCL OneTest™ Server, you can perform the following operations:
  • Configure HCL OneTest™ API to publish test reports to HCL OneTest™ Server.
  • Access secrets configured in a project in a team space on HCL OneTest™ Server to be used across different testing environments and during test execution runtime.

You can paste the generated offline user token in the HCL OneTest™ API UI. See Accessing HCL OneTest Server from HCL OneTest API.

Locating the used offline token

The offline user token that you generated and copied from HCL OneTest™ Server and used in the HCL OneTest™ API UI is stored in the .userProfile file. The token is stored under the attribute server.securityToken with the generated offline user token as its value.

The .userProfile file can be found in the .integrationtester subdirectory of the User's home directory. For example, the path to the .userProfile file can be C:\Users\<CurrentUser>\.integrationtester.

Offline user token environment variable

An offline user token can be configured in any of the following ways:
  • In the .userProfile file (by setting the value in the Server Settings tab or Project Preferences option in HCL OneTest™ API as detailed in Accessing HCL OneTest Server from HCL OneTest API.
  • By setting the value of an OS environment variable (HCL_ONETEST_OFFLINE_TOKEN=<generated offline user token>)

When running test resources in the HCL OneTest™ API UI, the offline user token defined in the .userProfile file is used to access HCL OneTest™ Server. If there is no token configured in the .userProfile file, then the token in the HCL_ONETEST_OFFLINE_TOKEN variable is used.

When running test resources in the non-GUI methods, the value of the HCL_ONETEST_OFFLINE_TOKEN variable is used in preference to the token found in the .userProfile file.

Accessing HCL OneTest™ Server from HCL OneTest™ API

You can access HCL OneTest™ Server from HCL OneTest™ API so that you can retrieve the secrets configured for a project in a team space and stored on HCL OneTest™ Server or to publish test reports from HCL OneTest™ API to HCL OneTest™ Server.

Before you begin

Before you use HCL OneTest™ API to access HCL OneTest™ Server, certain tasks must be completed. See Prerequisites.

About this task

After you have generated an offline user token in HCL OneTest™ Server, you must configure HCL OneTest™ API to access HCL OneTest™ Server.

Procedure

  1. Open your project. From the HCL OneTest™ API window, click Browse to browse to the location of your project, select the project, and click OK.
    You can add the copied offline user token in either of the following ways:
    • Adding the offline user token by using the Project Settings option. Go to Step 2.
    • Adding the offline user token by using the Project Preferences option. Go to Step 3.
Adding the offline user token by using the Project Settings option
  1. Open the Server Settings tab from Project > Server Settings. In the Server Settings tab window, complete the following steps:
    1. Click the HCL OneTest Server check box.
    2. Enter the hostname of the server hosting HCL OneTest™ Server in the Secure host field.
      Note: Enter the hostname and not the URL. The default port configured is 443. If you have configured a different port, enter that port number.
    3. Paste the offline user token you copied that you generated by using the Offline Token option in HCL OneTest™ Server.
    4. Click SSL, select an option if different from the one selected and then click OK.
    5. Test the connection to HCL OneTest™ Server by clicking Test.
      Important: You must enter the offline user token before you can test the connection to HCL OneTest™ Server.

      A Connection OK dialog is displayed for a successful connection. An error dialog is displayed for an unsuccessful connection.

    6. Select the project in a team space on HCL OneTest™ Server that you want to access by completing the following steps:
      1. Click Select in the Project panel.
        Note: The projects that you can access that are contained in the different team spaces on HCL OneTest™ Server are displayed implying that the connectivity to HCL OneTest™ Server is enabled with the use of the offline token.
      2. In the Select Project window, click the project in the team space that you want to select from the list.
      3. Click OK.
      4. Click OK to save the HCL OneTest™ Server settings.
Adding the offline user token by using the Project Preferences option
  1. Click Project > Preferences > Server Settings. In the Server Settings window, complete the following steps:
    Note: You can add the offline user token using this option to enable the access to HCL OneTest™ Server in methods that require an offline user token, for example, when running tests from the command-line client.
    1. Click the Show server URL validation failed dialog check box.
    2. Paste the offline user token in the HCL OneTest Server field.
    3. Click Apply and then click OK to apply, save, and exit from the dialog.
    Note: If you added the HCL OneTest™ Server offline user token by using the Project Settings option, the same token is displayed in the Preferences for the Server Settings.

    You can view the offline user token that you added, which gets stored in the .userProfile file located in .integrationtester subdirectory of the home directory. For more information, see Locating the used offline token.

Results

You have configured HCL OneTest™ API to access HCL OneTest™ Server.

What to do next

You can retrieve the secrets created and stored in a secret collection in a project in a team space on HCL OneTest™ Server from HCL OneTest™ API. For instructions, see Retrieving secrets from HCL OneTest Server.

Accessing HCL OneTest™ Server from IntegrationTesterCmd, ANT CLI, Maven CLI, or in a REST API call

When you are running test resources in projects from IntegrationTesterCmd, ANT CLI, Maven CLI, or in a REST API call, and the resources in the project require to access HCL OneTest™ Server you can use an optional parameter or attribute in your command argument.

Before you begin

Before you can access HCL OneTest™ Server, certain tasks must be completed. See Prerequisites.

You must have configured the offline user token environment variable. See Offline user token environment variable.

About this task

When you are running a test from the command line, ANT CLI, or as a REST API call, the following action is taken by the test engine:
  • The value of the HCL_ONETEST_OFFLINE_TOKEN variable is used in preference to the token found in the .userProfile file.
    Note: In a REST API call, the engine uses the token configured on the agent.
  • If you have copied the offline user token generated from HCL OneTest™ Server in the HCL OneTest™ API UI and the copied offline user token resides in the .userProfile file, then the test engine uses the offline token that is available in the .userProfile file. For more information, see Locating the used offline token.

Enabling tests to retrieve the configured secrets

Retrieving secrets during Tests running from command line, ANT CLI, Maven CLI, or as REST API calls provides the parameter or attributes that you may use to retrieve secrets when you are running tests from the command line, ANT CLI, or as REST API calls.

Table 1. Retrieving secrets during Tests running from command line, ANT CLI, Maven CLI, or as REST API calls
To retrieve secrets from HCL OneTest™ Server Parameter or attribute to use

When using the HCL OneTest™ API command line or Maven CLI

Use -secrets as a parameter in your command argument.

When you use the RunTests command with this parameter, the secrets collection name defined by the environment is overridden and the secrets defined in the project secrets collection on HCL OneTest™ Server is retrieved.

For details, see Running tests by using the command line.

When running as an ANT task

Use secrets as an attribute when you are defining an Ant task for running a test.

For details, see Running tests by using an Ant task.

Starting stubs

Retrieving secrets during Tests running from command line, ANT CLI, Maven CLI, or as REST API calls provides the parameter or attributes that you may use when you are starting stubs from the command line, ANT CLI, or as REST API calls.

When starting a stub from the HCL® Quality Server by using the start stub command, you may override the token that is used by the agent by specifying the token by using the parameter or attribute indicated in the following table.

Table 2. Starting stubs when running from command line, ANT, or as REST API calls
Starting a stub Parameter or attribute to use

When using the HCL OneTest™ API command line

Use --secretsAuthorization parameter in the start stub command.

For details, see Start a stub by using the command line.

When running as an ANT task

Use secretsAuthorization attribute in the start stub command.

For details, see Start a stub by using an Ant task.

When running as a REST API call

Use x-secrets-authorization header in the request.