Testing with Jenkins

You can use the HCL OneTest™ UI - Web UI Jenkins plugin for Web UI testing to run tests on a Jenkins server by using a Jenkins build step.

Introduction

To automate testing with Jenkins, you must configure two computers: A Jenkins master and a Jenkins slave. This master-slave configuration allows a single Jenkins installation on the master computer to host multiple slave environments for building and running tests. You must install the latest version of the HCL OneTest UI - Web UI Jenkins plugin on the master computer, and install the products themselves on the slave computer, where you create the tests. For detailed information about the Jenkins master-slave relationship, see the Distributed Builds section on the Jenkins site.

Note: You can download the latest version of the HCL OneTest UI - Web UI Jenkins plugin from HCL License & Delivery portal . You can then install the plugin on the Jenkins server. After you create the tests in HCL OneTest UI, you can run the tests on the Jenkins server by using this plugin.If you have earlier version of the HCL OneTest UI - Web UI Jenkins plugin, you must uninstall it before installing the latest version of the plugin on the Jenkins server.

Before you begin

You must have completed the following tasks:
  • Installed IBM® Installation Manager, which is required for installing the products.
  • Installed the products themselves.
  • Verified that you have a Jenkins master computer where Jenkins and the HCL OneTest UI - Web UI Jenkins plugin is installed.
  • Verified that you have a Jenkins slave computer where the products are installed.
  • Verified that you have a test residing within an Eclipse workspace on the Jenkins slave where the products are installed.
Note:

Running Web UI tests in the Chrome browser on Mac OS requires HCL OneTest UI V9.2.0 or the latest versions of the testing products. For Mac OS, you must add an environment variable that points to the installation directory of the product, for example, export TEST_WORKBENCH_HOME=/opt/HCL/HCLOneTest. For Windows™, this environment variable is already defined.

If you installed the product on Windows by using the stand-alone installer (not using IBM Installation Manager), you must specify the environment variable that points to the installation directory of the product. For example, export TEST_WORKBENCH_HOME=C:\Program Files\HCL\HCLOneTest.

Installing the HCL OneTest UI - Web UI Jenkins plugin on the Jenkins master computer

  1. Download the latest version of the HCL OneTest UI - Web UI Jenkins plugin for the appropriate test product from HCL License & Delivery portal on to the computer where the test product is installed.
  2. From the Jenkins dashboard, perform the following tasks:
    1. Click Manage Jenkins > Manage Plugins.
    2. Click Advanced.
    3. From the Upload Plugin section, click Choose File to locate and Open the HCL OneTest UI - Web UI Jenkins plugin.
    4. Click Upload.

    The HCL OneTest UI - Web UI Jenkins plugin is displayed in the Installed tab.

  3. Configure Global Security to allow Random TCP Ports for Java™ Network Launch Protocol (JNLP) agents.

Job Configuration

  1. Create a new Jenkins free-style software project. For more information to create a free-style Jenkins project, see Building a software project in Jenkins.
  2. From the Jenkins dashboard, perform the following tasks:
    1. Open the Jenkins free-style software project, and then click Configure.
    2. Click Build > Add build step.
    3. Click Run HCL OneTest UI - Web UI test.
  3. Provide the details about the test run as shown. The following table explains each field.
    Field Description
    Name Required. The name of the test.
    Workspace Required. The complete path to the Eclipse workspace.
    Project Required. The path, including the file name of the project relative to the workspace.
    Test Suite Name Required. The path, including the file name of the test to run related to the project.
    Note: You must provide the file name along with the file extension if you are using an Accelerated Functional Test suite.

    To run multiple tests of the same project sequentially, you must specify the test names separated by a comma.

    IMShared Location Optional. The complete path to HCLIMShared location,if it is not the default location.
    Var File Optional. The complete path to the XML file that contains the variable name and value pairs.
    Config File Optional. The complete path to a file that contains the parameters for a test run.
    Results File Optional. The name of the results file. The default result file is the test or schedule name with a time stamp appended. The results file is stored in the Results directory. If you are running multiple tests, do not provide a name for the results file.
    Overwrite Results File Optional. Determines whether a results file with the same name is overwritten. The default value is true, which means the results file can be overwritten.
    Quiet Optional. Turns off any message output from the launcher and returns to the command shell when the run or the attempt is complete.
    VM Args Optional. Java™ virtual machine arguments to pass in.
    Dataset Override Optional. For a test, the default value is the dataset specified in the test editor. Overrides the default dataset value to run if required.
    Note:

    You must use the Dataset Override option to replace the 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 (;).

    For example,

    /project_name1/ds_path/ds_filename.csv:/project_name1/ds_path/new_ds_filename.csv;/project_name2/ds_path/ds_filename.csv:/project_name2/ds_path/new_ds_filename.csv
    Protocol Input Optional. You can use this argument 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,browswer2,browser3"
    Exported Statistical Report Data File Optional. The complete path to a directory to store exported statistical report data.
    Custom Report Format Files Optional. A comma-separated list of absolute paths to custom report format files (.view files) to use when exporting statistical report data with the Export Statistical Report Data File option.
    Exported Statistical Report in html Optional. The complete path to a directory to export web analytic results. Analyze the results on a web browser without using the test workbench. If you run multiple tests, do not provide a value in this field. The web analytic results will be exported to Jenkins workspace.
    User Comments Optional. Add text within the double quotation mark to display it in the User Comments row of the report.

    If you do not supply a value for Exported Statistical Report Data File, these logs will be saved in Jenkins workspace/temp directory.

  4. Click Save.
  5. Optionally, to run multiple tests under the same job, click Add build step again, and provide details for the next test.

Master/Slave Configuration

Master and slave configurations are supported by HCL OneTest UI - Web UI Jenkins plugin . Refer to Distributed builds for more information.

While creating the job configuration, in addition to the preceding steps, you must select the Restrict where this project can be run check box and provide the name of the slave node in the Label Expression field. This is the location where the products are installed and where tests can be run.

Restrict where this project can be run

Running tests

After you save the project, you must open the project, and then click Build Now. This action starts the test run on the slave computer. You can run multiple tests of the same project by specifying test names (../<testName>) separated by a comma in Test Suite Name. You must specify the relative path from the project to the test including the file name of the test. To run multiple tests from different projects, you must add new build step for each project.

Building result and logs

  1. After the build completes, click the build number and open the console for the project. Locate the Test Result to check the test execution status.
    Note: If you add multiple build steps to run multiple tests, multiple Test Result instances are displayed.
  2. For product logs, log in to the slave computer and search in the Jenkins slave workspace/temp directory.