Configuring a test run in a GitHub Actions Workflow

After you complete the prerequisite tasks to run tests in a GitHub Actions Workflow, you can configure the test run in a GitHub Actions Workflow.

Before you begin

You must have completed the tasks mentioned in Prerequisites to run tests in a GitHub Actions Workflow.

Procedure

Perform the following steps to open the Git repository that you use or created, which has the GitHub Actions option enabled.
1. Open the Git repository on your GitHub Enterprise server.
2. Create a folder with the name as .github/workflows in the root folder of the repository.
3. Create an empty YAML file in the .github/workflows folder.
  
  The YAML file is used to define the GitHub Action in the Actions Workflow.

Perform the following steps to define the YAML file for the GitHub Action:

Open the GitHub Marketplace (https://github.com/marketplace?type=) in a web browser.
Search for HCL DevOps Test Performance GitHub Action that is available for running test resources that are in Test Performance project.
Click HCL DevOps Test Performance GitHub Action .
Read through the information provided.
Copy the contents of the YAML file that is provided in the example by clicking the copy icon .
Open the YAML file that is in the .github/workflows folder of your repository and paste the copied contents.

Refer to the following table to enter the required details in the YAML file:

The following table lists the required parameters that you must provide in the YAML file to run the test from the GitHub Action:

Parameters	Description
configFile	Enter the complete path to a configuration file that contains the parameters for a `test` or `schedule` run. For more information about creating a command line config file from Test Performance, see the Related information section. Note: If you provide a complete path of a configuration file for the configFile parameter, then you need not provide values for the workspace, project, and suite parameters. For example, `name: HCL DevOps Test Performance on: workflow_dispatch jobs: Performance-Action: name: HCL DevOps Test Performance runs-on: self-hosted steps: - name: HCL DevOps Test Performance uses: HCL-TECH-SOFTWARE/devops-perf-action@main with: configfile: <C:\Users\HCL\devopstest\workspace\project123\config.txt>`
project	Enter the name of the project that has performance test assets. For example, `name: HCL DevOps Test Performance on: workflow_dispatch jobs: Performance-Action: name: HCL DevOps Test Performance runs-on: self-hosted steps: - name: HCL DevOps Test Performance uses: HCL-TECH-SOFTWARE/devops-perf-action@main with: workspace: <C:/Users/HCL/devopstest/workspace> project: <proj123>`
suite	Enter the name of the test asset that you want to run. For example, `name: HCL DevOps Test Performance on: workflow_dispatch jobs: Performance-Action: name: HCL DevOps Test Performance runs-on: self-hosted steps: - name: HCL DevOps Test Performance uses: HCL-TECH-SOFTWARE/devops-perf-action@main with: workspace: <C:/Users/HCL/devopstest/workspace> project: <proj123> suite: <test1.testsuite>`
workspace	Enter the complete path of the Eclipse workspace. For example, `name: HCL DevOpsTest Performance on: workflow_dispatch jobs: Performance-Action: name: HCL OneTest Performance runs-on: self-hosted steps: - name: HCL OneTest Performance uses: HCL-TECH-SOFTWARE/devops-perf-action@main with: workspace: <C:/Users/HCL/devopstest/workspace>`

The following table lists the optional parameters that you must provide in the YAML file to run the test from the GitHub Action:

Parameters Description

duration

Use this parameter to change the duration of the stages in the rate schedule.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            duration: <Stage1=10s, Stage2=3m>

The stage number specified must exist in the rate schedule.

exportLog

Use this parameter to specify the path of the file directory to store the exported HTTP test log in a .txt format.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            exportLog: <C:/Users/Documents/GitActions/LogExp.txt>

exportStatReportList

Use this parameter to specify IDs of reports that you want to export in place of the default reports.

You can provide multiple report IDs separated by a comma. You can navigate to Preferences of Test Performance (Window > Preferences > Test > Performance Test Reports > Export Reports), and then select Show Report IDs checkbox to view the report IDs.

You must use the exportStatReportList parameter along with the exportStats or exportstatshtml parameter.

For example, you can provide the value for the exportStatReportList parameter as follows to export the Performance Report:

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            exportStats: <C:/Users/Documents/GitActions>
            exportStatReportList: <http>

exportStats

Use this parameter to provide the complete path to a directory that you can use to store the exported report in a comma-separated values (CSV) format.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOpsTest Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            exportStats: <C:/Users/Documents/GitActions>

exportStatsFormat

Use this parameter to specify a format for the result that you want to export along with the exportStats parameter.

You must use at least one of the following options with the exportStatsFormat parameter:

simple.csv
full.csv
simple.json
full.json
csv
json

You can add multiple options separated by a comma. When you want to export both simple and full type of test results in a json or csv format, you can specify either json or csv as options.

For example,

name: HCL DevOpst Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            exportStats: <C:/Users/Documents/GitActions>
            exportStatsFormat: <json>

imShared

Use this parameter to enter the complete path to the HCLIMShared location, if it is not in the default location.

The default location of the IMShared directory is as follows:

Operating system	The default path to the directory
Windows®	C:\Program Files\HCL\HCLIMShared
Linux™	/opt/HCL/HCLIMShared
Mac	/Application/HCL/HCLIMShared

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            imsharedloc: <D:\Testtool\HCL\HCLOneTest>

labels

Use this parameter to add labels to test results when the test run is complete.

You can add multiple labels to a test result separated by a comma. When you run test assets, then the labels that you added are displayed on the Performance Report in Test Performance.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            labels: <label1, label2>

overrideRmLabels

Use this parameter to perform any of the following actions:

Enable the Resource Monitoring from Service option for a performance schedule if the Resource Monitoring from Service option is not enabled from the schedule editor in Test Performance.
Ignore Resource Monitoring sources that were set in the performance schedule and change for a label matching mode.
Replace an existing set of Resource Monitoring labels that were set in the performance schedule and run the schedule with a new set of Resource Monitoring labels.

For example,

name: HCL DevOpsTest Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL One Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            overrideRmLabels: <rm1>

Notes:

You can use this field only when you want to run a Rate schedule or VU schedule.
You can add multiple Resource Monitoring labels separated by a comma.
You must add the Resource Monitoring labels to the Resource Monitoring sources on the Resource Monitoring page in the Test Hub project.

overwrite

Set this parameter value to true or false to determine whether a result file with the same name must be overwritten or not.

The default value is false.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            overwrite: <true>

publish

Use this parameter to publish test results to Test Hub.

Remember: Before you use the publish parameter, you must provide the offline user token of Test Hub by using any of the following methods:

Set the value of the HCL_DEVOPS_OFFLINE_TOKEN environment variable to the offline user token of Test Hub by using the command-line interface.
Provide the offline user token of Test Hub in the preferences of Test Performance (Window > Preferences > Test > DevOps Test Hub)

You must use one of the following values in the publish parameter:

serverURL#project.name=name_of_the_project&teamspace.name=name_of_the _teamspace
serverURL#project.name=name_of_the_project&teamspace.alias=name_of_the _teamspace_alias
no
The no option is useful if the product preferences are set to publish the results, but you do not want to publish them.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            publish: <URL_OF_DevOpsTest_Hub#project.name=test&amp;teamspace.name=ts1>

Where:

URL_OF_Test Hub is the URL of Test Hub.
test is the name of the project in Test Hub.
ts1 is the name of the team space.

Notes:

If you have a project with the same name in different team spaces, then you must append either the &teamspace.name=name_of_the _teamspace or &teamspace.alias=name_of_the_teamspace_alias options.
If the name of the project or team space contains a special character, then you must replace it with %<Hexvalue_of_special_character>.

For example, if the name of the team space is Initial Team Space, then you must provide it as Intial%20Team%20Space.

Where %20 is the Hex value of Space character.
The values provided in the Publish field always take precedence over the Results options set in the product preferences (Window > Preferences > Test > DevOps Test Hub > Results).

The Reports information section on the Log file displays the names of the report along with its corresponding URLs in the following conditions:

When you configured the URL of Test Hub in Preferences of Test Performance (Window > Preferences > Test > DevOps Test Hub).
When you set Publish result after execution as Always or Prompt in the Preferences of Test Performance (Window > Preferences > Test > DevOps Test Hub > Results).
When you used publish parameter or publish parameter along with publishreports parameter.

publishFor

Use this parameter to publish test results to Test Hub based on the completion status of the tests.

You must use the publishFor parameter along with the publish parameter. You must add multiple parameters separated by a comma. The available options that you can use for the publishFor parameter are as follows:

ALL: You can use this option irrespective of status of the test.
PASS: You can use this option to publish test results for the tests that have passed.
FAIL: You can use this option to publish test results for the tests that have failed.
ERROR: You can use this option to publish test results for the tests that included errors.
INCONCLUSIVE: You can use this option to publish test results for the inconclusive tests.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            publish: <URL_OF_DevOpsTest_Hub#project.name=test&amp;teamspace.name=ts1>
            publishFor: <PASS,ERROR>

publishReports

Use this parameter to publish specific test results to Test Hub.

You must use the publishReports parameter along with the publish parameter. The options that you can use with publishReports are as follows:

STATS
TESTLOG

You can prefix the publishReports value with ! to publish the reports except for the specified one in the test script.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            publish: <URL_OF_DevOpsTest_Hub#project.name=test&amp;teamspace.name=ts1>
            publishReports: <STATS>

rate

Use this parameter to change the rate of the rate runner group.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            rate: <Rate Runner Group1=1/s, 3/m>

Where, Rate Runner Group1 is the name of the rate runner group that has two stages. The desired rate for the first stage is one iteration per second and the rate for the second stage is three iterations per minute.

Notes:

The name of the Rate Runner group must match with the name in the rate schedule.
The rate parameter creates a new copy of the rate schedule that contains the specified number of rate.

reportHistory

Use this parameter when you want to view a record of all events that occurred during a test or schedule run.

You can use any of the following options:

jaeger: To send test logs to the Jaeger UI during the test or schedule run.
Note: You must set the JAEGER_AGENT_HOST property as an environment variable by using the command line before you use the jaeger option to send test logs to the Jaeger UI.
testlog: To send test logs as traditional test logs in Test Performance during the test or schedule run.
null: To send no test logs either to the Jaeger UI or Test Performance during the test or schedule run.

You can add multiple options separated by a comma to send test logs during the test or schedule run to Test Performance and the Jaeger UI.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            reportHistory: <jaeger,testlog>

For more information about how to view test logs in the Jaeger UI and Test Performance, see the Related information section.

results

Use this parameter to provide a different name to the result file.

The default name of the result file is the name of the test or schedule with a timestamp appended.

swapDatasets

Use this parameter to replace the dataset values during a test or schedule run.

You must ensure that both original and new datasets are in the same workspace and have the same column names.When you enter a value for the swapDatasets parameter, you must also include the path to the dataset. You must provide the values for the swapDatasets parameter in the following format:

/project_name/ds_path/original_ds.csv:/project_name/ds_path/new_ds.csv

You can override multiple datasets that are saved in a different project by adding multiple paths to the dataset separated by a semicolon. For a test or schedule, the default value is the dataset specified in the test editor or schedule editor.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            swapDatasets: </proj1023/Datasets/ds1.csv:/proj1023/Datasets/new_ds1.csv>

userComments

Use this parameter to add text that you want to display in the user comments row of the report.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            userComments: <test run with dataset>

users

Use this parameter to overrides the default number of users, if required.

For a schedule, the default is the number of users specified in the schedule editor and for a test, the default is one user.

For example,

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL OneTest Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            users: <50>

varFile Use this parameter to provide a complete path to an XML file that contains the variable name and value pairs.

vmArgs

For example, when you input the value as -Xmx4096m, it specifies the maximum heap size as 4GB.

name: HCL DevOps Test Performance
on: workflow_dispatch
jobs:
    Performance-Action:
        name: HCL DevOps Test Performance
        runs-on: self-hosted
        steps:
         - name: HCL DevOps Test Performance
           uses: HCL-TECH-SOFTWARE/devops-perf-action@main
           with:
            workspace: <C:/Users/HCL/devopstest/workspace>
            project: <proj123>
            suite: <test1.testsuite>
            vmArgs: <-Xmx4096m>

Save the YAML file.

Perform the following steps to set up a Runner for the GitHub Action in GitHub:
1. Click the Settings icon .
2. Click Actions > Runners > New self-hosted runner.
3. Follow the onscreen instructions to set up a self-hosted runner on your computer.
  
  After the runner is installed on your computer, you must verify that the runner is ready to take up jobs in the GitHub Actions Workflow and is in the Active state. The runner is listed in the Runners pane in the Git repository.
Perform the following steps to start the GitHub Action in the Workflow:
1. Click the Actions option in the Git repository.
  
  The GitHub Action that you configured in the YAML file for Test Performance is displayed as an Action under Workflows.
2. Click HCL DevOps Test Performance GitHub Action, and then click Run workflow.

Results

You have configured and run a resource that is in your project on Test Performance in a GitHub Action Workflow.

What to do next

You can perform any of the following tasks in the Git repository page by clicking the job that was completed:

View the status of the test run by expanding the Execute test section.
View the links to the test results and reports listed in the Execute test section.