Common Pipeline Library Reference Manual  6.1.1
Defines | Functions
Unit testing functions

Defines

#define cpl_test(bool)
 Evaluate an expression and increment an internal counter if zero.
#define cpl_test_abs(first, second, tolerance)
 Test if two numerical expressions are within a given absolute tolerance.
#define cpl_test_array_abs(first, second, tolerance)
 Test if two numerical arrays are identical within a given (absolute) tolerance.
#define cpl_test_assert(bool)
 Evaluate an expression and return if it fails.
#define cpl_test_eq(first, second)
 Test if two integer expressions are equal.
#define cpl_test_eq_error(first, second)
 Test if two error expressions are equal and reset the CPL error code.
#define cpl_test_eq_mask(first, second)
 Test if two CPL masks are equal.
#define cpl_test_eq_ptr(first, second)
 Test if two pointer expressions are equal.
#define cpl_test_eq_string(first, second)
 Test if two strings are equal.
#define cpl_test_error(error)
 Test and reset the CPL error code.
#define cpl_test_errorstate(errorstate)
 Test and if necessary reset the CPL errorstate.
#define cpl_test_fits(fitsfile)
 Test if a file is valid FITS using an external verification utility.
#define cpl_test_image_abs(first, second, tolerance)
 Test if two images are identical within a given (absolute) tolerance.
#define cpl_test_imagelist_abs(first, second, tolerance)
 Test if two imagelists are identical within a given (absolute) tolerance.
#define cpl_test_init(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_matrix_abs(first, second, tolerance)
 Test if two matrices are identical within a given (absolute) tolerance.
#define cpl_test_memory_is_empty()
 Test if the memory system is empty.
#define cpl_test_noneq(first, second)
 Test if two integer expressions are not equal.
#define cpl_test_noneq_ptr(first, second)
 Test if two pointer expressions are not equal.
#define cpl_test_noneq_string(first, second)
 Test if two strings are not equal.
#define cpl_test_nonnull(pointer)
 Test if a pointer is non-NULL.
#define cpl_test_null(pointer)
 Test if a pointer is NULL and update an internal counter on failure.
#define cpl_test_polynomial_abs(first, second, tolerance)
 Test if two polynomials are identical within a given (absolute) tolerance.
#define cpl_test_rel(first, second, tolerance)
 Test if two numerical expressions are within a given relative tolerance.
#define cpl_test_vector_abs(first, second, tolerance)
 Test if two vectors are identical within a given (absolute) tolerance.
#define cpl_test_zero(zero)
 Evaluate an expression and increment an internal counter if non-zero.

Functions

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

Detailed Description

This module provides various functions for unit testing.

Synopsis:
   #include "cpl_test.h"

Define Documentation

#define cpl_test (   bool)

Evaluate an expression and increment an internal counter if zero.

Parameters:
boolThe 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:
firstThe first value in the comparison, side-effects are allowed
secondThe second value in the comparison, side-effects are allowed
toleranceA 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:
firstThe first array in the comparison
secondThe second array of identical size in the comparison
toleranceA 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 return if it fails.

Parameters:
boolThe (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:
firstThe first value in the comparison, side-effects are allowed
secondThe 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:
firstThe first value in the comparison
secondThe 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:
firstThe first mask or NULL of the comparison
secondThe 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:
firstThe first value in the comparison, side-effects are allowed
secondThe 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:
firstThe first string or NULL of the comparison
secondThe 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:
errorThe 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:
errorstateThe 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:
fitsfileThe 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:
firstThe first image in the comparison
secondThe second image of identical size in the comparison
toleranceA 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_imagelist_abs (   first,
  second,
  tolerance 
)

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

Parameters:
firstThe first imagelist in the comparison
secondThe second imagelist of identical size in the comparison
toleranceA 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:
REPORTThe email address for the error message e.g. PACKAGE_BUGREPORT
LEVELThe 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:
valueThe number to test
toleranceThe 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:
valueThe number to test
toleranceThe 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:
firstThe first matrix in the comparison
secondThe second matrix of identical size in the comparison
toleranceA non-negative tolerance
Returns:
void
See also:
cpl_test_abs()
Note:
The test will fail if one or both the matrices are NULL

Test if the memory system is empty.

See also:
cpl_memory_is_empty()
#define cpl_test_noneq (   first,
  second 
)

Test if two integer expressions are not equal.

Parameters:
firstThe first value in the comparison, side-effects are allowed
secondThe 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:
firstThe first value in the comparison, side-effects are allowed
secondThe 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:
firstThe first string or NULL of the comparison
secondThe 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:
pointerThe 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:
pointerThe 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:
firstThe first polynomial in the comparison
secondThe second polynomial in the comparison
toleranceA 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:
firstThe first value in the comparison, side-effects are allowed
secondThe second value in the comparison, side-effects are allowed
toleranceA 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:
firstThe first vector in the comparison
secondThe second vector of identical size in the comparison
toleranceA 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:
zeroThe 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 ( cpl_size  nfail)

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

Parameters:
nfailThe 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);
    }
size_t cpl_test_get_bytes_image ( const cpl_image *  self)

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

Parameters:
selfThe CPL object
Returns:
The size in bytes
Note:
Passing NULL is allowed and will return zero
See also:
cpl_test_get_bytes_vector
size_t cpl_test_get_bytes_imagelist ( const cpl_imagelist *  self)

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

Parameters:
selfThe CPL object
Returns:
The size in bytes
Note:
Passing NULL is allowed and will return zero
See also:
cpl_test_get_bytes_vector
size_t cpl_test_get_bytes_matrix ( const cpl_matrix *  self)

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

Parameters:
selfThe CPL object
Returns:
The size in bytes
Note:
Passing NULL is allowed and will return zero
See also:
cpl_test_get_bytes_vector
size_t cpl_test_get_bytes_vector ( const cpl_vector *  self)

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

Parameters:
selfThe 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);
        }
    }
double cpl_test_get_walltime ( void  )

Get the process wall-clock time, when available (from gettimeofday())

Returns:
The process wall-clock time in seconds.
Note:
Will always return 0 if gettimeofday() is unavailable

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

    }