src/ucx/test.h

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2013 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>
 * UCX_TEST(function_name)
 * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
 * </pre>
 *
 * **** IN SOURCE FILE: ****
 * <pre>
 * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
 *   // tests with UCX_TEST_ASSERT()
 * }
 * 
 * UCX_TEST(function_name) {
 *   // 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

#include "ucx.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 __FUNC__.
 * We use __FUNC__ so we define it for those compilers which use
 * <code>__func__</code>.
 */
#define __FUNCTION__ __func__
#endif

/** Type for the UcxTestSuite. */
typedef struct UcxTestSuite UcxTestSuite;

/** Pointer to a test function. */
typedef void(*UcxTest)(UcxTestSuite*,FILE*);

/** Type for the internal list of test cases. */
typedef struct UcxTestList UcxTestList;

/** Structure for the internal list of test cases. */
struct UcxTestList {
    
    /** Test case. */
    UcxTest test;
    
    /** Pointer to the next list element. */
    UcxTestList *next;
};

/**
 * A test suite containing multiple test cases.
 */
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();

/**
 * Destroys a test suite.
 * @param suite the test suite to destroy
 */
void ucx_test_suite_free(UcxTestSuite* 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 <code>EXIT_SUCCESS</code> on success or
 * <code>EXIT_FAILURE</code> 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

#endif	/* UCX_TEST_H */