Unit testing functions


Defines

#define cpl_assert(bool)
 Evaluate an expression and return if it fails.
#define cpl_test(bool)
 Evaluate an expression and increment an internal counter if zero.
#define cpl_test_init(REPORT, LEVEL)   cpl_test_init_macro(__FILE__, REPORT, LEVEL)
 Initialize CPL + CPL messaging + unit test.
#define cpl_test_leq(value, tolerance)
 Evaluate A <= B and increment an internal counter if it is not true.
#define cpl_test_lt(value, tolerance)
 Evaluate A < B and increment an internal counter if it is not true.
#define cpl_test_zero(zero)
 Evaluate an expression and increment an internal counter if non-zero.

Functions

int cpl_test_end (int nfail)
 Finalize CPL and unit-testing environment and report any failures.
double cpl_test_get_cputime (void)
 Get the process time, when available (from times()).

Detailed Description

This module provides various functions for unit testing.

Synopsis:
   #include "cpl_test.h"

Define Documentation

#define cpl_assert ( bool   ) 

Value:

do {                                                  \
    /* Evaluate bool just once */                                              \
    const cpl_boolean cpl_assert_ok = (bool) ? CPL_TRUE : CPL_FALSE;           \
    cpl_test(cpl_assert_ok);                                                   \
    if (cpl_assert_ok == CPL_FALSE) return cpl_test_end(1);                    \
  } while (0)
Evaluate an expression and return if it fails.

Parameters:
bool The (boolean) expression to evaluate, side-effects are allowed
Note:
A zero value of the expression is a failure, other values are not
Returns:
void
See also:
cpl_test()
Note:
This macro should be used for unit tests that cannot continue after a failure.
Example of usage:
    int main (void)
    {

        cpl_test_init(CPL_MSG_WARNING);

        cpl_test(myfunc(&p));
        cpl_assert(p != NULL);
        cpl_test(*p);

        return cpl_test_end(0);
    }

#define cpl_test ( bool   ) 

Value:

cpl_test_macro((int)(bool), CPL_TRUE, #bool,     \
                                      cpl_func, __FILE__, __LINE__)
Evaluate an expression and increment an internal counter if zero.

Parameters:
bool The expression to evaluate, side-effects are allowed
Note:
A zero value of the expression is a failure, other values are not
Returns:
void
See also:
cpl_test_init()
Note:
This macro should be used for unit tests
Example of usage:
   cpl_test(myfunc()); // myfunc() is expected to return non-zero

#define cpl_test_init ( REPORT,
LEVEL   )     cpl_test_init_macro(__FILE__, REPORT, LEVEL)

Initialize CPL + CPL messaging + unit test.

Parameters:
REPORT The email address for the error message e.g. PACKAGE_BUGREPORT
LEVEL The default messaging level, e.g. CPL_MSG_WARNING
Returns:
void
See also:
cpl_init()
Note:
This macro should be used at the beginning of main() of a unit test instead of cpl_init() and before any other CPL function call.

#define cpl_test_leq ( value,
tolerance   ) 

Value:

cpl_test_leq_macro(value, #value, tolerance, #tolerance, cpl_func,         \
                       __FILE__, __LINE__)
Evaluate A <= B and increment an internal counter if it is not true.

Parameters:
value The number to test
tolerance The upper limit to compare against
Returns:
void
See also:
cpl_test_init()
Note:
This macro should be used for unit tests
Example of usage:
   cpl_test_leq(fabs(myfunc(&p)), DBL_EPSILON);
   cpl_test_nonnull(p);

#define cpl_test_lt ( value,
tolerance   ) 

Value:

cpl_test_lt_macro(value, #value, tolerance, #tolerance, cpl_func,         \
                       __FILE__, __LINE__)
Evaluate A < B and increment an internal counter if it is not true.

Parameters:
value The number to test
tolerance The upper limit to compare against
Returns:
void
See also:
cpl_test_init()
Note:
This macro should be used for unit tests
Example of usage:
   cpl_test_lt(0.0, myfunc());

#define cpl_test_zero ( zero   ) 

Value:

cpl_test_macro((int)(zero), CPL_FALSE, #zero, \
                                           cpl_func, __FILE__, __LINE__)
Evaluate an expression and increment an internal counter if non-zero.

Parameters:
zero The numerical expression to evaluate, side-effects are allowed
Note:
A zero value of the expression is a success, other values are not
Returns:
void
See also:
cpl_test()
Note:
This macro should be used for unit tests
Example of usage:
   cpl_test_zero(myfunc()); // myfunc() is expected to return zero


Function Documentation

int cpl_test_end ( int  nfail  ) 

Finalize CPL and unit-testing environment and report any failures.

Parameters:
nfail The number of failures counted apart from cpl_test() et al.
Returns:
EXIT_SUCCESS iff the CPL errorstate is clean
Note:
This function should be used for the final return from a unit test
See also:
cpl_test_init()
nfail should normally be zero, but may be set to a positive number when it is necessary to ensure a failure. nfail should only be negative in the unit test of the unit-test functions themselves.

Example of usage:

    int main (void)
    {

        cpl_test_init(PACKAGE_BUGREPORT, CPL_MSG_WARNING);

        cpl_test(myfunc(&p));
        cpl_test(p != NULL);

        return cpl_test_end(0);
    }

double cpl_test_get_cputime ( void   ) 

Get the process time, when available (from times()).

Returns:
The process time in seconds.
Note:
Will always return 0 if times() is unavailable
Example of usage:
    int my_benchmark (void)
    {
        double cputime, tstop;
        const double tstart = cpl_test_get_cputime();

        myfunc();

        tstop = cpl_test_get_cputime();

        cputime = tstop - tstart;

        cpl_msg_info(cpl_func, "The call took %g seconds of CPU-time", cputime);

    }


Generated on Wed Mar 18 09:40:13 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7