Unit testing functions

Macros
#define	cpl_test(bool)
	Evaluate an expression and increment an internal counter if zero. More...
#define	cpl_test_abs(first, second, tolerance)
	Test if two numerical expressions are within a given absolute tolerance. More...
#define	cpl_test_array_abs(first, second, tolerance)
	Test if two numerical arrays are identical within a given (absolute) tolerance. More...
#define	cpl_test_assert(bool)
	Evaluate an expression and terminate the process if it fails. More...
#define	cpl_test_eq(first, second)
	Test if two integer expressions are equal. More...
#define	cpl_test_eq_error(first, second)
	Test if two error expressions are equal and reset the CPL error code. More...
#define	cpl_test_eq_mask(first, second)
	Test if two CPL masks are equal. More...
#define	cpl_test_eq_ptr(first, second)
	Test if two pointer expressions are equal. More...
#define	cpl_test_eq_string(first, second)
	Test if two strings are equal. More...
#define	cpl_test_error(error)
	Test and reset the CPL error code. More...
#define	cpl_test_errorstate(errorstate)
	Test and if necessary reset the CPL errorstate. More...
#define	cpl_test_fits(fitsfile)
	Test if a file is valid FITS using an external verification utility. More...
#define	cpl_test_image_abs(first, second, tolerance)
	Test if two images are identical within a given (absolute) tolerance. More...
#define	cpl_test_image_rel(first, second, tolerance)
	Test if two images are identical within a given (relative) tolerance. More...
#define	cpl_test_imagelist_abs(first, second, tolerance)
	Test if two imagelists are identical within a given (absolute) tolerance. More...
#define	cpl_test_init(REPORT, LEVEL)
	Initialize CPL + CPL messaging + unit test. More...
#define	cpl_test_leq(value, tolerance)
	Evaluate A <= B and increment an internal counter if it is not true. More...
#define	cpl_test_lt(value, tolerance)
	Evaluate A < B and increment an internal counter if it is not true. More...
#define	cpl_test_matrix_abs(first, second, tolerance)
	Test if two matrices are identical within a given (absolute) tolerance. More...
#define	cpl_test_memory_is_empty()
	Test if the memory system is empty. More...
#define	cpl_test_noneq(first, second)
	Test if two integer expressions are not equal. More...
#define	cpl_test_noneq_ptr(first, second)
	Test if two pointer expressions are not equal. More...
#define	cpl_test_noneq_string(first, second)
	Test if two strings are not equal. More...
#define	cpl_test_nonnull(pointer)
	Test if a pointer is non-NULL. More...
#define	cpl_test_null(pointer)
	Test if a pointer is NULL and update an internal counter on failure. More...
#define	cpl_test_polynomial_abs(first, second, tolerance)
	Test if two polynomials are identical within a given (absolute) tolerance. More...
#define	cpl_test_rel(first, second, tolerance)
	Test if two numerical expressions are within a given relative tolerance. More...
#define	cpl_test_vector_abs(first, second, tolerance)
	Test if two vectors are identical within a given (absolute) tolerance. More...
#define	cpl_test_zero(zero)
	Evaluate an expression and increment an internal counter if non-zero. More...

Functions
int	cpl_test_end (cpl_size nfail)
	Finalize CPL and unit-testing environment and report any failures. More...
size_t	cpl_test_get_bytes_image (const cpl_image *self)
	Get the amount of storage [bytes] for the CPL object. More...
size_t	cpl_test_get_bytes_imagelist (const cpl_imagelist *self)
	Get the amount of storage [bytes] for the CPL object. More...
size_t	cpl_test_get_bytes_matrix (const cpl_matrix *self)
	Get the amount of storage [bytes] for the CPL object. More...
size_t	cpl_test_get_bytes_vector (const cpl_vector *self)
	Get the amount of storage [bytes] for the CPL object. More...
cpl_size	cpl_test_get_failed (void)
	Get the number of failed CPL tests. More...
cpl_size	cpl_test_get_tested (void)
	Get the number of CPL tests performed. More...
double	cpl_test_get_walltime (void)
	Get the process wall-clock time, when available. More...

Detailed Description

This module provides various functions for unit testing.

Synopsis:

#include "cpl_test.h"

Macro Definition Documentation

#define cpl_test

(

bool

)

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_abs	(		first,
			second,
			tolerance
	)

Test if two numerical expressions are within a given absolute tolerance.

Parameters

first	The first value in the comparison, side-effects are allowed
second	The second value in the comparison, side-effects are allowed
tolerance	A non-negative tolerance

Note

If the tolerance is negative, the test will always fail

See also

cpl_test()

Example of usage:

cpl_test_abs(computed, expected, DBL_EPSILON);

#define cpl_test_array_abs	(		first,
			second,
			tolerance
	)

Test if two numerical arrays are identical within a given (absolute) tolerance.

Parameters

first	The first array in the comparison
second	The second array of identical size in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_abs()

Note

The test will fail if one or both the arrays are NULL or of a non-numerical type

#define cpl_test_assert

(

bool

)

Evaluate an expression and terminate the process 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_test_assert(p != NULL);
    cpl_test(*p);

    return cpl_test_end(0);
}

#define cpl_test_eq	(		first,
			second
	)

Test if two integer expressions are equal.

Parameters

first	The first value in the comparison, side-effects are allowed
second	The second value in the comparison, side-effects are allowed

See also

cpl_test()

Returns

void

Example of usage:

cpl_test_eq(computed, expected);

For comparison of floating point values, see cpl_test_abs() and cpl_test_rel().

#define cpl_test_eq_error	(		first,
			second
	)

Test if two error expressions are equal and reset the CPL error code.

Parameters

first	The first value in the comparison
second	The second value in the comparison

See also

cpl_test_error

Note

If the two CPL error expressions are equal they will also be tested against the current CPL error code. After the test(s), the CPL errorstate is reset.

Example of usage:

cpl_error_code error = my_func(NULL);

// my_func(NULL) is expected to return CPL_ERROR_NULL_INPUT
// and to set the same error code
cpl_test_eq_error(error, CPL_ERROR_NULL_INPUT);

// The errorstate has been reset.

error = my_func(p); // Successful call
cpl_test_eq_error(error, CPL_ERROR_NONE);

#define cpl_test_eq_mask	(		first,
			second
	)

Test if two CPL masks are equal.

Parameters

first	The first mask or NULL of the comparison
second	The second mask or NULL of the comparison

Note

One or two NULL pointer(s) is considered a failure.

Example of usage:

cpl_test_eq_mask(computed, expected);

#define cpl_test_eq_ptr	(		first,
			second
	)

Test if two pointer expressions are equal.

Parameters

first	The first value in the comparison, side-effects are allowed
second	The second value in the comparison, side-effects are allowed

See also

cpl_test_eq()

Returns

void

Example of usage:

cpl_test_eq_ptr(computed, expected);

#define cpl_test_eq_string	(		first,
			second
	)

Test if two strings are equal.

Parameters

first	The first string or NULL of the comparison
second	The second string or NULL of the comparison

Note

One or two NULL pointer(s) is considered a failure.

Example of usage:

cpl_test_eq_string(computed, expected);

#define cpl_test_error

(

error

)

Test and reset the CPL error code.

Parameters

error

The expected CPL error code (incl. CPL_ERROR_NONE)

See also

cpl_test()

Note

After the test, the CPL errorstate is reset

Returns

void

Example of usage:

cpl_test( my_func(NULL) ); // my_func(NULL) is expected to return non-zero

cpl_test_error(CPL_ERROR_NULL_INPUT); // ... and to set this error code

// The errorstate has been reset.

cpl_test( !my_func(p) ); // my_func(p) is expected to return zero

#define cpl_test_errorstate

(

errorstate

)

Test and if necessary reset the CPL errorstate.

Parameters

errorstate

The expected CPL errorstate

See also

cpl_test()

Note

After the test, the CPL errorstate is set to the provided state

Returns

void

This function is useful for verifying that a successful call to a function does not modify any pre-existing errors.

Example of usage:

const cpl_error_code error = cpl_error_set(cpl_func, CPL_ERROR_EOL);
cpl_errorstate prestate = cpl_errorstate_get();
const cpl_error_code ok = my_func(); // Expected to succeed

cpl_test_errorstate(prestate); // Verify that no additional errors occurred
cpl_test_error(CPL_ERROR_EOL); // Reset error
cpl_test_eq(ok, CPL_ERROR_NONE); // Verify that my_func() succeeded

#define cpl_test_fits

(

fitsfile

)

Test if a file is valid FITS using an external verification utility.

Parameters

fitsfile

The file to verify, NULL causes failure

Note

The external verification utility is specified with the environemt variable CPL_TEST_FITS, if is not set the test will pass on any non-NULL file.

Example of usage:

export CPL_TEST_FITS=/usr/local/bin/fitsverify

cpl_test_fits(fitsfile);

#define cpl_test_image_abs	(		first,
			second,
			tolerance
	)

Test if two images are identical within a given (absolute) tolerance.

Parameters

first	The first image in the comparison
second	The second image of identical size in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_abs()

Note

The test will fail if one or both the images are NULL

#define cpl_test_image_rel	(		first,
			second,
			tolerance
	)

Test if two images are identical within a given (relative) tolerance.

Parameters

first	The first image in the comparison
second	The second image of identical size in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_rel()

Note

The test will fail if one or both the images are NULL

For each pixel position the two values x, y must pass the test: |x - y| <= tol * min(|x|, |y|). This definition is chosen since it is commutative and meaningful also for zero-valued pixels.

#define cpl_test_imagelist_abs	(		first,
			second,
			tolerance
	)

Test if two imagelists are identical within a given (absolute) tolerance.

Parameters

first	The first imagelist in the comparison
second	The second imagelist of identical size in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_image_abs()

Note

The test will fail if one or both the imagelists are NULL

#define cpl_test_init	(		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
	)

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
	)

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_matrix_abs	(		first,
			second,
			tolerance
	)

Test if two matrices are identical within a given (absolute) tolerance.

Parameters

first	The first matrix in the comparison
second	The second matrix of identical size in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_abs()

Note

The test will fail if one or both the matrices are NULL

#define cpl_test_memory_is_empty

(

)

Test if the memory system is empty.

See also

cpl_memory_is_empty()

Deprecated:

Called by cpl_test_end()

#define cpl_test_noneq	(		first,
			second
	)

Test if two integer expressions are not equal.

Parameters

first	The first value in the comparison, side-effects are allowed
second	The second value in the comparison, side-effects are allowed

See also

cpl_test_eq()

Returns

void

Example of usage:

cpl_test_noneq(computed, wrong);

#define cpl_test_noneq_ptr	(		first,
			second
	)

Test if two pointer expressions are not equal.

Parameters

first	The first value in the comparison, side-effects are allowed
second	The second value in the comparison, side-effects are allowed

See also

cpl_test_eq_ptr()

Returns

void

Example of usage:

cpl_test_noneq_ptr(computed, wrong);

#define cpl_test_noneq_string	(		first,
			second
	)

Test if two strings are not equal.

Parameters

first	The first string or NULL of the comparison
second	The second string or NULL of the comparison

Note

One or two NULL pointer(s) is considered a failure.

Example of usage:

cpl_test_noneq_string(computed, expected);

#define cpl_test_nonnull

(

pointer

)

Test if a pointer is non-NULL.

Parameters

pointer

The pointer to check, side-effects are allowed

See also

cpl_test_nonnull()

Returns

void

Example of usage:

cpl_test_nonnull(pointer); // pointer is expected to be non-NULL

#define cpl_test_null

(

pointer

)

Test if a pointer is NULL and update an internal counter on failure.

Parameters

pointer

The NULL-pointer to check, side-effects are allowed

See also

cpl_test()

Returns

void

Example of usage:

cpl_test_null(pointer); // pointer is expected to be NULL

#define cpl_test_polynomial_abs	(		first,
			second,
			tolerance
	)

Test if two polynomials are identical within a given (absolute) tolerance.

Parameters

first	The first polynomial in the comparison
second	The second polynomial in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_abs()

Note

The test will fail if one or both the polynomials are NULL

#define cpl_test_rel	(		first,
			second,
			tolerance
	)

Test if two numerical expressions are within a given relative tolerance.

Parameters

first	The first value in the comparison, side-effects are allowed
second	The second value in the comparison, side-effects are allowed
tolerance	A non-negative tolerance

Note

If the tolerance is negative or if one but not both of the two values is zero, the test will always fail. If both values are zero, the test will succeed for any non-negative tolerance. The test is commutative in the two values.

See also

cpl_test()

The test is carried out by comparing the absolute value of the difference abs (first - second) to the product of the tolerance and the minimum of the absolute value of the two values, tolerance * min(abs(first), abs(second)) (The test is implemented like this to avoid division with a number that may be zero.

Example of usage:

cpl_test_rel(computed, expected, 0.001);

#define cpl_test_vector_abs	(		first,
			second,
			tolerance
	)

Test if two vectors are identical within a given (absolute) tolerance.

Parameters

first	The first vector in the comparison
second	The second vector of identical size in the comparison
tolerance	A non-negative tolerance

Returns

void

See also

cpl_test_abs()

Note

The test will fail if one or both the vectors are NULL

#define cpl_test_zero

(

zero

)

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

Referenced by cpl_test_end().

Function Documentation

int cpl_test_end

(

cpl_size

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);
}

References cpl_end(), cpl_error_get_code(), CPL_ERROR_NONE, cpl_errorstate_dump(), cpl_free(), cpl_memory_dump(), cpl_memory_is_empty(), cpl_msg_debug(), cpl_msg_error(), cpl_msg_get_level(), cpl_msg_get_log_name(), cpl_msg_indent_less(), cpl_msg_indent_more(), cpl_msg_info(), cpl_msg_set_level(), cpl_msg_warning(), cpl_test_get_walltime(), and cpl_test_zero.

size_t cpl_test_get_bytes_image

(

const cpl_image *

self

)

Get the amount of storage [bytes] for the CPL object.

Parameters

self	The CPL object

Returns

The size in bytes

Note

Passing NULL is allowed and will return zero

See also

cpl_test_get_bytes_vector

References cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), and cpl_type_get_sizeof().

Referenced by cpl_test_get_bytes_imagelist().

size_t cpl_test_get_bytes_imagelist

(

const cpl_imagelist *

self

)

Get the amount of storage [bytes] for the CPL object.

Parameters

self	The CPL object

Returns

The size in bytes

Note

Passing NULL is allowed and will return zero

See also

cpl_test_get_bytes_vector

References cpl_imagelist_get_const(), cpl_imagelist_get_size(), and cpl_test_get_bytes_image().

size_t cpl_test_get_bytes_matrix

(

const cpl_matrix *

self

)

Get the amount of storage [bytes] for the CPL object.

Parameters

self	The CPL object

Returns

The size in bytes

Note

Passing NULL is allowed and will return zero

See also

cpl_test_get_bytes_vector

References cpl_matrix_get_ncol(), and cpl_matrix_get_nrow().

size_t cpl_test_get_bytes_vector

(

const cpl_vector *

self

)

Get the amount of storage [bytes] for the CPL object.

Parameters

self	The CPL object

Returns

The size in bytes

Note

Passing NULL is allowed and will return zero

Example of usage:

int my_benchmark (void)
{
    const size_t storage = cpl_test_get_bytes_vector(mydata);
    double walltime, tstop;
    const double tstart = cpl_test_get_walltime();

    myfunc(mydata);

    tstop = cpl_test_get_walltime();

    walltime = tstop - tstart;

    if (walltime > 0.0) {
      cpl_msg_info(cpl_func, "Processing rate: %g",
                   (double)storage/walltime);
    }
}

References cpl_vector_get_size().

cpl_size cpl_test_get_failed

(

void

)

Get the number of failed CPL tests.

Returns

The count of failed tests

See also

cpl_test_get_tested()

Example of usage:

void my_tester (void)
{
    const cpl_size prefailed = cpl_test_get_failed();

    cpl_test(mytest());

    if (cpl_test_get_failed() > prefailed) {
      cpl_msg_info(cpl_func, "The function mytest() failed!");
    }
}

cpl_size cpl_test_get_tested

(

void

)

Get the number of CPL tests performed.

Returns

The test count

See also

cpl_test_get_failed()

double cpl_test_get_walltime

(

void

)

Get the process wall-clock time, when available.

Returns

The process wall-clock time in seconds.

Note

Will always return 0 if clock_gettime() and gettimeofday() are unavailable or failing

See also

clock_gettime(), gettimeofday()

Example of usage:

int my_benchmark (void)
{
    double walltime, tstop;
    const double tstart = cpl_test_get_walltime();

    myfunc();

    tstop = cpl_test_get_walltime();

    walltime = tstop - tstart;

    cpl_msg_info(cpl_func, "The call took %g seconds of wall-clock time",
                 walltime);

}

Referenced by cpl_test_end().