Installing the Server Unit Test Harness

Unlike MettleCI’s Parallel Unit Test Harness, which is installed once for an entire DataStage Engine tier, the architecture of DataStage’s Server Engine requires the MettleCI Server Unit Test Harness to be installed and enabled individually for each Project in which you want to test Server jobs. To do this, follow the instructions below.

If you are IBM OEM Customer, you must upgrade to MettleCI v1.3 (or newer) to be able to execute the instructions on this page.

Prerequisites

You have performed the Unit Test Harness installation steps for Parallel Jobs on the relevant DataStage Engine host and you have successfully created and executed at least one Unit Test for a Parallel job (any Job in any Project)..
You have a working installation of the MettleCI CLI (version 1.1-218 or above) on either your DataStage Engine or DataStage Client host.
In your MettleCI CLI plugins directory, you have the dm-dstest-plugin-x.x-xxx.jar plugin file, where x.x-xxx is greater than, or equal to 1.0-533.

A default credential mapping has been set for your DataStage Engine. Refer to this FAQ page for completing this step when your DataStage engine is configured to use shared user credentials.

Default credential mapping is not the same as setting a specific user’s credential mapping. The latter won’t fulfill the runtime prerequisites of the Server Job Unit Test Harness.

Installation Steps

Only perform these steps if your DataStage solution uses Server Jobs. They must be repeated for each DataStage project where Server job unit testing is required.

Run the unittest install-server-test-harness MettleCI CLI command with the necessary arguments.

Example command with arguments:

CODE

mettleci unittest install-server-test-harness 
    -domain my-svcs.datamigrators.io:9443
    -server my-engn.datamigrators.io 
    -project dstage1 
    -username isadmin 
    -password mypassword

When running this MettleCI CLI command on a host where a DataStage Client has been installed, it will automatically run IBM’s DSStageTypeUpdater utility after installing the Server Unit Test Harness.

If the Windows User Account Control prompt appears, click “Yes” to allow DSStageTypeUpdater.exe to allow the necessary changes to be made.

Wait for DSStageTypeUpdater to complete

Use the linked IBM instructions to apply the following two environment variables for the whole DataStage instance or per Project, replacing values between < > with values specific to your installation. If you need to perform Server Job unit testing across multiple Projects, we recommend setting these variables at the instance level to avoid the additional administration overhead and risk of accidental configuration gaps.

CODE

DM_UNIT_TESTING_JAR=<DataStage install directory>/Server/DSComponents/bin/dm-unittest-harness-<x.x-xxx>.jar
DM_METTLE_HOME=<MettleCI home location>

Post-installation Steps

To enable MettleCI Unit Testing for an existing DataStage project:

Log into your development DataStage Engine(s) and navigate to your DataStage project folder. On *nix hosts, this path is usually as follows:
CODE
```
/opt/IBM/InformationServer/Server/Projects/<Your Existing Project>
```

Add the following Environment variable definition to the DSParams file under the [EnvVarDefns] section:

CODE

DM_ENABLE_UNIT_TESTING\MettleCI\-1\List/Disabled//Test//Intercept/\Disabled\3\Project\Unit Testing Configuration\

This will make the following Environment Variable available to add to the DataStage jobs for which you wish to enable unit testing:

Enable MettleCI Unit Testing by default on Project creation:

Add the same entry described above to the DSParams file for your ‘Template’ project. On *nix hosts, the default path to the parent folder of that DSParams file is as follows:
CODE
```
/opt/IBM/InformationServer/Server/Template
```

Troubleshooting

If your Server Job execution hangs

After deploying Server Job Unit Testing you might experience a situation in which a Server job hangs in a ‘running’ state when executing a Unit Test. To address this you will need to run the following command on your a DataStage Client host to update DataStage’s understanding of available Stage types.

CODE

<Datastage-Root-Folder>/IBM/InformationServer/Clients/Classic/DSStageTypeUpdater.exe

DSStageTypeUpdater.exe needs to be run on a project by project basis. For instance, if you have 10 projects, you will need to run it 10 times, once per project. For more details, refer to https://www-01.ibm.com/support/docview.wss?uid=swg21498616

Changing the level of Unit Test log messages

Enabling Unit Testing will set the log type to “Warning” for Job log entries generated by this MettleCI feature. This is to help remind developers to switch the Unit Testing mode off before deploying Jobs to Production. If you want to apply a different setting for Unit Testing log entries, you can override the default by adding a new environment variable DM_LOG_UNITTEST_LEVEL with value of INFO to the dsenv file. For example:

BASH

# Data Migrators Set Enable Unit Testing as INFO (default is Warning)
DM_LOG_UNITTEST_LEVEL=INFO
export DM_LOG_UNITTEST_LEVEL

Uninstall the Server Job Unit Test Harness

Only perform these steps if your Server Jobs Unit Test Harness was previously enabled for the specific Project you are working on. They must be repeated for each DataStage project for which Server unit testing was enabled.

Run the unittest uninstall-server-test-harness MettleCI CLI command with the necessary arguments.
Example command on Unix with arguments:

CODE

./mettleci unittest uninstall-server-test-harness 
    -domain my-svcs.datamigrators.io:9443
    -server my-engn.datamigrators.io 
    -project dstage1 
    -username isadmin 
    -password mypassword

Test whether the uninstallation has succeeded by…
- identifying a Server job that previously had a working Unit Test
- running the Job with the DM_ENABLE_UNIT_TESTING variable set to “Test”; then
- confirming that the resulting Job execution log doesn't contain any of the usual Unit Test Harness-generated status and result entries.