Installing software

Before you begin working with the Rational® Integration Tester 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

  1. Install Java SE Development Kit (JDK) 6 or later, on the system where you intend to install Apache Maven and Rational® Integration Tester.
  2. 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.
  3. 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.
  4. Install Rational® Integration Tester Version 9.1.1.1 or later, on the system where you have installed JDK and Maven.
    See Installing.
  5. Install Rational® Test Control Panel Version 9.1.1.1 or later, on the system where you have installed Rational® Integration Tester or on a remote server.
    See Installing.
  6. Verify that the installed Rational® Test 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 Rational® Test Control Panel.
      For example, use https://localhost:5443 if you have installed it on your local system.
    3. The login page of Rational® Test Control Panel 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
  1. 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
  1. Configure an environment variable for one of the following variables:
    • INTEGRATION_TESTER_HOME to point to the installation location of Rational® Integration Tester. For example, set %INTEGRATION_TESTER_HOME% = C:\Program Files\IBM\RationalIntegrationTester.
    • INTEGRATION_TESTER_AGENT_HOME to point to the installation location of IBM® Rational® Integration Tester Agent. For example, set %INTEGRATION_TESTER_AGENT_HOME% = C:\Program Files\IBM\RIT-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 Rational® Integration Tester. 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 Rational® Integration Tester.
  • A JUnit integration test used to test a running stub.
  • POM files to run stubs or tests.

Procedure

Creating an Integration Tester project
  1. Create an integration test project in Rational® Integration Tester.
    See Task flow: Basic test scenario.
  2. Run tests in Rational® Integration Tester. For information about JUnit tests, see Running tests.
Generating a POM file
  1. Generate a POM file by using the Rational® Integration Tester UI.
    See Generating Maven scripts to run stubs, tests, or suites.
Using the samples
  1. 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 Rational® Integration Tester 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 Rational® Test Control Panel uses the HTTPS protocol. If the server certificate used by Rational® Test Control Panel is not trusted by your system, Maven cannot connect and download files from Rational® Test Control Panel. To enable Maven to use the Java installation you must add the certificate used by Rational® Test Control Panel to the JDK trust store.

Adding Rational® Test Control Panel certificate to JDK trust store

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

Before you begin

You must have verified whether Rational® Test Control Panel is accessible.

About this task

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

Procedure

Exporting the Rational® Test Control Panel certificate
  1. Open a web browser and enter the address of the Rational® Test Control Panel server you configured, in the format https://<server URL>:<Port>.
    For example, if you have installed the Rational® Test 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.

  2. 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 rtcpcert.cer. You can save a copy of the certificate file to the path %JAVA_HOME%\bin.

Importing the Rational® Test Control Panel certificate
  1. 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

  2. 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.
  3. To import the saved certificate rtcpcert.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 "rtcpcert.cer" -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -file "%JAVA_HOME%\jre\lib\security\rtcpcert.cer"

Verifying certificate import
  1. To verify that the Rational® Test Control Panel certificate was added, run the following command:

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

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

Results

You have added the Rational® Test Control Panel certificate and enabled Maven to use the Rational® Test Control Panel 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 Rational® Integration Tester. 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 Rational® Integration Tester UI.

Procedure

Adding Rational® Test Control Panel URL
  1. Add the following values to update the Rational® Test Control Panel 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 Rational® Test Control Panel in your local system. If you have installed Rational® Test Control Panel in a remote server, replace <localhost:5443> with the server URL and port details you configured.

    The Maven integration feature in Rational® Test 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
  1. 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 Rational® Integration Tester.

    Edit the run to the integration test run that you created in Rational® Integration Tester.

Modifying startup timeout
  1. 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 Rational® Integration Tester and the Maven plug-in from Rational® Test Control Panel.

Before you begin

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

Procedure

Running Maven build
  1. 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
  1. 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 Rational® Test Control Panel plug-in
  1. 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 Rational® Test Control Panel or Rational® Integration Tester, you must update the versions for Maven to access the plug-ins. See Running POM files from earlier versions of Rational Integration Tester.

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

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