WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Unit Test Space

A unit test space contains unit tests that are run by the XUnit test manager. Because the XUnit manager is external to the unit test space, all test resources described in this document must be publicly available.

Publishing Tests

A unit test space publishes its tests by exposing the resource res:/etc/system/Tests.xml. This resource provides a list of testlist resource identifiers. The structure of the Tests.xml must be:

<tests>
  <test />
  <test /> ...
</tests>

Where each test element identifies testlist using the following structure:

<test>
  <id>urn:test:com:mycomp:application:accounting:services</id>
  <name>Accounting Service tests</name>
  <desc>Tests of the accounting system</desc>
  <uri>res:/test/testlist.xml</uri>
</test>

where

  • id - is the system unique identifier used to reference this testlist.
  • name - is the human readable name of the testlist.
  • desc - is a short human readable description of the testlist.
  • uri - is the URI of the associated testlist resource within the unit test space.

By convention the address space used for unit tests starts with res:/test/. This fileset definition will publish the test address sub-space:

<fileset>
  <regex>res:/test/.*</regex>
</fileset>

Testlist Definition

A testlist contains a list of unit test definitions. When the group of tests defined by a testlist are executed by the XUnit test manager, they are executed in document order.

<testlist>
  <test />
  <test /> ...
</testlist>

If the unit tests in a testlist require external resources such as assert libraries, these may be imported with the import element which identifies the library:

<testlist>
  <import>res:/org/netkernel/xml/assert/assertLibrary.xml</import> ...
  <test />
  <test /> ...
</testlist>

It is also possible to use import to include further groups of tests into a testlist:

<testlist>
  <test />
  <test /> ...
  <import>res:/test/othertestlist.xml</import> ...
</testlist>

Test Definition

Each test in a testlist specifies an individual unit test. A unit test is simply a set of declarative requests where the outer element specifies the role it plays in the unit test ( setup, test request, assert, teardown):

<test name="optional human readable test name">
  <setup />
  <request />
  <assert />
  <teardown />
</test>

The XUnit test manager uses the name of each declarative request to determine when to issue the request according to this sequence of steps (possibly modified if exceptions are thrown):

  1. setup
  2. request
  3. assert (each assert check is requested individually in document order)
  4. teardown

Request

The test request element is the only required part of a unit test. It defines a resource request issued into the unit test space by the XUnit test manager.

Example

The following request definition

<request>
  <identifier>active:toUpper</identifier>
  <argument name="operand">res:/resources/text.txt</argument>
  <representation>java.lang.String</representation>
  <verb>SOURCE</verb>
</request>

will cause XUnit to issue a SOURCE request for active:toUpper with an argument named operand which identifies a resource to convert to capital letters and with a required representation class of java.lang.String.

Setup

A test setup declarative request is optional and specifies a resource request that is executed prior to the test request.

Example

The following setup declarative request will execute a Groovy language script prior to the execution of the unit test request:

<setup>
  <identifier>active:groovy</identifier>
  <argument name="operator">res:/test/setup1.gy</argument>
</setup>

Teardown

A test teardown declarative request is optional and specifies a resource request that is executed after the test request.

Example

The following teardown declarative request will execute a Groovy language script after the execution of the unit test request:

<teardown>
  <identifier>active:groovy</identifier>
  <argument name="operator">res:/test/teardown1.gy</argument>
</teardown>

Assert

An assertion is a boolean test run against the resource representation returned from a test request. For example, you may assert that the representation is an instance of the class java.lang.String or an instance of the class java.lang.Boolean with the value true.

A unit test is considered a success (it "passes") if the request runs and all assertion tests evaluate to true. The unit test framework will report the success or failure of each test, each group of tests and all published tests as a whole.

The assert element may contain zero or more specific assertions that are run, in document order, against the result returned from the test request.

For example the following assert specification will cause the XUnit test manager to first check to make sure the time taken to process the test request was less than 20 milliseconds and then checks to make sure the returned representation is a Boolean with the value true:

<assert>
  <maxTime>20</maxTime>
  <true />
</assert>

If any assertion fails then the unit test fails and XUnit test management tool reports the failure in its report. Available assertions include built-in assertions, custom assertions (included in the testlist) as well as imported assert libraries.

Associating Tests with a Module

It is often useful to be able indicate that a collection of tests are intended to test a specific module (or modules).

This can be done by simply declaring the module associations in the declaration like this...

<testlist>
  < !--Associate this testlist with the following modules-->
  <module>
    <uri>urn:org:netkernel:app:foo</uri>
    <uri>urn:org:netkernel:app:baa</uri>
  </module> ...Your tests go here...
</testlist>

The value of declaring a module association is that when you view a module in the space explorer, the context menu for a module offers "Execute Tests..." which will take you to XUnit with the associated tests for that module filtered out and ready to execute.

Example Test Lists

Here is a test list that performs two tests: a simple source test on a resource and an invocation of a script engine.

<testlist>
  <module>
    <uri>urn:com:mycompany:project:module</uri>
  </module>
  <test name="Simple Test to Source myScript.gy">
    <request>
      <verb>SOURCE</verb>
      <identifier>res:/myScript.gy</identifier>
    </request>
  </test>
  <test name="Test to execute script myScript.gy with test 'operand' myTestData.txt">
    <request>
      <verb>SOURCE</verb>
      <identifier>active:groovy</identifier>
      <argument name="operator">res:/myScript.gy</argument>
      <argument name="operand">res:/myTestData.txt</argument>
    </request>
    <assert>
      <maxTime>20</maxTime>
    </assert>
  </test>
</testlist>