Unit Module

This XQuery Module contains annotations and functions for performing XQUnit tests.

=Introduction=

The more complex a software application grows, the more error-prone it gets. This is why testing frameworks have been developed, which provide a standardized, automated way of testing software. The XUnit frameworks (such as SUnit or JUnit) allow testing of atomic units of a program, such as single functions and algorithms.

This module borrows heavily from the existing frameworks: it provides various annotations for testing XQuery functions. Unit functions are provided to assert the validity of arbitrary conditions expressed in XQuery and to raise errors whenever a condition is not satisfied. Some additional functions exist to run all unit tests of the current module or a set of specified library modules.

=Usage=

Tests are started via the TEST command. It compiles all XQuery modules in a given file or directory and runs all functions that are annotated with %unit:test. A test report is generated and returned, which resembles the format returned by other xUnit testing frameworks, such as the Maven Surefire Plugin (see below).

=Conventions=

All annotations, functions and errors in this module are assigned to the  namespace, which is statically bound to the unit prefix.

=Annotations=

%unit:ignore
=Functions=

unit:fail
=Example=

The following XQUnit module tests.xqm contains all available unit annotations:

Query
 module namespace test = 'http://basex.org/modules/xqunit-tests';

(:~ Initializing function, which is called once before all tests. :) declare %unit:before-module function test:before-all-tests { }; (:~ Initializing function, which is called once after all tests. :) declare %unit:after-module function test:after-all-tests { }; (:~ Initializing function, which is called before each test. :) declare %unit:before function test:before { }; (:~ Initializing function, which is called after each test. :) declare %unit:after function test:after { }; (:~ Function demonstrating a successful test. :) declare %unit:test function test:assert-success { unit:assert() }; (:~ Function demonstrating a failure using unit:assert. :) declare %unit:test function test:assert-failure { unit:assert(, 'Empty sequence.') }; (:~ Function demonstrating a failure using unit:assert-equals. :) declare %unit:test function test:assert-equals-failure { unit:assert-equals(4 + 5, 6) }; (:~ Function demonstrating an unexpected success. :) declare %unit:test("expected", "err:FORG0001") function test:unexpected-success { }; (:~ Function demonstrating an expected failure. :) declare %unit:test("expected", "err:FORG0001") function test:expected-failure { 1 +  }; (:~ Function demonstrating the creation of a failure. :) declare %unit:test function test:failure { unit:fail("Failure!") }; (:~ Function demonstrating an error. :) declare %unit:test function test:error { 1 +  }; (:~ Skipping a test. :) declare %unit:test %unit:ignore("Skipped!") function test:skipped { };

By running TEST tests.xqm, the following report will be generated (timings may differ):

Result
      Empty sequence.   9 6 Item 1: 6 expected, 9 returned.  FORG0001  <testcase name="failure" time="PT0.004S"> <failure line="50" column="13"> Failure! <testcase name="error" time="PT0.004S"> <error line="55" column="6" type="FORG0001"> Cannot cast to xs:double: "". <testcase name="skipped" skipped="Skipped!" time="PT0S"/>

=Errors=

=Changelog=


 * Version 9.0


 * Updated: error codes updated; errors now use the module namespace


 * Version 8.0.2


 * Updated: (expected) errors are compared by QNames instead of local names (including namespaces).


 * Version 8.0


 * Deleted: UNIT0006 (ignore results returned by functions).
 * Added: unit:fail, 0-argument signature.
 * Updated: the info argument of functions can now be an arbitrary item.
 * Updated: infos are now represented in an  child element.
 * Updated: unit:before and unit:after can be extended by a filter argument.


 * Version 7.9


 * Added: TEST command
 * Removed: unit:test, unit:test-uris


 * Version 7.8


 * Added: unit:assert-equals
 * Updated: enhanced test report output

This module was introduced with Version 7.7.