Changes

Jump to navigation Jump to search
1,301 bytes added ,  13:15, 24 May 2018
no edit summary
This [[Module Library|XQuery Module]] contains annotations and functions for performing XQUnit tests.
 
With {{Version|7.9}}, the unit testing functionality has been further stabilized:
 
* Tests are now started with a [[Commands#TEST|TEST]] command.
* Tests can also be executed from the BaseX GUI.
* XQUnit functions can now contain updating functions.
 
=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 automated way for of testing software. The [http://en.wikipedia.org/wiki/XUnit XUnit] frameworks (such as SUnit or JUnit) allow testing of atomic unit 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 not started from within XQuery anymore. Instead, a via the [[Commands#TEST|TEST]] commandis now available, which . It compiles all XQuery modules in a given file or directory and runs allfunctions that are annotated with {{Code|%unit:test}}. A test report is generated and returned,which resembles the format returned by other xUnit testing frameworks, such as the MavenSurefire Plugin ([[#Result|see below]]).
=Conventions=
All annotations, functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/unit}} </nowiki></code> namespace, which is statically bound to the {{Code|unit}} prefix.<br/>
=Annotations=
|-
| width='120' | '''Syntax'''
|{{Code|%unit:test}}<br/>{{Code|%unit:test("expected", <ERROR>CODE)}}
|-
| '''Summary'''
|With this annotation, a function can be marked as unit test. It will be evaluated whenever if a test report is created for the module in which this function is located.<br/>If an optional <code>error </code > can be supplied as additional string argument. It is specified and if followed by <code>CODE</code>, which must be a valid [[XQuery 3.0#Expanded QNames|EQName]] string. If the function expression does not raise that error, the test will fail.|-| '''Examples'''|* The following test does will be successful, as it does nothing (and, hence, nothing wrong):<pre class="brush:xquery">declare %unit:test function local:void() { () };</pre>* The following test will be successful, as the function body will raise <code>err:XPTY0004</code>:<pre class="brush:xquery">declare %unit:test('expected', "err:XPTY0004") function local:add() { 123 + 'strings and integers cannot be added'};</pre>
|}
==%unit:before==
 
{| width='100%'
|-
| width='120' | '''Syntax'''
|{{Code|%unit:before}}<br/>{{Code|%unit:before(FUNCTION)}}
|-
| '''Summary'''
|A function decorated with this annotation will be evaluated '''before each''' unit test.<br/><code>FUNCTION</code> can be supplied as additional argument. It must be a valid [[XQuery 3.0#Expanded QNames|EQName]] string. If specified, the function will only be evaluated before a function with the given name is tested. This extension is e. g. helpful if the results of updates need to be tested.|-| '''Examples'''|* The first function will be evaluated before the actual test:<pre class="brush:xquery">declare %updating %unit:before("local:check") function local:before-check() { db:create('test-db')};declare %updating %unit:test function local:check() { unit:assert(db:exists('test-db'))};</pre>
|}
==%unit:after==
 
{| width='100%'
|-
| width='120' | '''Syntax'''
|{{Code|%unit:after}}<br/>{{Code|%unit:after(FUNCTION)}}
|-
| '''Summary'''
|A function decorated with this annotation will be evaluated '''after each''' unit test.<br/><code>FUNCTION</code> can be supplied as additional argument. It must be a valid [[XQuery 3.0#Expanded QNames|EQName]] string. If specified, the function will only be evaluated after a function with the given name is tested.
|}
|-
| width='120' | '''Syntax'''
|{{Code|%unit:ignore}}<br/>{{Code|%unit:ignore("message"MESSAGE)}}
|-
| '''Summary'''
=Functions=
 
{{Mark|Updated with Version 8.0}}: failure argument can now be an arbitrary item.
==unit:assert==
|-
| '''Errors'''
|{{Error|UNIT0001fail|#Errors}} the assertion failed, or an error was raised.
|}
|-
| '''Summary'''
|Asserts that the specified arguments are equal according to the rules of the [http://www.w3.org/TR/xpath-functions-30/#func-deep-equal {{Code|fn:deep-equalsequal}} function]. Otherwise, raises an error.<br/>The default failure message can be overridden with the {{Code|$info}} argument.
|-
| '''Errors'''
|{{Error|UNIT0001fail|#Errors}} the assertion failed, or an error was raised.
|}
==unit:fail==
 
{{Mark|Updated with Version 8.0}}: 0-argument signature adeded.
{| width='100%'
|-
| '''Errors'''
|{{Error|UNIT0001fail|#Errors}} default error raised by this function.
|}
(:~ 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 + <a/>
};
|Description
|-
|{{Code|UNIT0001fail}}
|An assertion failed, or an error was raised.
|-
|{{Code|UNIT0002no-args}}
|A test function must have no arguments.
|-
|{{Code|UNIT0003private}}|A test function is must not public.|-|{{Code|UNIT0004}}|An annotation was declared twice.|-|{{Code|UNIT0005}}|An annotation has invalid arguments.|-|{{Code|UNIT0006}}|A test function returns itemsbe private.
|}
=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: {{Code|UNIT0006}} (ignore results returned by functions).
* Added: [[#unit:fail|unit:fail]], 0-argument signature.
* Updated: the info argument of functions can now be an arbitrary item.
* Updated: infos are now represented in an <code>info</code> child element.
* Updated: [[#unit:before|unit:before]] and [[#unit:after|unit:after]] can be extended by a filter argument.
;Version 7.9
This module was introduced with Version 7.7.
 
[[Category:XQuery]]
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu