universe@103: /*
universe@103:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
universe@26:  *
universe@259:  * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.
universe@33:  *
universe@103:  * Redistribution and use in source and binary forms, with or without
universe@103:  * modification, are permitted provided that the following conditions are met:
universe@33:  *
universe@103:  *   1. Redistributions of source code must retain the above copyright
universe@103:  *      notice, this list of conditions and the following disclaimer.
universe@103:  *
universe@103:  *   2. Redistributions in binary form must reproduce the above copyright
universe@103:  *      notice, this list of conditions and the following disclaimer in the
universe@103:  *      documentation and/or other materials provided with the distribution.
universe@103:  *
universe@103:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
universe@103:  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
universe@103:  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
universe@103:  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
universe@103:  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
universe@103:  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
universe@103:  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
universe@103:  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
universe@103:  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
universe@103:  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
universe@103:  * POSSIBILITY OF SUCH DAMAGE.
universe@103:  */
universe@103:  
universe@134: /**
universe@134:  * @file: test.h
universe@134:  * 
universe@134:  * UCX Test Framework.
universe@134:  * 
universe@33:  * Usage of this test framework:
universe@33:  *
universe@33:  * **** IN HEADER FILE: ****
universe@33:  *
universe@134:  * <pre>
universe@297:  * UCX_TEST(function_name);
universe@297:  * UCX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional
universe@134:  * </pre>
universe@33:  *
universe@33:  * **** IN SOURCE FILE: ****
universe@134:  * <pre>
universe@134:  * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
universe@134:  *   // tests with UCX_TEST_ASSERT()
universe@134:  * }
universe@134:  * 
universe@134:  * UCX_TEST(function_name) {
universe@134:  *   // memory allocation and other stuff here
universe@134:  *   #UCX_TEST_BEGIN
universe@134:  *   // tests with UCX_TEST_ASSERT() and/or
universe@134:  *   // calls with UCX_TEST_CALL_SUBROUTINE() here
universe@134:  *   #UCX_TEST_END
universe@134:  *   // cleanup of memory here
universe@134:  * }
universe@134:  * </pre>
universe@33:  *
universe@134:  * <b>Note:</b> if a test fails, a longjump is performed
universe@134:  * back to the #UCX_TEST_BEGIN macro!
universe@134:  * 
universe@134:  * <b>Attention:</b> Do not call own functions within a test, that use
universe@134:  * UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().
universe@134:  * 
universe@33:  *
universe@134:  * @author Mike Becker
universe@134:  * @author Olaf Wintermann
universe@33:  *
universe@26:  */
universe@26: 
olaf@120: #ifndef UCX_TEST_H
olaf@120: #define	UCX_TEST_H
universe@26: 
universe@259: #include "ucx.h"
universe@26: #include <stdio.h>
universe@26: #include <string.h>
universe@33: #include <setjmp.h>
universe@26: 
universe@26: #ifdef	__cplusplus
universe@26: extern "C" {
universe@26: #endif
universe@26: 
universe@69: #ifndef __FUNCTION__
universe@146: 
universe@134: /**
universe@135:  * Alias for the <code>__func__</code> preprocessor macro.
universe@178:  * Some compilers use <code>__func__</code> and others use __FUNCTION__.
universe@178:  * We use __FUNCTION__ so we define it for those compilers which use
universe@135:  * <code>__func__</code>.
universe@134:  */
universe@69: #define __FUNCTION__ __func__
universe@69: #endif
universe@69: 
universe@134: /** Type for the UcxTestSuite. */
universe@83: typedef struct UcxTestSuite UcxTestSuite;
universe@146: 
universe@134: /** Pointer to a test function. */
universe@83: typedef void(*UcxTest)(UcxTestSuite*,FILE*);
universe@146: 
universe@138: /** Type for the internal list of test cases. */
universe@138: typedef struct UcxTestList UcxTestList;
universe@138: 
universe@138: /** Structure for the internal list of test cases. */
universe@138: struct UcxTestList {
universe@146:     
universe@138:     /** Test case. */
universe@138:     UcxTest test;
universe@146:     
universe@138:     /** Pointer to the next list element. */
universe@138:     UcxTestList *next;
universe@138: };
universe@83: 
universe@134: /**
universe@134:  * A test suite containing multiple test cases.
universe@134:  */
universe@83: struct UcxTestSuite {
universe@146:     
universe@134:     /** The number of successful tests after the suite has been run. */
universe@26:     unsigned int success;
universe@146:     
universe@134:     /** The number of failed tests after the suite has been run. */
universe@26:     unsigned int failure;
universe@146:     
universe@134:     /**
universe@134:      * Internal list of test cases.
universe@134:      * Use ucx_test_register() to add tests to this list.
universe@134:      */
universe@83:     UcxTestList *tests;
universe@83: };
universe@26: 
universe@134: /**
universe@134:  * Creates a new test suite.
universe@134:  * @return a new test suite
universe@134:  */
universe@26: UcxTestSuite* ucx_test_suite_new();
universe@146: 
universe@134: /**
universe@134:  * Destroys a test suite.
universe@138:  * @param suite the test suite to destroy
universe@134:  */
universe@134: void ucx_test_suite_free(UcxTestSuite* suite);
universe@26: 
universe@134: /**
universe@134:  * Registers a test function with the specified test suite.
universe@134:  * 
universe@134:  * @param suite the suite, the test function shall be added to
universe@134:  * @param test the test function to register
universe@135:  * @return <code>EXIT_SUCCESS</code> on success or
universe@135:  * <code>EXIT_FAILURE</code> on failure
universe@134:  */
universe@134: int ucx_test_register(UcxTestSuite* suite, UcxTest test);
universe@146: 
universe@134: /**
universe@134:  * Runs a test suite and writes the test log to the specified stream.
universe@134:  * @param suite the test suite to run
universe@134:  * @param outstream the stream the log shall be written to
universe@134:  */
universe@134: void ucx_test_run(UcxTestSuite* suite, FILE* outstream);
universe@26: 
universe@134: /**
universe@134:  * Macro for a #UcxTest function header.
universe@134:  * 
universe@225:  * Use this macro to declare and/or define a #UcxTest function.
universe@134:  * 
universe@134:  * @param name the name of the test function
universe@134:  */
universe@134: #define UCX_TEST(name) void name(UcxTestSuite* _suite_,FILE *_output_)
universe@33: 
universe@134: /**
universe@134:  * Marks the begin of a test.
universe@134:  * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>after</b>
universe@134:  * #UCX_TEST_BEGIN.
universe@134:  * 
universe@134:  * @see #UCX_TEST_END
universe@134:  */
universe@33: #define UCX_TEST_BEGIN fwrite("Running ", 1, 8, _output_);\
universe@69:         fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
universe@33:         fwrite("... ", 1, 4, _output_);\
universe@33:         jmp_buf _env_; \
universe@33:         if (!setjmp(_env_)) {
universe@26: 
universe@134: /**
universe@134:  * Checks a test assertion.
universe@134:  * If the assertion is correct, the test carries on. If the assertion is not
universe@134:  * correct, the specified message (terminated by a dot and a line break) is
universe@134:  * written to the test suites output stream.
universe@134:  * @param condition the condition to check
universe@134:  * @param message the message that shall be printed out on failure
universe@134:  */
universe@26: #define UCX_TEST_ASSERT(condition,message) if (!(condition)) { \
universe@26:         fwrite(message".\n", 1, 2+strlen(message), _output_); \
universe@26:         _suite_->failure++; \
universe@33:         longjmp(_env_, 1);\
universe@26:     }
universe@26: 
universe@134: /**
universe@134:  * Macro for a test subroutine function header.
universe@134:  * 
universe@225:  * Use this to declare and/or define a subroutine that can be called by using
universe@134:  * UCX_TEST_CALL_SUBROUTINE().
universe@134:  * 
universe@134:  * @param name the name of the subroutine
universe@134:  * @param ... the parameter list
universe@134:  * 
universe@134:  * @see UCX_TEST_CALL_SUBROUTINE()
universe@134:  */
universe@88: #define UCX_TEST_SUBROUTINE(name,...) void name(UcxTestSuite* _suite_,\
universe@88:         FILE *_output_, jmp_buf _env_, __VA_ARGS__)
universe@134: 
universe@134: /**
universe@134:  * Macro for calling a test subroutine.
universe@134:  * 
universe@134:  * Subroutines declared with UCX_TEST_SUBROUTINE() can be called by using this
universe@134:  * macro.
universe@134:  * 
universe@134:  * <b>Note:</b> You may <b>only</b> call subroutines within a #UCX_TEST_BEGIN-
universe@134:  * #UCX_TEST_END-block.
universe@134:  * 
universe@134:  * @param name the name of the subroutine
universe@134:  * @param ... the argument list
universe@134:  * 
universe@134:  * @see UCX_TEST_SUBROUTINE()
universe@134:  */
universe@88: #define UCX_TEST_CALL_SUBROUTINE(name,...) \
universe@88:         name(_suite_,_output_,_env_,__VA_ARGS__);
universe@33: 
universe@134: /**
universe@134:  * Marks the end of a test.
universe@134:  * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>before</b>
universe@134:  * #UCX_TEST_END.
universe@134:  * 
universe@134:  * @see #UCX_TEST_BEGIN
universe@134:  */
universe@33: #define UCX_TEST_END fwrite("success.\n", 1, 9, _output_); _suite_->success++;}
universe@26: 
universe@26: #ifdef	__cplusplus
universe@26: }
universe@26: #endif
universe@26: 
olaf@120: #endif	/* UCX_TEST_H */
universe@26: