# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1526127233 -7200
# Node ID ba760f2195c3568f20ee4a095c424ea329b21861
# Parent  e325716a442c215bc4cf63ef8983ba0a4d5cfbc1
documentation for the testing framework

diff -r e325716a442c -r ba760f2195c3 docs/src/modules.md
--- a/docs/src/modules.md	Sat May 12 13:57:12 2018 +0200
+++ b/docs/src/modules.md	Sat May 12 14:13:53 2018 +0200
@@ -438,6 +438,51 @@
 To avoid code duplication within tests, we also provide the possibility to
 define test subroutines.
 
+You should declare test cases and subroutines in a header file per test unit
+and implement them as you would implement normal functions.
+```C
+    /* myunit.h */
+    UCX_TEST(function_name);
+    UCX_TEST_SUBROUTINE(subroutine_name, paramlist); /* optional */
+
+
+    /* myunit.c */
+    UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
+        /* ... reusable tests with UCX_TEST_ASSERT() ... */
+    }
+
+    UCX_TEST(function_name) {
+        /* ... resource allocation and other test preparation ... */
+
+        /* mandatory marker for the start of the tests */
+        UCX_TEST_BEGIN
+
+        /*  ... verifications with UCX_TEST_ASSERT() ...
+         * (and/or calls with UCX_TEST_CALL_SUBROUTINE())
+         */
+
+        /* mandatory marker for the end of the tests */
+        UCX_TEST_END
+
+        /* ... resource cleanup ...
+         * (all code after UCX_TEST_END is always executed)
+         */
+    }
+```
+If you want to use the `UCX_TEST_ASSERT()` macro in a function, you are
+*required* to use a `UCX_TEST_SUBROUTINE`.
+Otherwise the testing framework does not know where to jump, when the assertion
+fails.
+
+After implementing the tests, you can easily build a test suite and execute it:
+```C
+    UcxTestSuite* suite = ucx_test_suite_new();
+    ucx_test_register(suite, testMyTestCase01);
+    ucx_test_register(suite, testMyTestCase02);
+    /* ... */
+    ucx_test_run(suite, stdout); /* stdout, or any other FILE stream */
+```
+
 ## Utilities
 
 *Header file:* [utils.h](api/utils_8h.html)  
diff -r e325716a442c -r ba760f2195c3 src/ucx/test.h
--- a/src/ucx/test.h	Sat May 12 13:57:12 2018 +0200
+++ b/src/ucx/test.h	Sat May 12 14:13:53 2018 +0200
@@ -36,8 +36,8 @@
  * **** IN HEADER FILE: ****
  *
  * <pre>
- * UCX_TEST(function_name)
- * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
+ * UCX_TEST(function_name);
+ * UCX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional
  * </pre>
  *
  * **** IN SOURCE FILE: ****