Unit Module
This XQuery Module contains functions for running XQUnit annotated functions in XQuery modules.
Contents
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.
|
Example
The following XQuery main module creates a test report. It contains all available XQUnit annotations:
- Query:
(:~ Initializing function, which is called once before all tests. :) declare %xqunit:before-module function local:before-all-tests() { () }; (:~ Initializing function, which is called once after all tests. :) declare %xqunit:after-module function local:after-all-tests() { () }; (:~ Initializing function, which is called before each test. :) declare %xqunit:before function local:before() { () }; (:~ Initializing function, which is called after each test. :) declare %xqunit:after function local:after() { () }; (:~ Function demonstrating a successful test. :) declare %xqunit:test function local:success-function() { xqunit:assert(1 + 2 = 3) }; (:~ Function demonstrating a failure. :) declare %xqunit:test function local:failure-function() { xqunit:assert(4 + 5 = 6) }; (:~ Function demonstrating an expected error. :) declare %xqunit:test("expected", "FORG0001") function local:expected-success() { () }; (:~ Function demonstrating an expected error. :) declare %xqunit:test("expected", "FORG0001") function local:expected-error() { 1 + <a/> }; (:~ Function demonstrating an error. :) declare %xqunit:test function local:error-function() { 1 + <a/> }; (:~ Skipping a test. :) declare %xqunit:test %xqunit:ignore("Skipped!") function local:skipped-function() { () }; (: run all tests :) xqunit:test()
xqunit:assert
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.