Mercurial > hg > ucx / file revision

 /*

  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

  *

  * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.

  *

  * Redistribution and use in source and binary forms, with or without

  * modification, are permitted provided that the following conditions are met:

  *

  *   1. Redistributions of source code must retain the above copyright

  *      notice, this list of conditions and the following disclaimer.

  *

  *   2. Redistributions in binary form must reproduce the above copyright

  *      notice, this list of conditions and the following disclaimer in the

  *      documentation and/or other materials provided with the distribution.

  *

  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

  * 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: ****

  *

  * <pre>

  * CX_TEST(function_name);

  * CX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional

  * </pre>

  *

  * **** IN SOURCE FILE: ****

  * <pre>

  * CX_TEST_SUBROUTINE(subroutine_name, paramlist) {

  *   // tests with CX_TEST_ASSERT()

  * }

  * 

  * CX_TEST(function_name) {

  *   // memory allocation and other stuff here

  *   #CX_TEST_BEGIN

  *   // tests with CX_TEST_ASSERT() and/or

  *   // calls with CX_TEST_CALL_SUBROUTINE() here

  *   #CX_TEST_END

  *   // cleanup of memory here

  * }

  * </pre>

  *

  * @remark if a test fails, execution continues at the

  * #CX_TEST_END macro! So make sure every necessary cleanup happens afterwards.

  * 

  * @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

  * @author Olaf Wintermann

  *

  */

 #ifndef UCX_TEST_H

 #define	UCX_TEST_H

 #include <stdlib.h>

 #include <stdio.h>

 #include <string.h>

 #include <setjmp.h>

 #ifdef	__cplusplus

 extern "C" {

 #endif

 #ifndef __FUNCTION__

 /**

  * Alias for the <code>__func__</code> preprocessor macro.

  * Some compilers use <code>__func__</code> and others use __FUNCTION__.

  * We use __FUNCTION__ so we define it for those compilers which use

  * <code>__func__</code>.

  */

 #define __FUNCTION__ __func__

 #endif

 #ifndef UCX_COMMON_H

 /**

  * Function pointer compatible with fwrite-like functions.

  */

 typedef size_t (*cx_write_func)(

         void const *,

         size_t,

         size_t,

         void *

 );

 #endif // UCX_COMMON_H

 /** Type for the CxTestSuite. */

 typedef struct CxTestSuite CxTestSuite;

 /** Pointer to a test function. */

 typedef void(*CxTest)(CxTestSuite *, void *, cx_write_func);

 /** Type for the internal list of test cases. */

 typedef struct CxTestSet CxTestSet;

 /** Structure for the internal list of test cases. */

 struct CxTestSet {

     /** Test case. */

     CxTest test;

     /** Pointer to the next list element. */

     CxTestSet *next;

 };

 /**

  * A test suite containing multiple test cases.

  */

 struct CxTestSuite {

     /** 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;

     /** The optional name of this test suite. */

     char const *name;

     /**

      * Internal list of test cases.

      * Use cx_test_register() to add tests to this list.

      */

     CxTestSet *tests;

 };

 /**

  * Creates a new test suite.

  * @param name optional name of the suite

  * @return a new test suite

  */

 static inline CxTestSuite* cx_test_suite_new(char const *name) {

     CxTestSuite* suite = (CxTestSuite*) malloc(sizeof(CxTestSuite));

     if (suite != NULL) {

         suite->name = name;

         suite->success = 0;

         suite->failure = 0;

         suite->tests = NULL;

     }

     return suite;

 }

 /**

  * Destroys a test suite.

  * @param suite the test suite to destroy

  */

 static inline void cx_test_suite_free(CxTestSuite* suite) {

     CxTestSet *l = suite->tests;

     while (l != NULL) {

         CxTestSet *e = l;

         l = l->next;

         free(e);

     }

     free(suite);

 }

 /**

  * 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

  */

 static inline int cx_test_register(CxTestSuite* suite, CxTest test) {

     CxTestSet *t = (CxTestSet*) malloc(sizeof(CxTestSet));

     if (t) {

         t->test = test;

         t->next = NULL;

         if (suite->tests == NULL) {

             suite->tests = t;

         } else {

             CxTestSet *last = suite->tests;

             while (last->next) {

                 last = last->next;

             }

             last->next = t;

         }

         return 0;

     } else {

         return 1;

     }

 }

 /**

  * 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

  */

 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("*** Test Suite : ", 1, 17, out_target);

         out_writer(suite->name, 1, strlen(suite->name), out_target);

         out_writer(" ***\n", 1, 5, out_target);

     }

     suite->success = 0;

     suite->failure = 0;

     for (CxTestSet *elem = suite->tests; elem; elem = elem->next) {

         elem->test(suite, out_target, out_writer);

     }

     out_writer("\nAll test completed.\n", 1, 21, out_target);

     char total[80];

     int len = snprintf(

             total, 80,

             "  Total:   %u\n  Success: %u\n  Failure: %u\n",

             suite->success + suite->failure, suite->success, suite->failure

     );

     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 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

  */

 #define cx_test_run_stdout(suite) cx_test_run_f(suite, stdout)

 /**

  * Macro for a #CxTest function header.

  * 

  * Use this macro to declare and/or define a #CxTest function.

  * 

  * @param name the name of the test function

  */

 #define CX_TEST(name) void name(CxTestSuite* _suite_,void *_output_, cx_write_func _writefnc_)

 /**

  * Marks the begin of a test.

  * <b>Note:</b> Any CX_TEST_ASSERT() calls must be performed <b>after</b>

  * #CX_TEST_BEGIN.

  * 

  * @see #CX_TEST_END

  */

 #define CX_TEST_BEGIN _writefnc_("Running ", 1, 8, _output_);\

         _writefnc_(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\

         _writefnc_("... ", 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 CX_TEST_ASSERT(condition,message) if (!(condition)) { \

         _writefnc_(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 a subroutine that can be called by using

  * CX_TEST_CALL_SUBROUTINE().

  * 

  * @param name the name of the subroutine

  * @param ... the parameter list

  * 

  * @see CX_TEST_CALL_SUBROUTINE()

  */

 #define CX_TEST_SUBROUTINE(name,...) void name(CxTestSuite* _suite_,\

         void *_output_, jmp_buf _env_, __VA_ARGS__)

 /**

  * Macro for calling a test subroutine.

  * 

  * Subroutines declared with CX_TEST_SUBROUTINE() can be called by using this

  * macro.

  * 

  * <b>Note:</b> You may <b>only</b> call subroutines within a #CX_TEST_BEGIN-

  * #CX_TEST_END-block.

  * 

  * @param name the name of the subroutine

  * @param ... the argument list

  * 

  * @see CX_TEST_SUBROUTINE()

  */

 #define CX_TEST_CALL_SUBROUTINE(name,...) \

         name(_suite_,_output_,_writefnc_,_env_,__VA_ARGS__);

 /**

  * Marks the end of a test.

  * <b>Note:</b> Any CX_TEST_ASSERT() calls must be performed <b>before</b>

  * #CX_TEST_END.

  * 

  * @see #CX_TEST_BEGIN

  */

 #define CX_TEST_END _writefnc_("success.\n", 1, 9, _output_); _suite_->success++;}

 #ifdef	__cplusplus

 }

 #endif

 #endif	/* UCX_TEST_H */