# Assert Overview

An overview of the Assert module.

## 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 calling sequence 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 calling sequence `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

5.4.0
Function introduced