matlab.unittest.constraints.Throws class

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

Constraint specifying function handle that throws MException

expand all in page

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 ExpectedException property of the constraint 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.

Input Arguments

excep

Error identifier or meta.class representing the specific type of expected exception. If excep is a meta.class but does not derive from MException, the Throws constructor throws an 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 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 character vectors, a string array, or an array of 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

'RespectingSet'

Indicator whether to respect the set of expected causes, specified as false or true (logical 0 or 1). When this value is false, the instance ignores additional causes. When set to true, the instance is sensitive to additional causes. A true value means that the constraint is not satisfied if the expected exceptions contain causes that are not specified in the 'CausedBy' name-value pair.

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'.

RespectSet

Indicator if the constraint respects set elements, specified through the constructor via the name-value pair argument, 'RespectingSet'.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Examples

collapse all

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!');
causeBy1 = MException('causedBy:someOtherError:id','CausedByError!');
causeBy2 = MException('causedBy:yetAnotherError:id','AnotherCausedByError!');
me  = me.addCause(causeBy1);
me  = me.addCause(causeBy2);

testCase.verifyThat(@() me.throw, Throws('TOP:error:id','CausedBy',...
    {'causedBy:someOtherError:id'}))
Interactive verification passed.

Check that the exception does not include any additional causes than the ones specified by 'CausedBy'.

testCase.verifyThat(@() me.throw, Throws('TOP:error:id','CausedBy',...
    {'causedBy:someOtherError:id'},'RespectingSet',true))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
Throws failed.
--> The following causes were unexpectedly found in the exception tree:
    --> 'causedBy:yetAnotherError:id'

Actual Error Report:
    Error using @()me.throw
    TopLevelError!
    
    Caused by:
        CausedByError!
        AnotherCausedByError!
    
Actual Error Structure:
    ?MException 'TOP:error:id'
    --> ?MException 'causedBy:someOtherError:id'
    --> ?MException 'causedBy:yetAnotherError:id'

Evaluated Function:
        @()me.throw

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 if the actual value is not a function handle, the constraint is not satisfied.

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 if the function does not throw an exception, the constraint is not satisfied.

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

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

Evaluated Function:
        @rand
Assumption failed.

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

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

---------------------
Framework Diagnostic:
---------------------
Throws failed.
--> The function threw the wrong exception.
    
    Actual Exception:
        'SOME:id'
    Expected Exception:
        'OTHER:id'

Actual Error Report:
    Error using @()error('SOME:id','Error!')
    Error!
    
Evaluated Function:
        @()error('SOME:id','Error!')

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

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:
    --> 'causedBy:someOtherError:id'

Actual Error Report:
    Error using @()error('TOP:error:id','TopLevelError!')
    TopLevelError!
    
Actual Error Structure:
    ?MException 'TOP:error:id'

Evaluated Function:
        @()error('TOP:error:id','TopLevelError!')

See Also

| | |

Introduced in R2013a

MATLAB Documentation

Support