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 .github/workflows in the root folder of the repository.
    3. Create an empty YAML file in the .github/workflows folder.

      The YAML file will be 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 OneTest WebUI GitHub Action to run test resources that are in a HCL OneTest™ UI project.
    3. Open HCL OneTest WebUI 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:
      Field Description
      Required
      workspace Enter the complete path of the Eclipse workspace.
      project Enter the name of the project containing the test.
      suite Enter the name of the test that you want to run.
      Optional
      imshared Enter the complete path to the location of the HCLIMShared folder if it is not in the default path. For example, D:\HCL\HCLIMShared
      Note: If you do not enter any value, the default path of the HCLIMShared folder is considered for test run. The default path in the different operating systems is as follows:
      • Linux: /opt/HCL/HCLIMShared
      • Mac: /Application/HCL/HCLIMShared
      • Windows: C:\Program Files\HCL\HCLIMShared
      configFile Enter the complete path of the file that contains the parameters for a test run.
      exportLog Enter the file path to store the exported HTTP test log. You can provide multiple parameter entries when running multiple tests. You must use a colon to separate the parameter entries. For example: c:/logexport.txt:c:/secondlogexport.txt
      exportReport Use this option to export the unified report of UI tests to the file formats such as PDF, HTML, and XML. For example, to export the report to only the PDF format, you can input the following values:

      type=unified;format=pdf;folder=Exportedreport102;filename=testreport
      exportStatReportList Enter the list of report IDs separated by a comma. You must use this option with exportstats or exportstatshtml to list the reports that you want to export in place of the default reports, or the reports selected under Preferences.
      Perform the following steps to retrieve the report IDs:
      • Navigate to Window > Preferences > Test > Performance Test Reports > Export Reports in HCL OneTest™ UI.
      • Select the required reports in the Select reports to export section.
      • Click Copy ID to clipboard.
      exportStats Enter the complete path of the folder to store the exported statistical report data.
      exportStatsFormat

      Specify a format for the report that you want to export. You must use the exportStats parameter along with the exportStatsFormat parameter.

      You must use at least one of the following formats:

      • simple.csv

      • full.csv

      • simple.json

      • full.json

      • csv

      • json

      For example, 
      Export stats = <local_dir_path> 
Export stats format = json

      You can add multiple formats for the report separated by a comma (,).

      The reports are saved to the location specified in the exportStats field.
      exportStatsHtml Enter the complete path to a directory to export web analytic results. If you run multiple tests, do not provide a value in this field.
      imports Enter the complete path to the project folder that is cloned from a source control system or remote repository. When you use this option, you can specifiy a name for the new workspace to be created to run the imported test assets.
      labels Enter the labels to be added to the test results when the test run is complete. You can add multiple labels to a test result separated by a comma.

      For example, label1, label2

      When you run test assets then the same labels are displayed on the UI Test Statistical Report in HCL OneTest™ UI.

      If you have set Publish result after execution as Always or Prompt in the HCL OneTest™ UI preferences (Window > Preferences > Test > HCL OneTest Server) and use the Labels option, then the Results page of HCL OneTest™ Server displays the same label for the specific test asset.
      overwrite Set the value as true to overwrite the existing result file and retain the same file name. The default value, false, indicates that the new result file is created.
      protocolinput You can use this option with additional arguments as follows:
      • To run a Web UI test in parallel on different browsers

        -protocolinput "all.available.targets.in.parallel=all"

        Note: If you use the -protocolinput argument, you must not use the following equivalent -vmargs arguments: 
        -vmargs "-Dall.available.targets.in.parallel=all"

      • To specify the Web UI preferences such as highlighting the page element and capturing screens

        For example, -protocolinput "webui.highlight=<value>;webui.report.screenshots=<value>" where webui.highlight specifies whether the page element must be highlighted and webui.report specifies whether the screens must be captured while playing back the test in the browser.

      • To run only the failed tests from a previous playback in an Accelerated Functional Test suite

        cmdline -workspace workspacename -project projectname -aftsuite aftsuitname -exportlog exportlogpath -results autoresults -protocolinput "runfailedtests=true"

        In the preceding example, runfailedtests=true specifies whether the failed test from a previous playback must be rerun in Accelerated Functional Test suite.

      • To automatically resolve the browser and driver incompatibility, while you play back the Web UI tests

        -protocolinput "webui.browser.driver.autoupdate=true"

      • To apply guided-healing and self-healing features while you run Web UI tests

        cmdline -workspace workspacename -project projectname -suite test1 -exportlog exportlogpath -results autoresults -protocolinput "autoheal=true"
      publish Specify the server URL and project name to publish test results to HCL OneTest™ Server.

      You must provide the URL and offline user token of the server in Window > Preferences > Test > HCL One Test Server of HCL OneTest™ UI before you use the publish parameter in the test script.

      Use the following arguments with the publish parameter:

      • To specify the project name, use any of the following formats:

        • serverURL #project.name=projectName&teamspace.name=name_of_the _teamspace

        • serverURL #project.name=projectName&teamspace.alias=name_of_the _teamspace_alias

        You must consider the following point while providing the values:
        • If the name of the project or team space contains a special character, then you must replace it with %<Hex_value_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 hexadecimal value of the space character.
      publish_for

      Specify the option to publish test results to HCL OneTest™ Server based on the completion status of the tests. You must use the publishFor parameter along with the publish parameter.

      The following are the available options that you can use for the publishFor parameter:

      • ALL - This is the default option. You can use this option to publish test results for any text execution verdict.
      • 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.
      You can add multiple parameters separated by a comma.
      publishReports Specify the option to publish test results in HCL OneTest™ Server. The values that you can use with publishReports are as follows:
      • FT - This is an identifier for Functional Test Report. You can use this value to publish the unified report if it is available for the selected test. See Unified reports.
      • STATS - This is an identifier for Statistics Report. You can use this value to publish the web analytics report if it is available for the selected test. See UI Test Statistical report.
      • TESTLOG - This is an identifier for Test Log. You can use this value to publish the test log if it is available for the selected test. See Logs overview.

      You must use the publishReports parameter along with the publish parameter.
      results Enter a folder name that is relative to the project to store the test results. For example, results folder/resultname.
      swapDatasets For a test, the default value is the dataset specified in the test editor.

      You must use the swapdatasets option to replace dataset values during a test run. You must ensure that both original and new datasets are in the same workspace and have the same column names. You must also include the path to the dataset.

      For example: /project_name/ds_path/ds_filename.csv:/project_name/ds_path/new_ds_filename.csv.
      User Comments Enter the text within double quotation mark to display it in the User Comments row of the report.
      varFile Enter the complete path to the XML file that contains the variable name and value pairs.
      vmArgs To specify the Java™ maximum heap size for the Java™ process that controls the command line playback, use the -vmargs option with the -Xmx argument.

      For example, when you use-vmargs -Xmx4096m, specify a maximum heap size of 4096m. This method is similar to specifying -Xmx4096m in the eclipse.ini file for the workbench when playing back the test from the user interface.

      To collect the response time data for the app itself and for the server and network and display them in different bar charts, use -vmargs "-De2e.collect=true". For desktop-based web applications, the response time data is captured and displayed by default.

      To execute tests in parallel on all mobile devices, which are in passive mode, connected to the workbench and ready for playback, use -vmargs "-Dall.available.targets.in.parallel=true".

      To execute tests in parallel on all supported desktop browsers and connected mobile devices, use -vmargs "-Dall.available.targets.in.parallel=all".

      To execute tests in parallel on selected desktop browsers and connected mobile devices, use -vmargs "-Dall.available.targets.in.parallel=browser1,browswer2,browser3". You must separate browser names with a comma. For example, firefox, ff, chrome, ie, ie64, safari, "-Dall.available.targets.in.parallel=browser1,browser2,browser3".
    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 start the runner. The runner is listed in the Runners pane in the Git repository. The runner is in the Idle state when it is connected to Github and is ready to execute jobs.

      Note: You must ensure that the runner is not in the Offline state before you run a workflow.
  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 HCL OneTest™ UI is displayed as an Action under Workflows.

    2. Click HCL OneTest WebUI GitHub Action, and then click Run workflow.

Results

You have configured and run a resource that is in your project on HCL OneTest™ UI in a GitHub Action Workflow.

What to do next

You can perform any of the following tasks on 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.