matlab.unittest.constraints.Throws class

Package: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.Constraint

Constraint specifying function handle that throws MException

Description

The Throws class creates a constraint that is satisfied only if the actual value is a function handle that throws a specific exception.

If the function throws an MException and the constraint's ExpectedException property is an error identifier, a qualification failure occurs if the actual MException thrown has a different identifier. Alternately, if the ExpectedException property is a meta.class, the constraint is not satisfied if the actual MException thrown does not derive from the ExpectedException.

Construction

outConstObj = Throws(excep) provides a constraint, outConstObj, specifying a function handle that throws a particular MException, excep.

outConstObj = Throws(excep,Name,Value) provides a constraint with additional options specified by one or more Name,Value pair arguments. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Input Arguments

excep

Error identifier or meta.class representing the specific type of expected exception. The Throws constructor throws an MException if excep is a meta.class but does not derive from MException.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'CausedBy'

Expected causes, specified as a cell array of strings and/or meta.class instances.

The testing results in a qualification failure if any causes specified in CausedBy are not found within the cause tree.

Default: {}

'WhenNargoutIs'

Number of outputs the constraint should request when invoking the function handle, specified as a non-negative, real, scalar integer.

Default: 0

Properties

ExpectedException

Expected MException identifier or class. Set this read only property through the constructor via the excep input argument.

Nargout

Number of output arguments the instance uses when executing functions. Set this property through the constructor via the name-value pair argument, 'WhenNargoutIs'.

RequiredCauses

Expected causes for the function handle throwing an MException. Set this property through the constructor via the name-value pair argument, 'CausedBy'.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Examples

expand all

Instantiate Throws Constraint

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Verify that a function throws a specified error id.

testCase.verifyThat(@() error('SOME:error:id','Error!'), ...
    Throws('SOME:error:id'))
Interactive verification passed.

Verify that a function throws a specified exception class.

testCase.verifyThat(@() error('SOME:error:id','Error!'), ...
    Throws(?MException))
Interactive verification passed.

Verify that a function, when called with a specified number of outputs, throws a specified error.

testCase.verifyThat(@() disp('hi'), Throws('MATLAB:maxlhs', ...
    'WhenNargoutIs', 1))
Interactive verification passed.

Check causes by identifier.

me = MException('TOP:error:id','TopLevelError!');
causeBy = MException('causedBy:someOtherError:id','CausedByError!');
me  = me.addCause(causeBy);
testCase.verifyThat(@() me.throw, Throws('TOP:error:id','CausedBy', ...
    {'causedBy:someOtherError:id'}))
Interactive verification passed.

Check causes by class.

me = MException('TOP:error:id','TopLevelError!');
causeBy = MException('causedBy:someOtherError:id','CausedByError!');
me = me.addCause(causeBy);
testCase.verifyThat(@() me.throw, Throws('TOP:error:id','CausedBy', ...
    {?MException}))
Interactive verification passed.

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

testCase.fatalAssertThat(5, Throws('some:id'))
Interactive fatal assertion 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
Fatal assertion failed.

Verify that the constraint is not satisfied if the function does not throw an exception.

testCase.assumeThat(@rand, Throws(?MException))
Interactive assumption failed.

---------------------
Framework Diagnostic:
---------------------
Throws failed.
--> The function did not throw any exception.
    
    Expected Exception Type:
        MException

Evaluated Function:
        @rand
Assumption failed.

Verify that the constraint is not satisfied if the function issues a non-specified error identifier.

testCase.verifyThat(@() error('SOME:id'), Throws('OTHER:id'))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
Throws failed.
--> The function threw an exception with the wrong identifier.
    
    Actual Identifier:
        MATLAB:error:missingMessageArgument
    Expected Identifier:
        OTHER:id

Evaluated Function:
        @()error('SOME:id')

Verify that the constraint is not satisfied if the function throws an exception and the cause does not match the specified identifier.

testCase.verifyThat(@() error('TOP:error:id','TopLevelError!'), ...
    Throws('TOP:error:id','CausedBy',{'causedBy:someOtherError:id'}))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
Throws failed.
--> The following causes were not found in the exception tree:
    --> Identifier:
            causedBy:someOtherError:id

Evaluated Function:
        @()error('TOP:error:id','TopLevelError!')
Was this topic helpful?