Overview

The Kinetic Task test harness is a utility that allows you to test task handlers without importing them for use in workflow. This allows you to test handlers independently and make changes more swiftly.

Setup

Before you begin, ensure you have Java 1.7 or higher installed.

To set up the test harness, download kinetic-task.jar and make a note of where you placed it on your system (for example, "C:\testHarness").

Test Cases

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

• simple_input.rb
• simple_output.xml

These two files make up one test case.

To add another test case, create a folder for the test (you can name it whatever you like) and add the following files to the folder:

• input.rb
• output.xml

Input

The input.rb file configures the input for the test case. It contains a ruby hash that defines bindings referenced in the handler's node.xml. Each entry in the hash maps to another hash, which contains 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'
  }
}

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

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

<?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 an XML string compared to the XML string returned by the init.rb code is similar to the results portion found in the node.xml 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 the command prompt. Open a command prompt and navigate to the directory containing the handler you want to test. In the example below, the kinetic_sample_person_retrieve_v2 handler is being tested.

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

The following output indicates the tests passed:

The exception message and stack trace will be printed if the test fails due to an exception. The differences will be printed if the test fails because the results do not match the expected results.

If the handler fails because it does not match the expected results, the handler itself may not be the issue; it is possible that the results file was not set up properly.