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

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

  2. Perform the following steps to define the YAML file for the GitHub Action:
    1. Open the GitHub Marketplace (https://github.com/marketplace?type=) in a web browser.
    2. Search for HCL DevOps Test Performance GitHub Action that is available for running test resources that are in Test Performance project.
    3. Click HCL DevOps Test Performance GitHub Action .
    4. Read through the information provided.
    5. Copy the contents of the YAML file that is provided in the example by clicking the copy icon Image of the copy icon..
    6. Open the YAML file that is in the .github/workflows folder of your repository and paste the copied contents.
    7. 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>
    8. Save the YAML file.
  3. Perform the following steps to set up a Runner for the GitHub Action in GitHub:
    1. Click the Settings icon Image of 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.

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