Testing with Ant

You can use Ant to run compound tests and Web UI tests from the command-line interface.

Before you begin

You must have completed the following tasks:

  • Installed Installation Manager.

  • Installed HCL OneTest™ UI.

  • Verified that you have test assets residing within HCL OneTest™ UI.

  • Downloaded the HCL OneTest™ UI Web UI Ant plugin 8.0 from the HCL® License & Delivery portal on to the computer where you install the product.

  • Added Ant to the PATH environment variable.

About this task

To run Web UI tests on Mac OS, you must add an environment variable that points to the installation directory of HCL OneTest™ UI.

For example, export TEST_WORKBENCH_HOME=/opt/HCL/HCLOneTest.

Note: For Windows™ and Linux®, the environment variable is set when you install the product.

Procedure

  1. Extract the following files from the downloaded ant plugin:

    • HOT-UI-Ant-UITest-x.0.jar

      Where, x is the version number of the Ant plugin.

    • HOT-UI-Ant-UITest.xml

    • README.txt

  2. Open the HOT-UI-Ant-UITest.xml file and provide required parameter values.
    You must provide the values for the following required parameters:
    • name
    • workspace
    • project
    • suite
    If you include these required parameters in a configuration file and use the Configfile parameter to specify the complete file path, then these parameters are not required.
    Remember: You must consider the following requirements:
    • Enter the parameter values within the double quotation marks.
    • Ensure that the special characters in the parameter values do not break the validation of the XML file. For example, you must enter the & character as &.
    For example,

    <webui name="test1" workspace="C:\workspace" projectname="TestProject" suite="Tests/test1.testsuite" results="Results/test1_on_anttask" />

    Note: You can add an additional <webui> task and provide the details for each test to run multiple tests simultaneously.

    The following table explains each parameter in detail.

    Parameter Description
    Required
    name The name of the test for the particular test product.
    workspace The complete path to the Eclipse workspace.
    projectname The path, including the file name of the project relative to the workspace.
    suite The path, including the file name of the test to run relative to the project. A test can be a Web UI test, compound test, or an Accelerated Functional Test.
    Note: You must provide the file name along with the file extension if you are using an Accelerated Functional Test suite.
    Optional
    configfile The complete path to a file that contains the parameters for a test run.
    exportReport The option to export the unified report of UI tests to the file formats such as PDF, HTML, and XML.
    Note: The exported XML file is a JUnit XML file. You can view this file in applications that support JUnit reporting formats.

    The command syntax is as follows:

    exportReport="type=<reporttype>;format=<file type1,file type2,file type3>;folder<destination folder path>;filename=<name of the exported file>"

    For example, to export the report to only the pdf format, you can use exportReport "type=unified;format=pdf;folder=Exportedreport102;filename=testreport

    If you want to export the report to multiple formats, you can specify the file formats as comma-separated values. The file type value can be in uppercase or lowercase.

    For example, to export the report to all the supported formats, you can use

    exportReport "type=unified;format=pdf,xml,html;folder=Exportedreport102;filename=testreport

    The report in different file formats use the same file name that is specified in the command.
    exportstatreportlist A comma-separated list of absolute paths to custom report format files (.view files) to use when exporting statistical report data with the exportstats option.
    exportstats The complete path to a directory that can be used to store exported statistical report data.
    exportstatsformat The option to specify a format for the result that you want to export along with the exportstats option. You must use at least one of the following parameters with the exportstatsformat option:

    • simple.csv

    • full.csv

    • simple.json

    • full.json

    • csv

    • json

    For example, exportstats="<local_dir_path>" exportstatsformat="simple.json"

    You can add multiple arguments separated by a comma.

    For example, exportstats="<local_dir_path>" exportstatsformat="simple.json, full.csv"

    When you want to export both simple and full type of test results in a json or csv format, you can specify json or csv as the arguments in the command. When the test run completes, the test result exports to simple.json and full.json files.

    For example, exportstats="<local_dir_path>" exportstatsformat="json"
    exportstatshtml The complete path to a directory that can be used to export web analytic results. The results are exported in the specified directory. Analyze the results on a web browser without using HCL OneTest™ UI.
    imports When you want to run Web UI tests that are in a source control system such as Git from a computer that runs the desktop product, you can clone the project resources in the remote repository to your computer. You can use an empty workspace folder on your computer to import the UI Test project resources and then run the tests. The desktop product is enabled to run the Web UI tests without the need of the workspace in the cloned repository or your existing workspace. You must use the workspace argument to precede the imports argument.
    Note: You can use this argument in the following scenarios:
    • You do not want to use your existing workspace.
    • You do not want to use the workspace cloned from a remote repository.
    To run UI tests contained in UI Test projects that are in a remote repository, you must perform the following steps:
    1. Clone the remote repository that contains the UI Test project to your computer.
    2. Create an empty workspace on your computer.
    3. Add the following command to the HOT-UI-Ant-UITest.xml file:

      name="<test_name>" workspace="<path_of_empty_workspace>" project="<project_name>" imports="<path_to_cloned_project_folder>" suite="<test_name>"

      For example,

      name="test1" workspace="C:\workspace" project="UIProject1" imports="d:\work\UIProject1" suite="Test1"
    imsharedloc The complete path to HCLIMShared location, if it is not at the default location.
    labels

    The option to add labels 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, labels =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 labels option, then the Results page of HCL OneTest™ Server displays the same label for the specific test asset.

    Note:
    • When you run tests by using the double quotation marks ("") for the labels parameter, then the labels in the test result do not include the double quotation marks.
    • To work around this problem, you must create a command-line config file, and then run the test by using the configfile parameter.
    • When you use the configfile parameter to run tests, then labels provided in the configuration file take precedence over the labels provided in the HOT-UI-Ant-UITest.xml file.
    overwrite Determines whether a result file with the same name is overwritten. The default value is false, which means the result file cannot be overwritten and a new result file is created.
    protocolinput The option to run a Web UI test in parallel on different browsers.

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

    protocolinput="all.available.targets.in.parallel=chrome,ff,ie"

    Note: If you use the protocolinput argument, you must not use the equivalent vmargs arguments:
    vmargs="-Dall.available.targets.in.parallel=all"
vmargs "-Dall.available.targets.in.parallel=browser1,browser2,browser3"
    publish The option to publish test results to HCL OneTest™ Server.

    You must provide the URL and offline user token of the server in Window > Preferences > Test > Rational Test Automation Server > 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 points while providing the project name:

      • If the project name is not specified, then the value of the Project parameter is used.

      • If you have a project with the same name in different team spaces, then you can append either the &teamspace.name=name_of_the _teamspace or &teamspace.alias==name_of_the_teamspace_alias options.

        For example: 
        name="test1" workspace="C:/Users/IBM/rationalsdp/workspace1" project="proj1" 
suite="Tests/testHttp.testsuite" publish="https://localhost:5443#project.name=test&amp;teamspace.name=ts1"
        Where:

        • https://localhost:5443 is the URL of the server.

        • test is the name of the project.

        • ts1 is the name of the team space.

      • While providing the name of the team space or team space alias, you must replace the ampersand (&) character with &amp; as shown in the preceding example.
      • 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.

    • To avoid publishing of reports, use no.

      You can use the no option if you do not want to publish test results after the run. This option is useful if the product preferences are set to publish the results, but you do not want to publish them.

      For example:
      name="test1" workspace="C:/Users/IBM/rationalsdp/workspace1" project="proj1" 
suite="Tests/testHttp.testsuite" publish="no"

    If you do not use the configfile parameter to run the tests, then the values provided in the test script always take precedence over the Results options set in the product preferences (Window > Preferences > Test > HCL One Test Server > Results).

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

    • When you configured the URL of HCL OneTest™ Server in preferences of HCL OneTest™ UI (Window > Preferences > Test > HCL One Test Server.

    • When you set Publish result after execution as Always or Prompt in the preferences of HCL OneTest™ UI (Window > Preferences > Test > HCL One Test Server > Results).
    publish_for

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

    The following are the available options that you can use for the publish_for 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.
    For example: 
    name="test1" workspace="C:/Users/IBM/rationalsdp/workspace1" project="proj1" 
suite="Tests/testHttp.testsuite" publish="https://localhost:5443#project.name=test&amp;teamspace.name=ts1" 
publish_for="FAIL,ERROR"
    publishreports 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.

    For example: 
    name="test1" workspace="C:/Users/IBM/rationalsdp/workspace1" project="proj1" 
suite="Tests/testHttp.testsuite" publish="https://localhost:5443#project.name=test&amp;teamspace.name=ts1" 
publishreports="STATS, TESTLOG"

    The values specified here override the values selected in Window > Preferences > Test > HCL One Test Server > Results of HCL OneTest™ UI.

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

    For example, 
    name="test1" workspace="C:/Users/IBM/rationalsdp/workspace1" project="proj1" 
suite="Tests/testHttp.testsuite" publish="https://localhost:5443#project.name=test&amp;teamspace.name=ts1" 
publishreports="!TESTLOG"

    All the reports except the TESTLOG report is published to HCL OneTest™ Server after executing the command.
    results The name of the results file. The default result file is the test name with a time stamp appended.
    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. You can swap multiple datasets that are saved in a different project by adding multiple paths to the dataset separated by a semicolon (;).
    usercomments The option to add text within the double quotation mark () to display it in the User Comments row of the report.
    Note:
    • When you run tests by using the double quotation marks ("") for the usercomments parameter, then the User Comments row of a report does not contain double quotation marks.
    • To work around this problem, you must create a command-line config file, and then run the test by using the configfile parameter.
    varfile The complete path to the XML file that contains the variable name and value pairs.
    vmargs To pass Java™ virtual machine arguments.
  3. Open a command prompt and navigate to the directory where you downloaded the Ant plugin.
    Note:
    You must close HCL OneTest™ UI before you run the test.
  4. Enter ant -f HOT-UI-Ant-UITest.xml to run the test.

Results

You have run the test by using the Ant plugin.

What to do next

You can view that the Ant execution output is logged into the logfile.txt file, and a test log is created in a temp directory called HOT-UI-Ant-UITest-x.0.