Difference between revisions of "Unit Module"
(→Usage) |
(→Usage) |
||
Line 13: | Line 13: | ||
* Tests can directly be run via the BaseX GUI. | * Tests can directly be run via the BaseX GUI. | ||
* All tested functions are now allowed to perform updates. | * All tested functions are now allowed to perform updates. | ||
− | |||
Tests are not started anymore from within XQuery. Insteadt, a [[Commands#TEST|TEST]] command | Tests are not started anymore from within XQuery. Insteadt, a [[Commands#TEST|TEST]] command | ||
has been added. It compiles all XQuery modules in a given file or directory and runs all | has been added. It compiles all XQuery modules in a given file or directory and runs all | ||
− | functions that are annotated with {{Code|%unit:test}}. | + | functions 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 Maven | |
− | A test report is generated and returned, which resembles the format returned by other xUnit | + | Surefire Plugin (see below). |
− | testing frameworks, such as the Maven Surefire Plugin (see below). | ||
=Conventions= | =Conventions= |
Revision as of 20:05, 23 May 2014
This XQuery Module contains annotations and functions for performing XQUnit tests.
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.
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
With Version 7.9, the unit testing functionality has been further stabilized:
- Tests can directly be run via the BaseX GUI.
- All tested functions are now allowed to perform updates.
Tests are not started anymore from within XQuery. Insteadt, a TEST command
has been added. 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 http://basex.org/modules/unit
namespace, which is statically bound to the unit
prefix.
Annotations
%unit:test
Syntax | %unit:test %unit:test("expected", <ERROR>)
|
Summary | With this annotation, a function can be marked as unit test. It will be evaluated whenever a test report is created for the module in which this function is located. If an optional error code is specified and if the function expression does not raise that error, the test will fail. |
%unit:before
Syntax | %unit:before
|
Summary | A function decorated with this annotation will be evaluated before each unit test. |
%unit:after
Syntax | %unit:after
|
Summary | A function decorated with this annotation will be evaluated after each unit test. |
%unit:before-module
Syntax | %unit:before-module
|
Summary | If a function is decorated with this annotation, it will be evaluated before all unit tests in the current module. |
%unit:after-module
Syntax | %unit:after-module
|
Summary | If a function is decorated with this annotation, it will be evaluated after all unit tests in the current module. |
%unit:ignore
Syntax | %unit:ignore %unit:ignore("message")
|
Summary | If a function is decorated with this annotation, it will temporarily be ignored by the test suite runner. |
Functions
unit:assert
Signatures | unit:assert($test as item()*) as empty-sequence() unit: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. The effective boolean value of an expression can be explicitly computed by using the fn:boolean function.The unit failure message overridden with the $message string.
|
Errors | UNIT0001 : the assertion failed, or an error was raised.
|
unit:assert-equals
Signatures | unit:assert-equals($returned as item()*, $expected as item()*) as empty-sequence() unit:assert-equals($returned as item()*, $expected as item()*, $message as xs:string) as empty-sequence() |
Summary | Asserts that the specified arguments are equal according to the rules of the fn:deep-equals function. Otherwise, raises an error.The unit failure message overridden with the $message string.
|
Errors | UNIT0001 : the assertion failed, or an error was raised.
|
unit:fail
Signatures | unit:fail($message as xs:string) as empty-sequence() |
Summary | Raises a unit error with the specified message. |
Errors | UNIT0001 : default error raised by this function.
|
Example
The following XQUnit module tests.xq
contains all available unit annotations:
Query:
(:~ Initializing function, which is called once before all tests. :) declare %unit:before-module function unit:before-all-tests() { () }; (:~ Initializing function, which is called once after all tests. :) declare %unit:after-module function unit:after-all-tests() { () }; (:~ Initializing function, which is called before each test. :) declare %unit:before function unit:before() { () }; (:~ Initializing function, which is called after each test. :) declare %unit:after function unit:after() { () }; (:~ Function demonstrating a successful test. :) declare %unit:test function unit:assert-success() { unit:assert(<a/>) }; (:~ Function demonstrating a failure using unit:assert. :) declare %unit:test function unit:assert-failure() { unit:assert((), 'Empty sequence.') }; (:~ Function demonstrating a failure using unit:assert-equals. :) declare %unit:test function unit:assert-equals-failure() { unit:assert-equals(4 + 5, 6) }; (:~ Function demonstrating an unexpected success. :) declare %unit:test("expected", "FORG0001") function unit:unexpected-success() { () }; (:~ Function demonstrating an expected failure. :) declare %unit:test("expected", "FORG0001") function unit:expected-failure() { 1 + <a/> }; (:~ Function demonstrating the creation of a failure. :) declare %unit:test function unit:failure() { unit:fail("Failure!") }; (:~ Function demonstrating an error. :) declare %unit:test function unit:error() { 1 + <a/> }; (:~ Skipping a test. :) declare %unit:test %unit:ignore("Skipped!") function unit:skipped() { () }; ()
By running TEST tests.xq
, the following report will be generated (timings may differ):
Result:
<testsuite name="file:///C:/Users/user/Desktop/x.xq" time="PT0S" tests="8" failures="4" errors="1" skipped="1"> <testcase name="assert-success" time="PT0S"/> <testcase name="assert-failure" time="PT0S"> <failure line="28" column="15" type="UNIT0001">Empty sequence.</failure> </testcase> <testcase name="assert-equals-failure" time="PT0S"> <failure line="33" column="22"> <returned item="1">9</returned> <expected item="1">6</expected> </failure> </testcase> <testcase name="unexpected-success" time="PT0S"> <failure> <expected>FORG0001</expected> </failure> </testcase> <testcase name="expected-failure" time="PT0S"/> <testcase name="failure" time="PT0S"> <failure line="48" column="13" type="UNIT0001">Failure!</failure> </testcase> <testcase name="error" time="PT0S"> <error line="53" column="6" type="FORG0001">Invalid xs:double cast: "".</error> </testcase> <testcase name="skipped" skipped="Skipped!" time="PT0S"/> </testsuite>
Errors
Code | Description |
---|---|
UNIT0001
|
An assertion failed, or an error was raised. |
UNIT0002
|
A test function must have no arguments. |
UNIT0003
|
A test function is not public. |
UNIT0004
|
An annotation was declared twice. |
UNIT0005
|
An annotation has invalid arguments. |
UNIT0006
|
A test function returns items. |
Changelog
- 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.