matlab.unittest.constraints.Throws Class

Namespace: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.Constraint

Test if function throws specified error

Description

The matlab.unittest.constraints.Throws class provides a constraint to test if a function handle throws a specified error.

The matlab.unittest.constraints.Throws class is a handle class.

Creation

Description

c = matlab.unittest.constraints.Throws(identifier) creates a constraint to test if a function handle throws the error specified by identifier. The constraint is satisfied if the actual value is a function handle that throws the specified error when the testing framework invokes it.

c = matlab.unittest.constraints.Throws(identifier,Name,Value) specifies options using one or more name-value arguments. For example, c = matlab.unittest.constraints.Throws(identifier,"WhenNargoutIs",2) creates a constraint to test if a function handle throws the specified error when invoked with two output arguments.

Input Arguments

identifier — Error identifier

string scalar | character vector | matlab.metadata.Class instance

Error identifier, specified as a string scalar, character vector, or matlab.metadata.Class instance.

If identifier is a matlab.metadata.Class instance, then the constraint is satisfied if the thrown error is an instance of the specified class or one of its subclasses.

This argument sets the ExpectedException property.

Example: "MATLAB:UndefinedFunction"

Example: ?MException

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: c = matlab.unittest.constraints.Throws(identifier,WhenNargoutIs=2)

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: c = matlab.unittest.constraints.Throws(identifier,"WhenNargoutIs",2)

WhenNargoutIs — Number of outputs

0 (default) | nonnegative integer scalar

Number of outputs that the constraint requests when invoking the function handle, specified as a nonnegative integer scalar.

This argument sets the Nargout property.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

CausedBy — Required causes of error

string array | cell array of character vectors | array of matlab.metadata.Class instances

Required causes of the expected error, specified as a string array, cell array of character vectors, or array of matlab.metadata.Class instances. If any of the specified causes is missing when the function handle throws the error, the constraint is not satisfied.

This argument sets the RequiredCauses property.

RespectingSet — Whether to respect set of required causes

false or 0 (default) | true or 1

Whether to respect the set of required causes, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, the constraint is not satisfied if the expected error contains causes that are not specified by the CausedBy name-value argument. By default, the constraint is insensitive to additional causes.

This argument sets the RespectSet property.

Properties

ExpectedException — Expected error identifier

character vector | matlab.metadata.Class instance

Expected error identifier, returned as a character vector or matlab.metadata.Class instance.

This property is set by the identifier input argument.

Attributes:

GetAccess	public
SetAccess	immutable

Nargout — Number of outputs

0 (default) | nonnegative integer scalar

Number of outputs that the constraint requests when invoking the function handle, returned as a nonnegative integer scalar.

This property is set by the WhenNargoutIs name-value argument.

Attributes:

GetAccess	public
SetAccess	private

RequiredCauses — Required causes of error

cell array of character vectors | array of matlab.metadata.Class instances

Required causes of the expected error, returned as a cell array of character vectors or an array of matlab.metadata.Class instances.

This property is set by the CausedBy name-value argument.

Attributes:

GetAccess	public
SetAccess	private

RespectSet — Whether to respect set of required causes

0 (default) | 1

Whether to respect the set of required causes, returned as a 0 or 1 of data type logical.

This property is set by the RespectingSet name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Examples

Test for Specified Errors

Test if the actual value is a function handle that throws a specified error.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.Throws

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Verify that the error function throws an error with the expected identifier.

testCase.verifyThat(@() error("SOME:error:id","Error!"), ...
    Throws("SOME:error:id"))

Verification passed.

Test again by passing the constraint a matlab.metadata.Class instance instead of a string. The test passes.

testCase.verifyThat(@() error("SOME:error:id","Error!"), ...
    Throws(?MException))

Verification passed.

Verify that the test fails if the actual and expected error identifiers do not match.

testCase.verifyThat(@() error("SOME:error:id","Error!"), ...
    Throws("OTHER:error:id"))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    Throws failed.
    --> The function threw the wrong exception.
        
        Actual Exception:
            'SOME:error:id'
        Expected Exception:
            'OTHER:error:id'
    --> Actual Error Report:
            Error using @()error("SOME:error:id","Error!")
            Error!
    
    Evaluated Function:
      function_handle with value:
    
        @()error("SOME:error:id","Error!")

Test the rand function. The test fails because rand does not throw any errors.

testCase.verifyThat(@rand,Throws(?MException))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    Throws failed.
    --> The function did not throw any exception.
        
        Expected Exception:
            ?MException
    
    Evaluated Function:
      function_handle with value:
    
        @rand

The disp function does not return any outputs. Verify that calling disp with one output argument throws a specified error.

testCase.verifyThat(@() disp("Hello World!"), ...
    Throws("MATLAB:maxlhs","WhenNargoutIs",1))

Verification passed.

Verify that the Throws constraint is not satisfied if the actual value is not a function handle.

testCase.verifyThat(5,Throws("SOME:error:id"))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    Throws failed.
    --> The value must be an instance of the expected type.
        
        Actual Class:
            double
        Expected Type:
            function_handle
    
    Actual Value:
         5

Test for Causes of Error

Test for causes of an error by using the Throws constraint.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.Throws

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Create an MException object, me, with two causes of errors, cause1 and cause2.

me = MException("TOP:id","Top-Level Error!");
cause1 = MException("CAUSE1:id1","First Cause of Error!");
cause2 = MException("CAUSE2:id2","Second Cause of Error!");
me  = me.addCause(cause1);
me  = me.addCause(cause2);

Verify that cause1 is a cause of me when the framework throws it.

testCase.verifyThat(@() me.throw,Throws("TOP:id","CausedBy","CAUSE1:id1"))

Verification passed.

Test again by specifying the cause as a matlab.metadata.Class instance. The test passes. If me had no causes, the test would fail.

testCase.verifyThat(@() me.throw,Throws("TOP:id","CausedBy",?MException))

Verification passed.

Test if the error does not have any causes other than cause1. The test fails because cause2 also is a cause of the expected error.

testCase.verifyThat(@() me.throw, ...
    Throws("TOP:id","CausedBy","CAUSE1:id1","RespectingSet",true))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    Throws failed.
    --> The following causes were unexpectedly found in the exception tree:
        --> 'CAUSE2:id2'
    --> Actual Error Report:
            Error using @()me.throw
            Top Level Error!
            
            Caused by:
                First Cause of Error!
                Second Cause of Error!
    
    Actual Error Structure:
        ?MException 'TOP:id'
        --> ?MException 'CAUSE1:id1'
        --> ?MException 'CAUSE2:id2'
    
    Evaluated Function:
      function_handle with value:
    
        @()me.throw

Verify that the constraint is not satisfied if a specified cause does not belong to an error.

testCase.verifyThat(@() error("TOP:id","Top-Level Error!"), ...
    Throws("TOP:id","CausedBy","CAUSE1:id1"))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    Throws failed.
    --> The following causes were not found in the exception tree:
        --> 'CAUSE1:id1'
    --> Actual Error Report:
            Error using @()error("TOP:id","Top-Level Error!")
            Top-Level Error!
    
    Actual Error Structure:
        ?MException 'TOP:id'
    
    Evaluated Function:
      function_handle with value:
    
        @()error("TOP:id","Top-Level Error!")

Version History

Introduced in R2013a