toolkit: comparison ucx/cx/test.h

-:bf7084544cb1
+:7c4b9cba09ca
 *
 * Usage of this test framework:
 *
 * **** IN HEADER FILE: ****
 *
-* <pre>
+* <code>
 * CX_TEST(function_name);
 * CX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional
-* </pre>
+* </code>
 *
 * **** IN SOURCE FILE: ****
-* <pre>
+* <code>
 * CX_TEST_SUBROUTINE(subroutine_name, paramlist) {
 *   // tests with CX_TEST_ASSERT()
 * }
 *
 * CX_TEST(function_name) {
 *     // tests with CX_TEST_ASSERT() and/or
 *     // calls with CX_TEST_CALL_SUBROUTINE() here
 *   }
 *   // cleanup of memory here
 * }
-* </pre>
+* </code>
 *
 * @attention Do not call own functions within a test, that use
 * CX_TEST_ASSERT() macros and are not defined by using CX_TEST_SUBROUTINE().
 *
 * @author Mike Becker
 */
 #ifndef UCX_TEST_H
 #define	UCX_TEST_H
-#include <stdlib.h>
+#include "common.h"
 #include <stdio.h>
 #include <string.h>
 #include <setjmp.h>
 #ifdef	__cplusplus
 * <code>__func__</code>.
 */
 #define __FUNCTION__ __func__
 #endif
-//
 #if !defined(__clang__) && __GNUC__ > 3
 #pragma GCC diagnostic ignored "-Wclobbered"
 #endif
-#ifndef UCX_COMMON_H
-/**
-* Function pointer compatible with fwrite-like functions.
-*/
-typedef size_t (*cx_write_func)(
-const void *,
-size_t,
-size_t,
-void *
-);
-#endif // UCX_COMMON_H
 /** Type for the CxTestSuite. */
 typedef struct CxTestSuite CxTestSuite;
 /** Pointer to a test function. */
 /**
 * Creates a new test suite.
 * @param name optional name of the suite
 * @return a new test suite
 */
+cx_attr_nonnull
+cx_attr_nodiscard
+cx_attr_cstr_arg(1)
+cx_attr_malloc
 static inline CxTestSuite* cx_test_suite_new(const char *name) {
 CxTestSuite* suite = (CxTestSuite*) malloc(sizeof(CxTestSuite));
 if (suite != NULL) {
 suite->name = name;
 suite->success = 0;
 return suite;
 }
 /**
-* Destroys a test suite.
+* Deallocates a test suite.
-* @param suite the test suite to destroy
+*
+* @param suite the test suite to free
 */
 static inline void cx_test_suite_free(CxTestSuite* suite) {
+if (suite == NULL) return;
 CxTestSet *l = suite->tests;
 while (l != NULL) {
 CxTestSet *e = l;
 l = l->next;
 free(e);
 /**
 * 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 zero on success or non-zero on failure
+* @retval zero success
-*/
+* @retval non-zero failure
+*/
+cx_attr_nonnull
 static inline int cx_test_register(CxTestSuite* suite, CxTest test) {
 CxTestSet *t = (CxTestSet*) malloc(sizeof(CxTestSet));
 if (t) {
 t->test = test;
 t->next = NULL;
 /**
 * Runs a test suite and writes the test log to the specified stream.
 * @param suite the test suite to run
 * @param out_target the target buffer or file to write the output to
-* @param out_writer the write function writing to \p out_target
+* @param out_writer the write function writing to @p out_target
 */
+cx_attr_nonnull
 static inline void cx_test_run(CxTestSuite *suite,
 void *out_target, cx_write_func out_writer) {
 if (suite->name == NULL) {
 out_writer("*** Test Suite ***\n", 1, 19, out_target);
 } else {
 out_writer(total, 1, len, out_target);
 }
 /**
 * Runs a test suite and writes the test log to the specified FILE stream.
-* @param suite the test suite to run
+* @param suite (@c CxTestSuite*) the test suite to run
-* @param file the target file to write the output to
+* @param file (@c FILE*) the target file to write the output to
 */
 #define cx_test_run_f(suite, file) cx_test_run(suite, (void*)file, (cx_write_func)fwrite)
 /**
 * Runs a test suite and writes the test log to stdout.
-* @param suite the test suite to run
+* @param suite (@c CxTestSuite*) the test suite to run
 */
 #define cx_test_run_stdout(suite) cx_test_run_f(suite, stdout)
 /**
 * Macro for a #CxTest function header.
 */
 #define CX_TEST(name) void name(CxTestSuite* _suite_,void *_output_, cx_write_func _writefnc_)
 /**
 * Defines the scope of a test.
+*
+* @code
+* CX_TEST(my_test_name) {
+*     // setup code
+*     CX_TEST_DO {
+*         // your tests go here
+*     }
+*     // tear down code
+* }
+* @endcode
+*
 * @attention Any CX_TEST_ASSERT() calls must be performed in scope of
 * #CX_TEST_DO.
 */
 #define CX_TEST_DO _writefnc_("Running ", 1, 8, _output_);\
 _writefnc_(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
 /**
 * 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 condition (@c bool) the condition to check
-* @param message the message that shall be printed out on failure
+* @param message (@c char*) the message that shall be printed out on failure
 */
 #define CX_TEST_ASSERTM(condition,message) if (!(condition)) { \
 const char *_assert_msg_ = message; \
 _writefnc_(_assert_msg_, 1, strlen(_assert_msg_), _output_); \
 _writefnc_(".\n", 1, 2, _output_); \
 /**
 * 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 condition (@c bool) the condition to check
 */
 #define CX_TEST_ASSERT(condition) CX_TEST_ASSERTM(condition, #condition " failed")
 /**
 * Macro for a test subroutine function header.

Mercurial > hg > toolkit / file comparison

comparison: ucx/cx/test.h

ucx/cx/test.h