Assert Overview

Purpose

The goal of this module is to provide functions to check the behavior of some other functions, for example in unit tests. We emphasize the use of consistent tools for testing numerical issues, with the goal of testing numerical algorithms more easily. In particular, we provide a comparison function for two floating point numbers, which allows to check that two numbers are "numerically almost equal", i.e. that the relative error is small.

Quick start

The assert_checktrue function allows to check that a matrix of booleans is true. The following assertion fails and generate an error.

assert_checktrue ( [%t %F] );

The assert_checkequal function allows to check that two variables are equal. The following assertion is a success and runs silently.

assert_checkequal ( %nan , %nan );

The assert_checkalmostequal function allows to check that a computed result is close to an expected result. In the following script, we check that computed=1.23456 is close to expected=1.23457, but that 11 digits have been lost with respect to the maximum achievable accuracy.

assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e11*%eps );

A particular feature of the module is that all the assert functions have the same output arguments. This feature allows to get a uniform behavior and supports a simple management of the errors in the case where an assertion is not satisfied. For example, consider the function assert_checktrue, which syntax is:

flag = assert_checktrue ( condition )
flag = assert_checktrue ( condition )
[flag,errmsg] = assert_checktrue ( condition )

If any entry in condition is false,

• if the errmsg output variable is not used, an error is generated,

• if the errmsg output variable is used, no error is generated.

The reason of this behavior is to be able to use assertions both in scripts (e.g. unit tests) and in functions. For example, in a typical unit test, the statement:

assert_checktrue ( 1+1==12 );

will generate an error, as expected. On the other hand, consider the situation where we want to insert assertions checkings in a function. We might want to manage the case where the assertion fails. In this case, the syntax assert_checktrue ( condition ) generates an error, which interrupts the execution. We may want to avoid this, by catching the error generated by assert_checktrue. This requires to use the execstr function and may lead to the following source code.

function y=myfunction(x)
    ierr=execstr("assert_checktrue ( x==12 )","errcatch");
    if ( ierr <> 0 ) then
        error("Oups!")
    end
    y=x
endfunction

In this case, we suggest to use instead the calling sequence [flag,errmsg] = assert_checktrue ( condition ), which simplifies the processing of the error.

function y=myfunction2(x)
    [flag,errmsg] = assert_checktrue ( x==12 )
    if ( ~flag ) then
        error("Oups!")
    end
    y=x
endfunction

History