<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY UTE "GTEE">
]>

<sect1 id="ute_harness_interface">
  <title>Harness interface</title>
  <sect2 id="ute_harness_interface_overview">
    <title>Overview</title>
    <para>
      Harness interface is a convention between UTE and a harness module.
    </para>
    <para>
      Harness module is parsable shell script <code>$UTE_HOME/harness/$harness</code> (where
      <code>$harness</code> is the harness module identifier). This shell script must define a number of
      shell functions, some of which are mandatory and others are optional. These functions are called by UTE
      during harness module lifecycle to perform particular task (refer to <xref linkend="ute_harness_module_functions"/>).
      Harness module may use additional tools which are placed under <code>$UTE_HOME/tool/$tool/</code> (where
      <code>tool</code> is the tool identifier) and data files which are placed under <code>$UTE_HOME/data/.</code>
    </para>
    <para>
      UTE immediately fails if any command exits with non-zero status (except test harness, the exit code
      of which is processed). It means that harness module must be written to process expected non-zero exit
      codes. Additionally, it is recommended to validate any settings before usage to avoid starting testrun with
      wrong settings.
    </para>
    <para>
       Harness module functions are expected to use a number of internal variables set by UTE. Refer
       to <xref linkend="ute_internal_variables_table"/> for list of these variables. Additionally, harness module may expect
       user to define a number of additional settings, in which case, it should validate them before
       execution.
    </para>
    <para>
      Additionally, UTE defines a number of utility functions which are recommended to be used by harness modules
      (refer to <xref linkend="ute_utility_functions"/>).
    </para>
  </sect2>
  <sect2 id="ute_harness_module_functions">
    <title>Harness module functions</title>
      <para>
        By convention, all harness module functions are prefixed with the identifier of harness module.
      </para>
      <para>
        The following table provides the list of functions. For particular harness module,
	<code>harness</code> is expected to be replaced with harness module identifier.
        <table pgwide="1" id="ute_harness_module_functions_table">
          <title>Harness module functions</title>
          <tgroup align="left" valign="top" cols="3">
            <colspec align="left" valign="top" name="Name"/>
            <colspec align="left" valign="top" name="Mandatory"/>
            <colspec align="left" valign="top" name="Description"/>
            <thead>
              <row>
                <entry>Name</entry>
                <entry>Mandatory</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>harness_setup</entry>
                <entry>yes</entry>
                <entry>Testrun preparation</entry>
              </row>
              <row>
                <entry>harness_run</entry>
                <entry>yes</entry>
                <entry>Testrun execution</entry>
              </row>
              <row>
                <entry>harness_initialize</entry>
                <entry>no</entry>
                <entry>Harness module initialization (called early before and before <code>harness_setup)</code>)</entry>
              </row>
              <row>
                <entry>harness_postprocess</entry>
                <entry></entry>
                <entry>Harness module cleanup (called late after <code>harness_run</code>)</entry>
              </row>
              <row>
                <entry></entry>
                <entry></entry>
                <entry></entry>
              </row>
              <row>
                <entry></entry>
                <entry></entry>
                <entry></entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </para>
  </sect2>
  <sect2 id="ute_variables">
    <title>Variables</title>
      <para>
        Several kinds of variables are accessible to harness module:
	<itemizedlist>
	  <listitem>Settings provided by user</listitem>
	  <listitem>Auxiliary variables set by UTE</listitem>
	  <listitem>Auxiliary variables set by harness module itself</listitem>
	</itemizedlist>
      </para>
      <para>
        Some of user settings are mandatory and validated by UTE, thus
	there is no need for harness module to validate them. In addition, UTE defines
	or calculates a number of internal variables which are then used by harness module.
	Note that these variables allow for flexible test configuration and their usage
	is mandatory for harness module.
      </para>
      <para>
        There may be harness module-specific settings (mandatory or optional).  There are no constrains
	or limitations on these settings, although there are several recommendations:
	<itemizedlist>
	  <listitem>
	    The number of mandatory settings should be kept to minimum to simplify user experience.
	  </listitem>
	  <listitem>
	    At the same time, it is recommended to allow for flexible reconfiguration of testrun
	    (ideally as flexible as test harness capabilities). Last two items together mean that testrun
	    configuration is defined by a number of parameters, most of which have sensible default value.
	  </listitem>
	  <listitem>
            All settings should always be validated during <code>harness_setup</code> or
	    <code>harness_initialize</code> steps. In most cases, one of validation functions 
	    should be used (refer to <xref linkend="ute_utility_functions"/>).
	  </listitem>
	</itemizedlist>
      </para>
      <para>
        Refer to <xref linkend="ute_harness_modules_common"/> for list of settings provided by user.
      </para>
      <para>
        The following table provides the list of internal UTE variables.
        <table pgwide="1" id="ute_internal_variables_table">
          <title>Harness internal variables</title>
          <tgroup align="left" valign="top" cols="3">
            <colspec align="left" valign="top" name="Name"/>
            <colspec align="left" valign="top" name="Command line option"/>
            <colspec align="left" valign="top" name="Set by"/>
            <colspec align="left" valign="top" name="Default value"/>
            <colspec align="left" valign="top" name="Description"/>
            <thead>
              <row>
                <entry>Name</entry>
                <entry>Command line option</entry>
                <entry>Set by</entry>
                <entry>Default value</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>UTE_HOME</entry>
                <entry>-</entry>
                <entry>UTE</entry>
                <entry>-</entry>
                <entry>UTE location</entry>
              </row>
              <row>
	        <entry>PLATFORM</entry>
	        <entry>-</entry>
	        <entry>UTE</entry>
	        <entry>-</entry>
	        <entry>Machine platform (e.g. solaris-sparc, linux-amd64, windows-i586) </entry>
              </row>
              <row>
	        <entry>JDK_ARCH</entry>
	        <entry>-</entry>
	        <entry>UTE</entry>
	        <entry></entry>
	        <entry>Product architecture (e.g. solaris-sparc, linux-amd64, windows-i586)</entry>
              </row>
              <row>
	        <entry>PS</entry>
	        <entry>-</entry>
	        <entry>UTE</entry>
	        <entry></entry>
	        <entry>Path component separator (':'/';')</entry>
              </row>
              <row>
                <entry>TEST_JAVA</entry>
                <entry>-</entry>
                <entry>UTE</entry>
                <entry></entry>
                <entry>Full path to java binary (from TEST_JAVA_HOME and JAVA_EXE)</entry>
              </row>
              <row>
                <entry>VM_OPTS_ALL</entry>
                <entry>-</entry>
                <entry>UTE</entry>
                <entry></entry>
                <entry>All product options</entry>
              </row>
              <row>
                <entry>STABLE_JAVA</entry>
                <entry>-</entry>
                <entry>UTE</entry>
                <entry></entry>
                <entry>Full path to stable java binary</entry>
              </row>
              <row>
                <entry></entry>
                <entry></entry>
                <entry></entry>
                <entry></entry>
                <entry></entry>
              </row>
              <row>
                <entry></entry>
                <entry></entry>
                <entry></entry>
                <entry></entry>
                <entry></entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </para>
  </sect2>
  <sect2 id="ute_utility_functions">
    <title>Utility and validation functions</title>
    <para>
      Note: all validation functions immediately fail (and cause UTE to fail with non-zero exit code) if validation fails.
    </para>
    <para>
      The following table provides the list of supported utility and validation functions:
        <table pgwide="1" id="ute_utility_functions_table">
          <title>Utility functions</title>
          <tgroup align="left" valign="top" cols="3">
            <colspec align="left" valign="top" name="Usage"/>
            <colspec align="left" valign="top" name="Description"/>
            <thead>
              <row>
                <entry>Usage</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row><entry><literallayout><code>info "message",
		debug "message",
		warn "message",
		error "message</code></literallayout></entry>
                <entry>Log message at corresponding log level</entry>
              </row>
              <row>
                <entry><code>fail "message"</code></entry>
                <entry>Fail current function with given message</entry>
              </row>
              <row>
                <entry><literallayout><code>ivar_set "name" "value"
		ivar_get "name"</code></literallayout></entry>
                <entry>Set or get variable with given name (indirectly)</entry>
              </row>
	      <row>
	        <entry><code>harness_run command arg ...</code></entry>
		<entry>Run harness with given arguments</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>process_start id command arg ...
		process_stop id</code></literallayout></entry>
		<entry>Start or stop background process with given command line</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>set_default_var name value</code></literallayout></entry>
		<entry>Set value of variable <code>name</code> to <code>value</code> if it has not been set yet (by user)</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>check_not_empty name</code></literallayout></entry>
		<entry>Check that variable with name <code>name</code> is set (has non-empty value)</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>check_dir dir</code></literallayout></entry>
		<entry>Check that <code>dir</code> is existing directory</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>check_dir_var name</code></literallayout></entry>
		<entry>Check that variable <code>name</code> contains an existing directory</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>check_file filename</code></literallayout></entry>
		<entry>Check that <code>filename</code> is an existing file</entry>
	      </row>
	      <row>
	        <entry><literallayout><code>check_file_var name</code></literallayout></entry>
		<entry>Check that variable <code>name</code> contains an existing file</entry>
	      </row>
           </tbody>
          </tgroup>
        </table>
    </para>
  </sect2>
</sect1>
