Installing software

Before you begin working with the HCL OneTest™ API project in your Maven build, you must complete installing the requisite software.

About this task

Depending on the operating system of the system where you intend to install the software, refer to the relevant OS documentation for the procedure.

Procedure

Install Java SE Development Kit (JDK) 6 or later, on the system where you intend to install Apache Maven and HCL OneTest™ API.
Configure an environment variable for JAVA_HOME to point to the installed JDK location and is set as the default JDK.
Setting JDK as the default ensures that Maven uses the installed JDK as its default JRE.
Install Apache Maven version 3.2.5 or later, on the same system where you have installed JDK. Ensure that the Maven version is compatible with the JDK version.
You can check the version of JDK supported for the Maven version from the list at Maven Releases History.
Install HCL OneTest™ API Version 9.1.1.1 or later, on the system where you have installed JDK and Maven.
See Installation of HCL OneTest API.
Install HCL Quality Server Version 9.1.1.1 or later, on the system where you have installed HCL OneTest™ API or on a remote server.
See Installation of HCL OneTest API Agent.
Verify that the installed HCL Quality Server is accessible by completing the following steps:
1. Open a web browser on your Apache Maven system.
2. Enter the server address and port number you configured for HCL Quality Server.
  For example, use https://localhost:5443 if you have installed it on your local system.
3. The login page of HCL Quality Server must display.

What to do next

You must configure environment variables for the installed software components.

Setting up environment variables

You can configure an environment variable for the installed software components to enable Maven find the location of the installed components during its build process.

Procedure

Setting the JAVA_HOME environment variable

If not configured already, configure an environment variable JAVA_HOME to point to the installed JDK location and is set as the default JDK.
Setting JDK as the default ensures that Maven uses the installed JDK as its default JRE. For example, the path to the location of JDK can be:
Set %JAVA_HOME% = C:\Program Files\Java\jdk1.8.0_191 and ensure not to point to the JRE location contained within the JDK folder to C:\Program Files\Java\jdk1.8.0_191\jre.

Setting the INTEGRATION_TESTER_HOME environment variable

Configure an environment variable for one of the following variables:
- INTEGRATION_TESTER_HOME to point to the installation location of HCL OneTest™ API. For example, set %INTEGRATION_TESTER_HOME% = C:\Program Files\HCL\HCLProducts\API.
- INTEGRATION_TESTER_AGENT_HOME to point to the installation location of HCL OneTest™ API Agent. For example, set %INTEGRATION_TESTER_AGENT_HOME% = C:\Program Files\HCL\HCLProducts\Agent.

What to do next

You must set up the integration test resources.

Setting up integration test resources

Before you can run Maven commands, you must set up the integration test resources that Maven uses in its build.

Before you begin

You must set up your own project resources that you want to test by using HCL OneTest™ API. Alternatively, you can use the samples that you can download from https://github.com/ibm-rtvs/maven.

You must ensure that the following are available in a folder from where you can run the Maven commands:

The integration test project with the file extension as .ghp and opens in HCL OneTest™ API.
A JUnit integration test used to test a running stub.
POM files to run stubs or tests.

Procedure

Creating an Integration Tester project

Create an integration test project in HCL OneTest™ API.
See Task flow: Basic test scenario.
Run tests in HCL OneTest™ API. For information about JUnit tests, see Running tests.

Generating a POM file

Generate a POM file by using the HCL OneTest™ API UI.
See Generating Maven scripts to run stubs, tests, or suites.

Using the samples

Go to https://github.com/ibm-rtvs/maven and download the following folders and files to a folder in your system:
- Sample folder containing the HCL OneTest™ API project.
- src folder containing JUnit and Integration Tests.
- POM files
  - pom-stub-junit-test.xml
  - pom-stub-test.xml
  - pom-test.xml

What to do next

Communication with HCL Quality Server uses the HTTPS protocol. If the server certificate used by HCL Quality Server is not trusted by your system, Maven cannot connect and download files from HCL Quality Server. To enable Maven to use the Java installation you must add the certificate used by HCL Quality Server to the JDK trust store.

Adding HCL Quality Server certificate to JDK trust store

You must add the HCL Quality Server certificate to the JDK trust store so that Maven can download the Maven plug-ins from HCL Quality Server.

Before you begin

You must have verified whether HCL Quality Server is accessible.

About this task

You must first export the HCL Quality Server certificate by using the browser interface, and then add the exported certificate to the certificate in the JDK trust store.

Procedure

Exporting the HCL Quality Server certificate

Open a web browser and enter the address of the HCL Quality Server server you configured, in the format https://<server URL>:<Port>.
For example, if you have installed the HCL Quality Server in your local system, the address is https://localhost:5443.
The following steps are for the Chrome browser provided as an example of how you can export the certificate. For other browsers, you can use the relevant steps as provided by the browser documentation.
Click the View site information icon before the URL in the address bar of your browser.
In the dialog box that displays, complete the following steps:
1. Click Certificate.
2. Click the Details tab.
3. Click Copy to File.
4. Click Next to continue with the file export.
5. Select the encoding type and click Next.
6. Specify a file name and browse to a location on your system to save the exported file and then click Next.
7. Verify the details of the file displayed and click Finish.
  
  A message is displayed that the export was successful.
  
  For example, the exported certificate is saved as hqscert.cer. You can save a copy of the certificate file to the path %JAVA_HOME%\bin.

Importing the HCL Quality Server certificate

Determine the location of the cacerts file based on the JRE path (JAVA_HOME) that was set for Maven.
The path to the cacerts file is:
%JAVA_HOME%\lib\security\cacerts
In a Windows system, launch the command prompt as an administrator, and change the directory to point to the folder containing the JRE Keytool command tool.
For example, the commands used are:
C:\>cd %JAVA_HOME%\binC:\Program Files (x86)\Java\jre1.6.0_22\bin>

Note: You can run the keytool commands only from this directory.
To import the saved certificate hqscert.cer, run the following command:

keytool -importcert -alias "<saved_certificate.cer>" -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -file "%JAVA_HOME%\jre\lib\security\<saved_certificate.cer>"

Enter changeit when prompted for the password to change cacerts.

For example, substituting the saved certificate with its name, the command is:

keytool -importcert -alias "hqscert.cer" -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -file "%JAVA_HOME%\jre\lib\security\hqscert.cer"

Verifying certificate import

To verify that the HCL Quality Server certificate was added, run the following command:

keytool -list -keystore "%JAVA_HOME%\lib\security\cacerts"

Searching for the saved certificate name (hqscert.cer) in the displayed text and finding it implies that the certificate was added to the JDK trust store.

Results

You have added the HCL Quality Server certificate and enabled Maven to use the HCL Quality Server plug-in.

What to do next

You can run the Maven project commands. Optionally, you can edit the existing POM files in your Maven project to run the integration tests.

Modifying the POM files

You must modify the existing POM files in your Maven project to point to the integration test project and tests in HCL OneTest™ API. You need not modify the POM files if you are running your Maven project using the samples provided.

About this task

You can skip the steps in this task if you are using the sample project, tests, and POM files or if you have generated the POM file by using the HCL OneTest™ API UI.

Procedure

Adding HCL Quality Server URL

Add the following values to update the HCL Quality Server URL in the existing POM file or in the new POM files you want to use:
```
<repositories>
		<repository>
			<id>rtcp-site</id>
			<url>https://localhost:5443/maven2</url>
		</repository>
	</repositories>
	<pluginRepositories>
		<pluginRepository>
			<id>rtcp-site</id>
			<url>https://localhost:5443/maven2</url>
		</pluginRepository>
	</pluginRepositories>
```
Note: The above URL is valid if you have installed HCL Quality Server in your local system. If you have installed HCL Quality Server in a remote server, replace <localhost:5443> with the server URL and port details you configured.

The Maven integration feature in HCL Quality Server provides for a folder maven2 that is populated with the Maven plug-in files that are generated during the Maven project build. The Maven build files can be accessed by using a web browser on your Apache Maven system after a successful project build with the URL https://localhost:5443/maven2.

Updating environment and project details

Add the following values for the environment, integration test project file, and test run in the existing POM file or in the new POM files you want to use:

<configuration>
                    <properties>
                        <property>
                            <name>it_config_xml</name>
                            <value>
                                <![CDATA[
                                <projects processStartupTimeout="60">
                                    <project file="${user.home}/Getting Started 1/Getting Started 1.ghp" environment="IBM485-R8HDH4M" run="api/RTCP/examples/phonebook/api/queryPhonebook/queryPhonebookTest"/>
                                </projects>
                                ]]>
                            </value>
                        </property>

Edit the project file to the location of the integration test project that has the .ghp extension.

Edit the environment to the name of the environment you have created in HCL OneTest™ API.

Edit the run to the integration test run that you created in HCL OneTest™ API.

Modifying startup timeout

Edit and modify the default value of 60 seconds configured for the processStartupTimeout.
Modifying this value increases the timeout in seconds for the Maven build process to start before the build is aborted.

Running Maven commands

You can run Maven commands in your project build to perform integration tests by using HCL OneTest™ API and the Maven plug-in from HCL Quality Server.

Before you begin

You must have set up the project and tests in HCL OneTest™ API.
You must have generated the POM files from HCL OneTest™ API.
You must have imported the HCL Quality Server certificate into the JDK trust store.
If you have existing POM files that you use in your Maven build project, you must have modified the POM files to point to HCL OneTest™ API project and tests, and also point to the installed HCL Quality Server.

Procedure

Running Maven build

Run the following command to run the Maven build from the folder that contains the POM file and project files:

mvn verify -f <the-pom-file.xml>

Running this command performs the Maven build without any logging of the build.

Adding the trace logging to the build command

Run the following command to run the Maven build from the folder that contains the POM file and project files:

mvn verify -f <the-pom-file.xml> -X

Running this command performs the Maven build with Trace Logging to log the RunTests messages and other diagnostics.

Updating the version in the HCL Quality Server plug-in

Run the following command from the folder that contains the POM file and project files:

mvn versions:update-properties -Dincludes=com.hcl.products.test.it -f <POM_FILE>

If you are using POM files from earlier versions of HCL Quality Server or HCL OneTest™ API, you must update the versions for Maven to access the plug-ins. See Running POM files from earlier versions of HCL OneTest API.

Viewing Maven build results

You can view the generated failsafe-report.html report after Maven builds are run in the Maven created folder target\site.

Procedure

Navigate to the Maven folder that contains the POM file and project files. For example, ${USER_HOME}\bin.
Open target\site folder.
Open failsafe-report.html report to view the Maven build report.