documentation for the testing framework

Sat, 12 May 2018 14:13:53 +0200

author
Mike Becker <universe@uap-core.de>
date
Sat, 12 May 2018 14:13:53 +0200
changeset 297
ba760f2195c3
parent 296
e325716a442c
child 298
fffe3a16a3de

documentation for the testing framework

docs/src/modules.md file | annotate | diff | comparison | revisions
src/ucx/test.h file | annotate | diff | comparison | revisions
     1.1 --- a/docs/src/modules.md	Sat May 12 13:57:12 2018 +0200
     1.2 +++ b/docs/src/modules.md	Sat May 12 14:13:53 2018 +0200
     1.3 @@ -438,6 +438,51 @@
     1.4  To avoid code duplication within tests, we also provide the possibility to
     1.5  define test subroutines.
     1.6  
     1.7 +You should declare test cases and subroutines in a header file per test unit
     1.8 +and implement them as you would implement normal functions.
     1.9 +```C
    1.10 +    /* myunit.h */
    1.11 +    UCX_TEST(function_name);
    1.12 +    UCX_TEST_SUBROUTINE(subroutine_name, paramlist); /* optional */
    1.13 +
    1.14 +
    1.15 +    /* myunit.c */
    1.16 +    UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
    1.17 +        /* ... reusable tests with UCX_TEST_ASSERT() ... */
    1.18 +    }
    1.19 +
    1.20 +    UCX_TEST(function_name) {
    1.21 +        /* ... resource allocation and other test preparation ... */
    1.22 +
    1.23 +        /* mandatory marker for the start of the tests */
    1.24 +        UCX_TEST_BEGIN
    1.25 +
    1.26 +        /*  ... verifications with UCX_TEST_ASSERT() ...
    1.27 +         * (and/or calls with UCX_TEST_CALL_SUBROUTINE())
    1.28 +         */
    1.29 +
    1.30 +        /* mandatory marker for the end of the tests */
    1.31 +        UCX_TEST_END
    1.32 +
    1.33 +        /* ... resource cleanup ...
    1.34 +         * (all code after UCX_TEST_END is always executed)
    1.35 +         */
    1.36 +    }
    1.37 +```
    1.38 +If you want to use the `UCX_TEST_ASSERT()` macro in a function, you are
    1.39 +*required* to use a `UCX_TEST_SUBROUTINE`.
    1.40 +Otherwise the testing framework does not know where to jump, when the assertion
    1.41 +fails.
    1.42 +
    1.43 +After implementing the tests, you can easily build a test suite and execute it:
    1.44 +```C
    1.45 +    UcxTestSuite* suite = ucx_test_suite_new();
    1.46 +    ucx_test_register(suite, testMyTestCase01);
    1.47 +    ucx_test_register(suite, testMyTestCase02);
    1.48 +    /* ... */
    1.49 +    ucx_test_run(suite, stdout); /* stdout, or any other FILE stream */
    1.50 +```
    1.51 +
    1.52  ## Utilities
    1.53  
    1.54  *Header file:* [utils.h](api/utils_8h.html)  
     2.1 --- a/src/ucx/test.h	Sat May 12 13:57:12 2018 +0200
     2.2 +++ b/src/ucx/test.h	Sat May 12 14:13:53 2018 +0200
     2.3 @@ -36,8 +36,8 @@
     2.4   * **** IN HEADER FILE: ****
     2.5   *
     2.6   * <pre>
     2.7 - * UCX_TEST(function_name)
     2.8 - * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
     2.9 + * UCX_TEST(function_name);
    2.10 + * UCX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional
    2.11   * </pre>
    2.12   *
    2.13   * **** IN SOURCE FILE: ****

mercurial