TEST_ERROR

Test if an error is successfully thrown.

Back to Simple Unit Testing Toolbox Documentation.

Contents

Syntax

TEST_ERROR(f)
TEST_ERROR(f,args)
TEST_ERROR(__,name,print,color)
outputs = TEST_ERROR(__)

Description

TEST_ERROR(f) tests if the function f (that has no inputs) successfully throws an error. Note that this syntax is only applicable in the trivial case where a function with no inputs is purposefully defined such that it fails every time that it is evaluated.

TEST_ERROR(f,args) tests if the function f successfully throws an error when subject to the input arguments args.

TEST_ERROR(...,name,print,color) does the same as the syntaxes above, but also allows the user to specify a test name, whether or not to print the test results to the Command Window, and whether or not to print those test results in color. This syntax is primarily used when defining unit test classes.

outputs = TEST_ERROR(...) also returns the test outputs. Again, this syntax is primarily used when defining unit test classes.

Inputs

Variable Description Format
f function handle assigned to function you want to test 1×1
function_handle
args (OPTIONAL) input arguments to f (defaults to empty cell array) cell array
name (OPTIONAL) test name (defaults to empty string) char array
print (OPTIONAL) true if test result should be printed to Command Window, false otherwise (defaults to true) 1×1
logical
color (OPTIONAL) true if test result should be printed in color, false otherwise (defaults to true) 1×1
logical

Outputs

Variable Description Format
output test outputs

Field Description Format
passed true if test passed, false otherwise 1×1
logical
result string storing result of test char array
message string storing additional diagnostic message char array
1×1
struct

Example #1: Passed test.

MATLAB's mod function requires to inputs Therefore, we expect mod to throw an error if only 1 input is provided. First, we assign a function handle to the mod function.

f = @(x,y) mod(x,y);

Next, let's test to make sure the mod function throws an error if only one input is provided. Since we are testing if the function throws an error, the test should pass as the mod function should throw an error when given only one input.

TEST_ERROR(f,{5});

Passed.

Note that we don't have to define the function handle separately; we can also define it within the call on TEST_ERROR.

TEST_ERROR(@(x,y)mod(x,y),{5});

Passed.

Example #2: Failed test.

Let's once again use MATLAB's mod function (which requires 2 inputs) as an example. This time around, let's correctly pass it 2 real-valued inputs, as required. Since we are now passing 2 real-valued inputs, the mod function should execute correctly, and testing for an error should result in a failed test (since the function will not throw an error).

TEST_ERROR(@(x,y)mod(x,y),{5,5});

FAILED.
    >>>> Function did not throw an error.

Example #3: User-defined function raising custom error.

Let's consider a user-defined divide_safe function that safeguards against division by 0. If we try dividing 5 by 0 using the divide_safe function, we should get an error.

TEST_ERROR(@(a,b)divide_safe(a,b),{5,0});

function c = divide_safe(a,b)
    if b == 0
        error('Divide-by-zero error.')
    end
    c = a/b;
end

Passed.

See also

TEST_NO_ERROR


Published with MATLAB® R2022a