ucx: comparison ucx/test.h

-:0a70e0d36949
+:4d320dc3a7af
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
-/*
+/**
-*
+* @file: test.h
+*
+* UCX Test Framework.
+*
 * Usage of this test framework:
 *
 * **** IN HEADER FILE: ****
 *
-* UCX_TEST_DECLARE(function_name)
+* <pre>
+* UCX_TEST(function_name)
+* UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
+* </pre>
 *
 * **** IN SOURCE FILE: ****
-*
+* <pre>
-* UCX_TEST_IMPLEMENT(function_name) {
+* UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
-*  <memory allocation and other stuff here>
+*   // tests with UCX_TEST_ASSERT()
-*  UCX_TEST_BEGIN
-*  <tests with UCX_TEST_ASSERT here>
-*  UCX_TEST_END
-*  <cleanup of memory here>
 * }
 *
-* PLEASE NOTE: if a test fails, a longjump is performed
+* UCX_TEST(function_name) {
-* back to the UCX_TEST_BEGIN macro!
+*   // memory allocation and other stuff here
-*
+*   #UCX_TEST_BEGIN
+*   // tests with UCX_TEST_ASSERT() and/or
+*   // calls with UCX_TEST_CALL_SUBROUTINE() here
+*   #UCX_TEST_END
+*   // cleanup of memory here
+* }
+* </pre>
+*
+* <b>Note:</b> if a test fails, a longjump is performed
+* back to the #UCX_TEST_BEGIN macro!
+*
+* <b>Attention:</b> Do not call own functions within a test, that use
+* UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().
+*
+*
+* @author Mike Becker
+* @author Olaf Wintermann
 *
 */
 #ifndef UCX_TEST_H
 #define	UCX_TEST_H
 #ifdef	__cplusplus
 extern "C" {
 #endif
 #ifndef __FUNCTION__
+/**
+* Alias for the __func__ preprocessor macro.
+* Some compilers use __func__ and others use __FUNC__. We use __FUNC__ so we
+* define it for those compilers which use __func__.
+*/
 #define __FUNCTION__ __func__
 #endif
+/** Type for the internal list of test cases. */
 typedef struct UcxTestList UcxTestList;
+/** Type for the UcxTestSuite. */
 typedef struct UcxTestSuite UcxTestSuite;
+/** Pointer to a test function. */
 typedef void(*UcxTest)(UcxTestSuite*,FILE*);
-struct UcxTestList{
+/**
-UcxTest test;
+* A test suite containing multiple test cases.
-UcxTestList *next;
+*/
-};
 struct UcxTestSuite {
+/** The number of successful tests after the suite has been run. */
 unsigned int success;
+/** The number of failed tests after the suite has been run. */
 unsigned int failure;
+/**
+* Internal list of test cases.
+* Use ucx_test_register() to add tests to this list.
+*/
 UcxTestList *tests;
 };
+/**
+* Creates a new test suite.
+* @return a new test suite
+*/
 UcxTestSuite* ucx_test_suite_new();
-void ucx_test_suite_free(UcxTestSuite*);
+/**
+* Destroys a test suite.
-int ucx_test_register(UcxTestSuite*, UcxTest);
+* @param the test suite to destroy
-void ucx_test_run(UcxTestSuite*, FILE*);
+*/
+void ucx_test_suite_free(UcxTestSuite* suite);
-#define UCX_TEST_DECLARE(name) void name(UcxTestSuite*,FILE *)
-#define UCX_TEST_IMPLEMENT(name) void name(UcxTestSuite* _suite_,FILE *_output_)
+/**
+* Registers a test function with the specified test suite.
+*
+* @param suite the suite, the test function shall be added to
+* @param test the test function to register
+* @return EXIT_SUCCESS on success or EXIT_FAILURE on failure
+*/
+int ucx_test_register(UcxTestSuite* suite, UcxTest test);
+/**
+* Runs a test suite and writes the test log to the specified stream.
+* @param suite the test suite to run
+* @param outstream the stream the log shall be written to
+*/
+void ucx_test_run(UcxTestSuite* suite, FILE* outstream);
+/**
+* Macro for a #UcxTest function header.
+*
+* Use this macro to declare and/or define an #UcxTest function.
+*
+* @param name the name of the test function
+*/
+#define UCX_TEST(name) void name(UcxTestSuite* _suite_,FILE *_output_)
+/**
+* Marks the begin of a test.
+* <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>after</b>
+* #UCX_TEST_BEGIN.
+*
+* @see #UCX_TEST_END
+*/
 #define UCX_TEST_BEGIN fwrite("Running ", 1, 8, _output_);\
 fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
 fwrite("... ", 1, 4, _output_);\
 jmp_buf _env_; \
 if (!setjmp(_env_)) {
+/**
+* Checks a test assertion.
+* If the assertion is correct, the test carries on. If the assertion is not
+* correct, the specified message (terminated by a dot and a line break) is
+* written to the test suites output stream.
+* @param condition the condition to check
+* @param message the message that shall be printed out on failure
+*/
 #define UCX_TEST_ASSERT(condition,message) if (!(condition)) { \
 fwrite(message".\n", 1, 2+strlen(message), _output_); \
 _suite_->failure++; \
 longjmp(_env_, 1);\
 }
+/**
+* Macro for a test subroutine function header.
+*
+* Use this to declare and/or define an subroutine that can be called by using
+* UCX_TEST_CALL_SUBROUTINE().
+*
+* @param name the name of the subroutine
+* @param ... the parameter list
+*
+* @see UCX_TEST_CALL_SUBROUTINE()
+*/
 #define UCX_TEST_SUBROUTINE(name,...) void name(UcxTestSuite* _suite_,\
 FILE *_output_, jmp_buf _env_, __VA_ARGS__)
+/**
+* Macro for calling a test subroutine.
+*
+* Subroutines declared with UCX_TEST_SUBROUTINE() can be called by using this
+* macro.
+*
+* <b>Note:</b> You may <b>only</b> call subroutines within a #UCX_TEST_BEGIN-
+* #UCX_TEST_END-block.
+*
+* @param name the name of the subroutine
+* @param ... the argument list
+*
+* @see UCX_TEST_SUBROUTINE()
+*/
 #define UCX_TEST_CALL_SUBROUTINE(name,...) \
 name(_suite_,_output_,_env_,__VA_ARGS__);
+/**
+* Marks the end of a test.
+* <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>before</b>
+* #UCX_TEST_END.
+*
+* @see #UCX_TEST_BEGIN
+*/
 #define UCX_TEST_END fwrite("success.\n", 1, 9, _output_); _suite_->success++;}
 #ifdef	__cplusplus
 }
 #endif

Mercurial > hg > ucx / file comparison

comparison: ucx/test.h

ucx/test.h