Apama 10.15.0 | Connecting Apama Applications to External Components | Standard Connectivity Plug-ins | Codec Connectivity Plug-ins | The Unit Test Harness codec connectivity plug-in
 
The Unit Test Harness codec connectivity plug-in
The Unit Test Harness codec and the Null Transport transport make it easy to send test messages into a connectivity chain and/or to write out received messages to a text file, without the need to write any EPL in the correlator, which is very useful for writing unit tests for connectivity plug-ins, and especially codecs.
*Unit Test Harness. This is a Java codec that is useful for unit testing your plug-ins in isolation, by writing messages from the chain to a text file, and/or sending test messages into the chain from a text file (in either direction) without the need to use or configure the host or transport at either end of the chain.
*Null Transport. This is a trivial Java transport that does not send any messages towards the host and ignores any messages received from the host direction. If you are unit-testing a codec plug-in, no sending or receiving functionality is required for the transport. However, as a transport needs to exist at the end of a connectivity chain, you should use the Null Transport as the chain's transport.
The following example configuration shows the how the harness could be used for testing the behavior of a codec plug-in in the towards host direction, by sending test messages through the plug-in being tested and writing the messages from the plug-in out to a file:
connectivityPlugins:
unitTestHarness:
classpath: ${APAMA_HOME}/lib/connectivity-unit-test-harness.jar
class: com.softwareag.connectivity.testplugins.UnitTestHarness
nullTransport:
classpath: ${APAMA_HOME}/lib/connectivity-unit-test-harness.jar
class: com.softwareag.connectivity.testplugins.NullTransport
# plug-in being tested would also be defined here

startChains:
MyTestChain:
- apama.eventMap
# this is a unit test, so the host is not used

- unitTestHarness:
pluginUnderTest: towardsTransport
writeTo: output-towards-host.txt

- myCodecPluginBeingTested

- unitTestHarness:
pluginUnderTest: towardsHost
readFrom: ${TEST_INPUT_DIR}/input-towards-host.txt

- nullTransport
# this is a codec unit test, so no transport functionality is required
Apama ships an example of some PySys test cases using the Unit Test Harness codec as part of the JSON codec. You can find it in the samples\connectivity_plugin\java\JSON-Codec\tests directory of your Apama installation.
The following configuration options are available for the Unit Test Harness codec:
Configuration option
Description
pluginUnderTest
Required. Either towardsTransport or towardsHost, indicating which direction the plug-in being tested is along the chain relative to this unitTestHarness instance.
Messages from the readFrom file are sent down the chain towards the direction identified by pluginUnderTest, and messages received from that direction of the chain (that is, that were sent towards the opposite of the pluginUnderTest direction) are written to the writeTo file.
For example, a chain might have the host plug-in followed by a unitTestHarness with pluginUnderTest=towardsTransport followed by a codec plug-in that you are testing, followed by a unitTestHarness with pluginUnderTest=towardsHost followed by a nullTransport instance.
writeTo
The path of a UTF-8 text file to which messages from the plug-in under test are written.
If empty, no messages are written to a text file.
Default: empty.
readFrom
The path of a UTF-8 text file from which messages are read and sent towards the plug-in under test, or a directory containing such text files. When this plug-in is started, messages are read from the file and sent towards the plug-in under test. If a directory is specified, then the same is done for any new files in that directory, including any files that are subsequently written to that directory while the plug-in is running.
If empty, no messages are sent by the unitTestHarness.
Default: empty.
logOutput
By default, the unitTestHarness writes a single-line log message to the host's log file for each message from the plug-in under test, using the same format as writeTo. This may be useful as an alternative to writeTo, or as a way to create test cases that block until either the host log file contains the final expected message or an error message.
If you want to disable this behavior because the log file is becoming too large, then set this to false.
Default: true.
passThrough
By default, any messages received by the unitTestHarness are not passed on to the next plug-in in the chain (typically the transport or the host), as usually writing or logging the messages is all that is required and passing them on would require extra configuration in the host or transport to avoid error messages.
If you want to include the host or transport in your testing, then set this to true.
Default: false.
echoBack
If set to true, messages received from the plug-in under test are automatically sent back in the opposite direction towards the plug-in under test. This is useful for testing the round-trip mapping behavior of a codec plug-in.
Default: false.
The file format for readFrom and writeTo is identical, containing a metadata line followed by a payload line, repeating until the end of the file. Blank lines and lines starting with a hash (#) are ignored. The file encoding for both is always UTF-8 (which is the same as ASCII for the most common alphanumeric and punctuation characters).
A metadata line is encoded as a single-line JSON string. For example:
metadata={"aim":"purpose of this test message", "other stuff":[1, 2, 3]}
A payload line can use one of the following formats, depending on the type:
*Any message payload except for byte[] can be encoded using as a single-line JSON string. For example:
payload_json={"a\nb":123, "c":[true]}
There are some special JSON formats that can be used:
*JSON does not allow non-string keys. A special format of a JSON object with a ".Map" key and a value of a list of size 2 lists will be converted to a map. For example:
{".Map":[[123,"abc"],[987,"zyx"]]}
This would be converted to {123:"abc",987:"zyx"} if JSON allowed it. These may also be nested, for example:
{".Map":[[{".Map":[[333,"abc"],[555,"zyx"]]},"value"]]}
Any other keys in the ".Map" object will be ignored.
*A special format of a JSON map object with a ".NamedMap" key to a string value and a ".Map" key will create a NamedMap Java class which can be used with the EPL any type. For example:
{".NamedMap":"MyEvent",".Map":{"i":123}}
The contents of ".Map" will be named with the MyEvent name which can be used to determine the type of the converted any type variable. The ".Map" value may also use the special formatting above.
*Although JSON can be used to represent simple string payloads, it is sometimes simpler to use payload_string format for these as it removes the need to follow JSON quoting rules. For example:
payload_string=a " b
Note that the above can only be used if there are no new lines in the string. If there are new lines, use a JSON string instead. For example:
payload_json="my\nstring"
*For binary payloads (that is, a message whose payload is a byte array), use payload_byte[], which takes a base64-encoded representation of binary data. For example:
payload_byte[]=SGVsbG8gV29ybGQ=