Accessing DevOps Test Hub

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

Prerequisites

Before you can access Test Hub, certain tasks must be completed:
  • You must have installed and configured Test Hub. For more information about Test Hub, 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 Test Hub and created a secrets collection containing secrets in that project.
  • You must have logged in to Test Hub and copied the offline user token generated by using the Offline Token option from the Test Hub Header. See Generating an offline user token. You must have retained the token copy because this offline user token is used to access Test Hub.

Generating an offline user token

  1. Log into Test Hub.
  2. Click the image of the user action icon. icon in the Test Hub 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 Test Hub nor is retrievable from the Test Hub at a later time.

Using the offline token

The offline user token enables you to connect to Test Hub from Test Integrations and APIs.

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

You can paste the generated offline user token in the Test Integrations and APIs UI. See Accessing Test Hub from Test Integrations and APIs.

Locating the used offline token

The offline user token that you generated and copied from Test Hub and used in the Test Integrations and APIs 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 Test Integrations and APIs as detailed in Accessing Test Hub from Test Integrations and APIs.
  • By setting the value of an OS environment variable (HCL_ONETEST_OFFLINE_TOKEN=<generated offline user token>)

When running test resources in the Test Integrations and APIs UI, the offline user token defined in the .userProfile file is used to access Test Hub. 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 Test Hub from Test Integrations and APIs

You can access Test Hub from Test Integrations and APIs so that you can retrieve the secrets configured for a project in a team space and stored on Test Hub or to publish test reports from Test Integrations and APIs to Test Hub.

Before you begin

Before you use Test Integrations and APIs to access Test Hub, certain tasks must be completed. See Prerequisites.

About this task

After you have generated an offline user token in Test Hub, you must configure Test Integrations and APIs to access Test Hub.

Procedure

  1. Open your project. From the Test Integrations and APIs 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 DevOps Test Hub check box.
    2. Enter the hostname of the server hosting Test Hub 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 Test Hub.
    4. Click SSL, select an option if different from the one selected and then click OK.
    5. Test the connection to Test Hub by clicking Test.
      Important: You must enter the offline user token before you can test the connection to Test Hub.

      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 Test Hub 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 Test Hub are displayed implying that the connectivity to Test Hub 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 Test Hub 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 Test Hub 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 DevOps Test Hub field.
    3. Click Apply and then click OK to apply, save, and exit from the dialog.
    Note: If you added the Test Hub 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 Test Integrations and APIs to access Test Hub.

What to do next

You can retrieve the secrets created and stored in a secret collection in a project in a team space on Test Hub from Test Integrations and APIs. For instructions, see Retrieving secrets from DevOps Test Hub.

Accessing Test Hub 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 Test Hub you can use an optional parameter or attribute in your command argument.

Before you begin

Before you can access Test Hub, 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 Test Hub in the Test Integrations and APIs 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 Test Hub Parameter or attribute to use

When using the Test Integrations and APIs 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 Test Hub 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 Test Virtualization Control Panel 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 Test Integrations and APIs 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.