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)