Installing software

Before you begin working with the IBM® DevOps Test Integrations and APIs (Test Integrations and APIs) project in your Maven build, you must complete installing the requisite software.

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

Install Java SE Development Kit (JDK) 6 or later, on the system where you intend to install Apache Maven and Test Integrations and APIs.
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 Test Integrations and APIs Version 9.1.1.1 or later, on the system where you have installed JDK and Maven.
Install Test Virtualization Control Panel Version 9.1.1.1 or later, on the system where you have installed Test Integrations and APIs or on a remote server.
Verify that the installed Test Virtualization Control Panel 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 Test Virtualization Control Panel.
  For example, use https://localhost:5443 if you have installed it on your local computer.
3. The login page of Test Virtualization Control Panel must display.

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, if it is not done already.

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

Note:

In Test Integrations and APIs 10.2.2 or later, the environment variables INTEGRATION_TESTER_HOME and INTEGRATION_TESTER_AGENT_HOME are automatically created at the time of installing the product software.

Configure an environment variable for one of the following variables:
- INTEGRATION_TESTER_HOME to point to the installation location of Test Integrations and APIs. For example, set %INTEGRATION_TESTER_HOME% = C:\Program Files\IBM\DevOpsTestAPI.
- INTEGRATION_TESTER_AGENT_HOME to point to the installation location of Test Integrations and APIs Agent. For example, set %INTEGRATION_TESTER_AGENT_HOME% = C:\Program Files\IBM\DevOpsTestAPI.

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.

You must set up your own project resources that you want to test by using Test Integrations and APIs. 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 Test Integrations and APIs.
A JUnit integration test used to test a running stub.
POM files to run stubs or tests.

Creating an Integration Tester project

Create an integration test project in Test Integrations and APIs.
See Task flow: Basic test scenario.
Run tests in Test Integrations and APIs. For information about JUnit tests, see Running tests.

Generating a POM file

Generate a POM file by using the Test Integrations and APIs 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 Test Integrations and APIs project.
- src folder containing JUnit and Integration Tests.
- POM files
  - pom-stub-junit-test.xml
  - pom-stub-test.xml
  - pom-test.xml

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

Adding Test Virtualization Control Panel certificate to JDK trust store

You must add the Test Virtualization Control Panel certificate to the JDK trust store so that Maven can download the Maven plug-ins from Test Virtualization Control Panel.

You must have verified whether Test Virtualization Control Panel is accessible.

You must first export the Test Virtualization Control Panel certificate by using the browser interface, and then add the exported certificate to the certificate in the JDK trust store.

Exporting the Test Virtualization Control Panel certificate

Open a web browser and enter the address of the Test Virtualization Control Panel server you configured, in the format https://<server URL>:<Port>.
For example, if you have installed the Test Virtualization Control Panel 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 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 dtcpcert.cer. You can save a copy of the certificate file to the path %JAVA_HOME%\bin.

Importing the Test Virtualization Control Panel 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%\bin

C:\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 dtcpcert.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 "dtcpcert.cer" -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -file "%JAVA_HOME%\jre\lib\security\dtcpcert.cer"

Verifying certificate import

To verify that the Test Virtualization Control Panel certificate was added, run the following command:

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

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

You have added the Test Virtualization Control Panel certificate and enabled Maven to use the Test Virtualization Control Panel plug-in.

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 Test Integrations and APIs. You need not modify the POM files if you are running your Maven project using the samples provided.

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 Test Integrations and APIs UI.

Adding Test Virtualization Control Panel URL

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

The Maven integration feature in Test Virtualization Control Panel 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 Test Integrations and APIs.

Edit the run to the integration test run that you created in Test Integrations and APIs.

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 Test Integrations and APIs and the Maven plug-in from Test Virtualization Control Panel.

You must have set up the project and tests in Test Integrations and APIs.
You must have generated the POM files from Test Integrations and APIs.
You must have imported the Test Virtualization Control Panel 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 Test Integrations and APIs project and tests, and also point to the installed Test Virtualization Control Panel.

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 Test Virtualization Control Panel 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 Test Virtualization Control Panel or Test Integrations and APIs, you must update the versions for Maven to access the plug-ins. See Running POM files from earlier versions of DevOps Test Integrations and APIs.

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.

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.