Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
XQUnit This module borrows heavily from the existing frameworks: it introduces various new annotations for testing XQuery functions. XQUnit 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.
xqunitunit:assert(1 + 2 = 3)
xqunitunit:assert(4 + 5 = 6)
xqunitunit:test()
no edit summary
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 [http://en.wikipedia.org/wiki/XUnit XUnit] frameworks (such as SUnit or JUnit) allow testing of atomic unit of a program, such as single functions and algorithms.
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 {{Code|http://basex.org/modules/xqunitunit}} namespace, which is statically bound to the {{Code|xqunitunit}} prefix.<br/>
=Annotations=
==%xqunitunit:test==
{| width='100%'
|-
| width='90' | '''Syntax'''
|{{Code|%xqunitunit:test}}<br/>{{Code|%xqunitunit:test("expected", <ERROR>)}}
|-
| '''Summary'''
|With this annotation, a function can be marked as '''XQUnit unit test'''. It will be evaluated whenever a test report is created for the module in which this function is located.<br/>If an optional error code is specified and if the function expression does not raise that error, the test will fail.
|}
==%xqunitunit:before==
{| width='100%'
|-
| width='90' | '''Syntax'''
|{{Code|%xqunitunit:before}}
|-
| '''Summary'''
|A function decorated with this annotation will be evaluated '''before each''' XQUnit unit test.
|}
==%xqunitunit:after==
{| width='100%'
|-
| width='90' | '''Syntax'''
|{{Code|%xqunitunit:after}}
|-
| '''Summary'''
|A function decorated with this annotation will be evaluated '''after each''' XQUnit unit test.
|}
==%xqunitunit:before-module==
{| width='100%'
|-
| width='90' | '''Syntax'''
|{{Code|%xqunitunit:before-module}}
|-
| '''Summary'''
|If a function is decorated with this annotation, it will be evaluated '''before all''' XQUnit unit tests in the current module.
|}
==%xqunitunit:after-module==
{| width='100%'
|-
| width='90' | '''Syntax'''
|{{Code|%xqunitunit:after-module}}
|-
| '''Summary'''
|If a function is decorated with this annotation, it will be evaluated '''after all''' XQUnit unit tests in the current module.
|}
==%xqunitunit:ignore==
{| width='100%'
|-
| width='90' | '''Syntax'''
|{{Code|%xqunitunit:ignore}}<br/>{{Code|%xqunitunit:ignore("message")}}
|-
| '''Summary'''
=Functions=
==xqunitunit:assert==
{| width='100%'
|-
| width='90' | '''Signatures'''
|{{Func|xqunitunit:assert|$test as item()*|empty-sequence()}}<br />{{Func|xqunitunit:assert|$test as item()*, $message as xs:string|empty-sequence()}}<br />
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|XQUNIT0001UNIT0001|#Errors}} the assertion failed, or an error was raised.
|}
==xqunitunit:fail==
{| width='100%'
|-
| width='90' | '''Signatures'''
|{{Func|xqunitunit:fail|$message as xs:string|empty-sequence()}}<br />
|-
| '''Summary'''
|Raises an XQUnit a unit error with the specified message.
|-
| '''Errors'''
|{{Error|XQUNIT0001UNIT0001|#Errors}} default error raised by this function.
|}
==xqunitunit:test==
{| width='100%'
|-
| width='90' | '''Signatures'''
|{{Func|xqunitunit:test||element(testsuite)*}}<br />
|-
| '''Summary'''
|Runs all functions in the current module that are annotated with {{Code|xqunitunit}} annotations.<br />A test report is generated and returned, which resembles the format returned by other xUnit testing frameworks, such as the Maven Surefire Plugin.
|-
| '''Errors'''
|{{Error|XQUNIT0002UNIT0002|#Errors}} a test function must have no arguments.<br/>{{Error|XQUNIT0003UNIT0003|#Errors}} a test function must not be updating.<br/>{{Error|XQUNIT0004UNIT0004|#Errors}} an annotation was declared twice.<br/>{{Error|XQUNIT0005UNIT0005|#Errors}} an annotation has invalid arguments.
|}
==xqunitunit:test-libraries==
{| width='100%'
|-
| width='90' | '''Signatures'''
|{{Func|xqunitunit:test-libraries|$uris as xs:string*|element(testsuites)}}<br />
|-
| '''Summary'''
|Runs all functions in the specified modules that are annotated with {{Code|xqunitunit}} annotations.<br />A test report is generated and returned, which resembles the format returned by other xUnit testing frameworks, such as the Maven Surefire Plugin.
|-
| '''Errors'''
|{{Error|XQUNIT0002UNIT0002|#Errors}} a test function must have no arguments.<br/>{{Error|XQUNIT0003UNIT0003|#Errors}} a test function must not be updating.<br/>{{Error|XQUNIT0004UNIT0004|#Errors}} an annotation was declared twice.<br/>{{Error|XQUNIT0005UNIT0005|#Errors}} an annotation has invalid arguments.
|}
=Example=
The following XQuery main module creates a test report. It contains all available XQUnit unit annotations:
'''Query:'''
(:~ Initializing function, which is called once before all tests. :)
declare
%xqunitunit:before-module
function local:before-all-tests() { ()
};
(:~ Initializing function, which is called once after all tests. :)
declare
%xqunitunit:after-module
function local:after-all-tests() { ()
};
(:~ Initializing function, which is called before each test. :)
declare
%xqunitunit:before
function local:before() { ()
};
(:~ Initializing function, which is called after each test. :)
declare
%xqunitunit:after
function local:after() { ()
};
(:~ Function demonstrating a successful test. :)
declare
%xqunitunit:test
function local:success-function() {
};
(:~ Function demonstrating a failure. :)
declare
%xqunitunit:test
function local:failure-function() {
};
(:~ Function demonstrating an expected error. :)
declare
%xqunitunit:test("expected", "FORG0001")
function local:expected-success() {
()
(:~ Function demonstrating an expected error. :)
declare
%xqunitunit:test("expected", "FORG0001")
function local:expected-error() {
1 + <a/>
(:~ Function demonstrating an error. :)
declare
%xqunitunit:test
function local:error-function() {
1 + <a/>
(:~ Skipping a test. :)
declare
%xqunitunit:test %xqunitunit:ignore("Skipped!")
function local:skipped-function() {
()
(: run all tests :)
</pre>
! width="95%"|Description
|-
|{{Code|XQUNIT0001UNIT0001}}
|An assertion failed, or an error was raised.
|-
|{{Code|XQUNIT0002UNIT0002}}
|A test function must have no arguments.
|-
|{{Code|XQUNIT0003UNIT0003}}
|A test function must not be updating.
|-
|{{Code|XQUNIT0004UNIT0004}}
|An annotation was declared twice.
|-
|{{Code|XQUNIT0005UNIT0005}}
|An annotation has invalid arguments.
|}
