How to Use the Task Test Harness

The Test Harness is a utility that allows you to test task handlers without importing them for use in workflow. This way handlers can be tested independently and changes can be made more swiftly.

Setup

Download the kinetic-task.jar and place it anywhere you like on your system. For reference, I placed it in the following directory:
C:\testHarness.

Prerequisites: Requires Java 1.7 or higher.

Note - This test harness should be used to test handlers that will be used with Kinetic Task 4.x.

Test Cases

Test cases are configured by placing files within the test directory of the handler package. Most handlers will always include at least the two following files:

  • simple_input.rb
  • simple_output.xml
    These two files make up one test case. To add another test case we would add two files named <test_name>_input.rb and <test_name>_output.xml where test_name can be anything it just needs to match for both files.

Input

The input.rb file configures the input for the test case. It simply contains a ruby hash that defines bindings referenced in the node.xml of the handler. Note that each entry in the hash maps to another hash which contains our input values for the test case.

{
  'info' => {
    'server'   => 'matrix.kineticdata.com',
    'username' => 'Demo',
    'password' => '',
    'port'     => '',
    'prognum'  => '0',
    'authentication' => ''
  },
  'parameters' => {
    'search_by'    => 'AR Login',
    'search_value' => 'demo'
  }
}

Below is the node.xml for the handler I am using in this example. The bindings used in the node.xml are highlighted. Bindings are referenced by first using the @ syntax to reference a type of binding, then within the [] we reference the specific value. For example @info['username'] references the username info binding.

In the input.rb the keys of the outer hash are the types of bindings, "info" and "parameters" for example. The keys of the inner hashes are the names of the values, "username" and "search_value" for example.

<?xml version="1.0" encoding="UTF-8"?>
<taskDefinition id="kinetic_sample_people_retrieve" name="Kinetic Sample People Retrieve" schema_version="1.0" version="2">
    <author>[email protected]</author>
    <description>
        Retrieves specific fields from a single entry in the KS_SAMPLE_People form.
        The record is retrieved by using the Search By and Search Value parameters
        to build a qualification.
    </description>
    <helpurl>http://ktc.kineticdata.com/handler/kinetic_sample_people_retrieve/2</helpurl>
    <visible>true</visible>
    <deferrable>false</deferrable>
    <parameters>
        <parameter id="search_by" label="Search By" required="true"
            menu="Entry Id,Email Address,AR Login,Instance Id"
            tooltip="The Search By parameter has 4 options, and configures which field the handler will use in its search qualification" />
        <parameter id="search_value" label="Search Value" required="true"
            tooltip="The Search Value parameter is the value of the Search By field on the record  that will be retrieved" />
    </parameters>
    <handler name="kinetic_sample_people_retrieve" version="2">
        <infos>
            <info name="server">&lt;%= @info['server'] %&gt;</info>
            <info name="username">&lt;%= @info['username'] %&gt;</info>
            <info name="password">&lt;%= @info['password'] %&gt;</info>
            <info name="port">&lt;%= @info['port'] %&gt;</info>
            <info name="prognum">&lt;%= @info['prognum'] %&gt;</info>
            <info name="authentication">&lt;%= @info['authentication'] %&gt;</info>
        </infos>
        <parameters>
            <parameter name="search_by" description="search by">&lt;%= @parameters['search_by'] %&gt;</parameter>
            <parameter name="search_value" description="search value">&lt;%= @parameters['search_value'] %&gt;</parameter>
        </parameters>
    </handler>
    <results format="xml">
        <result name="First Name" />
        <result name="Last Name" />
        <result name="AR Login" />
    </results>
</taskDefinition>

Output

The output.xml file configures the expected output for the test case. It is simply an XML string to be compared to the XML string that is returned by the init.rb code. Note that this is very similar to the results portion found in the node.xml shown above.

<results>
    <result name="First Name">Don</result>
    <result name="Last Name">Demo</result>
    <result name="AR Login">demo</result>
</results>

Running the Test Harness

The kinetic-task.jar is executed via command prompt. Open a command prompt and navigate to the directory that contains the handler you would like to test (I am testing the kinetic_sample_person_retrieve_v2 handler in this example). Run the command shown below.

java -jar C:\testHarness\kinetic-task.jar -test-handler=kinetic_sample_person_retrieve_v1

The output will look like this if the tests passed.

output

If the test fails due to an exception the exception message and stack trace will be printed. If the test fails because the actual results do not match the expected results, the differences will be printed. Note that if the handler fails because it did not match the expected results, it might not be that the handler actually failed. It could mean that the expected results file was not prepared/set up properly.