ucx: ucx/test.h@4d320dc3a7af

     1 /*

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

     3  *

     4  * Copyright 2013 Olaf Wintermann. All rights reserved.

     5  *

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

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

     8  *

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

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

    11  *

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

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

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

    15  *

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

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

    18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

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

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

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

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

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

    24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

    25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

    26  * POSSIBILITY OF SUCH DAMAGE.

    27  */

    29 /**

    30  * @file: test.h

    31  *

    32  * UCX Test Framework.

    33  *

    34  * Usage of this test framework:

    35  *

    36  * **** IN HEADER FILE: ****

    37  *

    38  * <pre>

    39  * UCX_TEST(function_name)

    40  * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional

    41  * </pre>

    42  *

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

    44  * <pre>

    45  * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {

    46  *   // tests with UCX_TEST_ASSERT()

    47  * }

    48  *

    49  * UCX_TEST(function_name) {

    50  *   // memory allocation and other stuff here

    51  *   #UCX_TEST_BEGIN

    52  *   // tests with UCX_TEST_ASSERT() and/or

    53  *   // calls with UCX_TEST_CALL_SUBROUTINE() here

    54  *   #UCX_TEST_END

    55  *   // cleanup of memory here

    56  * }

    57  * </pre>

    58  *

    59  * <b>Note:</b> if a test fails, a longjump is performed

    60  * back to the #UCX_TEST_BEGIN macro!

    61  *

    62  * <b>Attention:</b> Do not call own functions within a test, that use

    63  * UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().

    64  *

    65  *

    66  * @author Mike Becker

    67  * @author Olaf Wintermann

    68  *

    69  */

    71 #ifndef UCX_TEST_H

    72 #define	UCX_TEST_H

    74 #include "ucx.h"

    75 #include <stdio.h>

    76 #include <string.h>

    77 #include <setjmp.h>

    79 #ifdef	__cplusplus

    80 extern "C" {

    81 #endif

    83 #ifndef __FUNCTION__

    84 /**

    85  * Alias for the __func__ preprocessor macro.

    86  * Some compilers use __func__ and others use __FUNC__. We use __FUNC__ so we

    87  * define it for those compilers which use __func__.

    88  */

    89 #define __FUNCTION__ __func__

    90 #endif

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

    93 typedef struct UcxTestList UcxTestList;

    94 /** Type for the UcxTestSuite. */

    95 typedef struct UcxTestSuite UcxTestSuite;

    96 /** Pointer to a test function. */

    97 typedef void(*UcxTest)(UcxTestSuite*,FILE*);

    99 /**

   100  * A test suite containing multiple test cases.

   101  */

   102 struct UcxTestSuite {

   103     /** The number of successful tests after the suite has been run. */

   104     unsigned int success;

   105     /** The number of failed tests after the suite has been run. */

   106     unsigned int failure;

   107     /**

   108      * Internal list of test cases.

   109      * Use ucx_test_register() to add tests to this list.

   110      */

   111     UcxTestList *tests;

   112 };

   114 /**

   115  * Creates a new test suite.

   116  * @return a new test suite

   117  */

   118 UcxTestSuite* ucx_test_suite_new();

   119 /**

   120  * Destroys a test suite.

   121  * @param the test suite to destroy

   122  */

   123 void ucx_test_suite_free(UcxTestSuite* suite);

   125 /**

   126  * Registers a test function with the specified test suite.

   127  *

   128  * @param suite the suite, the test function shall be added to

   129  * @param test the test function to register

   130  * @return EXIT_SUCCESS on success or EXIT_FAILURE on failure

   131  */

   132 int ucx_test_register(UcxTestSuite* suite, UcxTest test);

   133 /**

   134  * Runs a test suite and writes the test log to the specified stream.

   135  * @param suite the test suite to run

   136  * @param outstream the stream the log shall be written to

   137  */

   138 void ucx_test_run(UcxTestSuite* suite, FILE* outstream);

   140 /**

   141  * Macro for a #UcxTest function header.

   142  *

   143  * Use this macro to declare and/or define an #UcxTest function.

   144  *

   145  * @param name the name of the test function

   146  */

   147 #define UCX_TEST(name) void name(UcxTestSuite* _suite_,FILE *_output_)

   149 /**

   150  * Marks the begin of a test.

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

   152  * #UCX_TEST_BEGIN.

   153  *

   154  * @see #UCX_TEST_END

   155  */

   156 #define UCX_TEST_BEGIN fwrite("Running ", 1, 8, _output_);\

   157         fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\

   158         fwrite("... ", 1, 4, _output_);\

   159         jmp_buf _env_; \

   160         if (!setjmp(_env_)) {

   162 /**

   163  * Checks a test assertion.

   164  * If the assertion is correct, the test carries on. If the assertion is not

   165  * correct, the specified message (terminated by a dot and a line break) is

   166  * written to the test suites output stream.

   167  * @param condition the condition to check

   168  * @param message the message that shall be printed out on failure

   169  */

   170 #define UCX_TEST_ASSERT(condition,message) if (!(condition)) { \

   171         fwrite(message".\n", 1, 2+strlen(message), _output_); \

   172         _suite_->failure++; \

   173         longjmp(_env_, 1);\

   174     }

   176 /**

   177  * Macro for a test subroutine function header.

   178  *

   179  * Use this to declare and/or define an subroutine that can be called by using

   180  * UCX_TEST_CALL_SUBROUTINE().

   181  *

   182  * @param name the name of the subroutine

   183  * @param ... the parameter list

   184  *

   185  * @see UCX_TEST_CALL_SUBROUTINE()

   186  */

   187 #define UCX_TEST_SUBROUTINE(name,...) void name(UcxTestSuite* _suite_,\

   188         FILE *_output_, jmp_buf _env_, __VA_ARGS__)

   190 /**

   191  * Macro for calling a test subroutine.

   192  *

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

   194  * macro.

   195  *

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

   197  * #UCX_TEST_END-block.

   198  *

   199  * @param name the name of the subroutine

   200  * @param ... the argument list

   201  *

   202  * @see UCX_TEST_SUBROUTINE()

   203  */

   204 #define UCX_TEST_CALL_SUBROUTINE(name,...) \

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

   207 /**

   208  * Marks the end of a test.

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

   210  * #UCX_TEST_END.

   211  *

   212  * @see #UCX_TEST_BEGIN

   213  */

   214 #define UCX_TEST_END fwrite("success.\n", 1, 9, _output_); _suite_->success++;}

   216 #ifdef	__cplusplus

   217 }

   218 #endif

   220 #endif	/* UCX_TEST_H */

Mercurial > hg > ucx / file revision