Unit Module

This XQuery Module contains functions for running XQUnit annotated functions in XQuery modules.

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, automatized way for testing software. The XUnit frameworks (such as SUnit or JUnit) allow testing of atomic unit of a program, such as single functions and algorithms.

XQUnit borrows heavily from the existing frameworks: it introduces various new annotations for testing XQuery functions. XQUnit 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.

Please note that this module is still in beta stage, and its functionality is still subject to change. Your feedback is welcome.

Conventions

Both functions and errors in this module are assigned to the http://basex.org/modules/xqunit namespace, which is statically bound to the xqunit prefix.

Annotations

%xqunit:test

Syntax	%xqunit:test
Summary	With this annotation, a function can be marked a XQUnit test. It will be evaluated whenever a test report is created for the module in which this function is located.

%xqunit:before

Syntax	%xqunit:before
Summary	A function decorated with this annotation will be evaluated before each XQUnit test.

%xqunit:after

Syntax	%xqunit:after
Summary	A function decorated with this annotation will be evaluated after each XQUnit test.

%xqunit:before-module

Syntax	%xqunit:before-module
Summary	If a function is decorated with this annotation, it will be evaluated before all XQUnit tests in the current module.

%xqunit:after-module

Syntax	%xqunit:after-module
Summary	If a function is decorated with this annotation, it will be evaluated after all XQUnit tests in the current module.

Functions

xqunit:assert

Signatures	xqunit:assert($test as item()*) as empty-sequence() xqunit:assert($test as item()*, $message as xs:string) as empty-sequence()
Summary	Asserts that the effective boolean value of the specified $test is true and returns an empty sequence. Otherwise, raises an error. If the optional error $message can be specified as second argument.
Errors	XQUNIT0001: the assertion failed. XQUNIT0002: the evaluated code raised an XQuery error.

xqunit:fail

Signatures	xqunit:fail($message as xs:string) as empty-sequence()
Summary	Raises an XQUnit error with the specified message.
Errors	XQUNIT0001: default error raised by this function.

xqunit:test

Signatures	xqunit:test() as element(testsuite)*
Summary	Runs all functions in the current module that are annotated with xqunit annotations. A test report is generated and returned, which resembles the format returned by other xUnit testing frameworks, such as the Maven Surefire Plugin.
Errors	XQUNIT0003: a test function must have no arguments. XQUNIT0004: a test function must not be updating. XQUNIT0005: an annotation was declared twice. XQUNIT0006: an annotation has invalid arguments.

xqunit:test-libraries

Signatures	xqunit:test-libraries($uris as xs:string*) as element(testsuites)
Summary	Runs all functions in the specified modules that are annotated with xqunit annotations. A test report is generated and returned, which resembles the format returned by other xUnit testing frameworks, such as the Maven Surefire Plugin.
Errors	XQUNIT0003: a test function must have no arguments. XQUNIT0004: a test function must not be updating. XQUNIT0005: an annotation was declared twice. XQUNIT0006: an annotation has invalid arguments.

Errors

Code	Description
XQUNIT0001	An assertion failed, or xqunit:fail was called.
XQUNIT0002	An error was raised within an XQUnit test function.
XQUNIT0003	A test function must have no arguments.
XQUNIT0004	A test function must not be updating.
XQUNIT0005	An annotation was declared twice.
XQUNIT0006	An annotation has invalid arguments.

Changelog

This module was introduced with Version 7.7.