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(
creates a constraint to test if a function handle throws the error specified by
identifier
)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(
specifies options using one or more name-value arguments. For example, identifier
,Name,Value
)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
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
See Also
Functions
Classes
Objects
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)