1.1 --- a/ucx/test.h Fri Aug 09 10:24:02 2013 +0200
1.2 +++ b/ucx/test.h Fri Aug 09 11:32:10 2013 +0200
1.3 @@ -26,27 +26,45 @@
1.4 * POSSIBILITY OF SUCH DAMAGE.
1.5 */
1.6
1.7 -/*
1.8 - *
1.9 +/**
1.10 + * @file: test.h
1.11 + *
1.12 + * UCX Test Framework.
1.13 + *
1.14 * Usage of this test framework:
1.15 *
1.16 * **** IN HEADER FILE: ****
1.17 *
1.18 - * UCX_TEST_DECLARE(function_name)
1.19 + * <pre>
1.20 + * UCX_TEST(function_name)
1.21 + * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
1.22 + * </pre>
1.23 *
1.24 * **** IN SOURCE FILE: ****
1.25 + * <pre>
1.26 + * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
1.27 + * // tests with UCX_TEST_ASSERT()
1.28 + * }
1.29 + *
1.30 + * UCX_TEST(function_name) {
1.31 + * // memory allocation and other stuff here
1.32 + * #UCX_TEST_BEGIN
1.33 + * // tests with UCX_TEST_ASSERT() and/or
1.34 + * // calls with UCX_TEST_CALL_SUBROUTINE() here
1.35 + * #UCX_TEST_END
1.36 + * // cleanup of memory here
1.37 + * }
1.38 + * </pre>
1.39 *
1.40 - * UCX_TEST_IMPLEMENT(function_name) {
1.41 - * <memory allocation and other stuff here>
1.42 - * UCX_TEST_BEGIN
1.43 - * <tests with UCX_TEST_ASSERT here>
1.44 - * UCX_TEST_END
1.45 - * <cleanup of memory here>
1.46 - * }
1.47 + * <b>Note:</b> if a test fails, a longjump is performed
1.48 + * back to the #UCX_TEST_BEGIN macro!
1.49 + *
1.50 + * <b>Attention:</b> Do not call own functions within a test, that use
1.51 + * UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().
1.52 + *
1.53 *
1.54 - * PLEASE NOTE: if a test fails, a longjump is performed
1.55 - * back to the UCX_TEST_BEGIN macro!
1.56 - *
1.57 + * @author Mike Becker
1.58 + * @author Olaf Wintermann
1.59 *
1.60 */
1.61
1.62 @@ -63,50 +81,136 @@
1.63 #endif
1.64
1.65 #ifndef __FUNCTION__
1.66 +/**
1.67 + * Alias for the __func__ preprocessor macro.
1.68 + * Some compilers use __func__ and others use __FUNC__. We use __FUNC__ so we
1.69 + * define it for those compilers which use __func__.
1.70 + */
1.71 #define __FUNCTION__ __func__
1.72 #endif
1.73
1.74 +/** Type for the internal list of test cases. */
1.75 typedef struct UcxTestList UcxTestList;
1.76 +/** Type for the UcxTestSuite. */
1.77 typedef struct UcxTestSuite UcxTestSuite;
1.78 +/** Pointer to a test function. */
1.79 typedef void(*UcxTest)(UcxTestSuite*,FILE*);
1.80 -
1.81 -struct UcxTestList{
1.82 - UcxTest test;
1.83 - UcxTestList *next;
1.84 -};
1.85
1.86 +/**
1.87 + * A test suite containing multiple test cases.
1.88 + */
1.89 struct UcxTestSuite {
1.90 + /** The number of successful tests after the suite has been run. */
1.91 unsigned int success;
1.92 + /** The number of failed tests after the suite has been run. */
1.93 unsigned int failure;
1.94 + /**
1.95 + * Internal list of test cases.
1.96 + * Use ucx_test_register() to add tests to this list.
1.97 + */
1.98 UcxTestList *tests;
1.99 };
1.100
1.101 +/**
1.102 + * Creates a new test suite.
1.103 + * @return a new test suite
1.104 + */
1.105 UcxTestSuite* ucx_test_suite_new();
1.106 -void ucx_test_suite_free(UcxTestSuite*);
1.107 +/**
1.108 + * Destroys a test suite.
1.109 + * @param the test suite to destroy
1.110 + */
1.111 +void ucx_test_suite_free(UcxTestSuite* suite);
1.112
1.113 -int ucx_test_register(UcxTestSuite*, UcxTest);
1.114 -void ucx_test_run(UcxTestSuite*, FILE*);
1.115 +/**
1.116 + * Registers a test function with the specified test suite.
1.117 + *
1.118 + * @param suite the suite, the test function shall be added to
1.119 + * @param test the test function to register
1.120 + * @return EXIT_SUCCESS on success or EXIT_FAILURE on failure
1.121 + */
1.122 +int ucx_test_register(UcxTestSuite* suite, UcxTest test);
1.123 +/**
1.124 + * Runs a test suite and writes the test log to the specified stream.
1.125 + * @param suite the test suite to run
1.126 + * @param outstream the stream the log shall be written to
1.127 + */
1.128 +void ucx_test_run(UcxTestSuite* suite, FILE* outstream);
1.129
1.130 -#define UCX_TEST_DECLARE(name) void name(UcxTestSuite*,FILE *)
1.131 -#define UCX_TEST_IMPLEMENT(name) void name(UcxTestSuite* _suite_,FILE *_output_)
1.132 +/**
1.133 + * Macro for a #UcxTest function header.
1.134 + *
1.135 + * Use this macro to declare and/or define an #UcxTest function.
1.136 + *
1.137 + * @param name the name of the test function
1.138 + */
1.139 +#define UCX_TEST(name) void name(UcxTestSuite* _suite_,FILE *_output_)
1.140
1.141 +/**
1.142 + * Marks the begin of a test.
1.143 + * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>after</b>
1.144 + * #UCX_TEST_BEGIN.
1.145 + *
1.146 + * @see #UCX_TEST_END
1.147 + */
1.148 #define UCX_TEST_BEGIN fwrite("Running ", 1, 8, _output_);\
1.149 fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
1.150 fwrite("... ", 1, 4, _output_);\
1.151 jmp_buf _env_; \
1.152 if (!setjmp(_env_)) {
1.153
1.154 +/**
1.155 + * Checks a test assertion.
1.156 + * If the assertion is correct, the test carries on. If the assertion is not
1.157 + * correct, the specified message (terminated by a dot and a line break) is
1.158 + * written to the test suites output stream.
1.159 + * @param condition the condition to check
1.160 + * @param message the message that shall be printed out on failure
1.161 + */
1.162 #define UCX_TEST_ASSERT(condition,message) if (!(condition)) { \
1.163 fwrite(message".\n", 1, 2+strlen(message), _output_); \
1.164 _suite_->failure++; \
1.165 longjmp(_env_, 1);\
1.166 }
1.167
1.168 +/**
1.169 + * Macro for a test subroutine function header.
1.170 + *
1.171 + * Use this to declare and/or define an subroutine that can be called by using
1.172 + * UCX_TEST_CALL_SUBROUTINE().
1.173 + *
1.174 + * @param name the name of the subroutine
1.175 + * @param ... the parameter list
1.176 + *
1.177 + * @see UCX_TEST_CALL_SUBROUTINE()
1.178 + */
1.179 #define UCX_TEST_SUBROUTINE(name,...) void name(UcxTestSuite* _suite_,\
1.180 FILE *_output_, jmp_buf _env_, __VA_ARGS__)
1.181 +
1.182 +/**
1.183 + * Macro for calling a test subroutine.
1.184 + *
1.185 + * Subroutines declared with UCX_TEST_SUBROUTINE() can be called by using this
1.186 + * macro.
1.187 + *
1.188 + * <b>Note:</b> You may <b>only</b> call subroutines within a #UCX_TEST_BEGIN-
1.189 + * #UCX_TEST_END-block.
1.190 + *
1.191 + * @param name the name of the subroutine
1.192 + * @param ... the argument list
1.193 + *
1.194 + * @see UCX_TEST_SUBROUTINE()
1.195 + */
1.196 #define UCX_TEST_CALL_SUBROUTINE(name,...) \
1.197 name(_suite_,_output_,_env_,__VA_ARGS__);
1.198
1.199 +/**
1.200 + * Marks the end of a test.
1.201 + * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>before</b>
1.202 + * #UCX_TEST_END.
1.203 + *
1.204 + * @see #UCX_TEST_BEGIN
1.205 + */
1.206 #define UCX_TEST_END fwrite("success.\n", 1, 9, _output_); _suite_->success++;}
1.207
1.208 #ifdef __cplusplus
