matlab.unittest.constraints.Throws - Test if function throws specified error - MATLAB (original) (raw)

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](#mw%5F0b0c6b12-9e97-4ad3-8866-e90d508a6ef8)) creates a constraint to test if a function handle throws the error specified byidentifier. The constraint is satisfied if the actual value is a function handle that throws the specified error when the testing framework invokes it.

example

c = matlab.unittest.constraints.Throws([identifier](#mw%5F0b0c6b12-9e97-4ad3-8866-e90d508a6ef8),[Name,Value](#namevaluepairarguments)) 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.

example

Input Arguments

expand all

Error identifier, specified as a string scalar, character vector, ormatlab.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](matlab.unittest.constraints.throws-class.html#bt2ir8b-1-ExpectedException) property.

Example: "MATLAB:UndefinedFunction"

Example: ?MException

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=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)

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

This argument sets the [Nargout](matlab.unittest.constraints.throws-class.html#bt2ir8b-1-Nargout) property.

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

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](matlab.unittest.constraints.throws-class.html#bt2ir8b-1-RequiredCauses) property.

Whether to respect the set of required causes, specified as a numeric or logical0 (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 theCausedBy name-value argument. By default, the constraint is insensitive to additional causes.

This argument sets the [RespectSet](matlab.unittest.constraints.throws-class.html#bt2ir8b-1-RespectSet) property.

Properties

expand all

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

This property is set by the identifier input argument.

Attributes:

GetAccess public
SetAccess immutable

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

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

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

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

Attributes:

GetAccess public
SetAccess private

Examples

collapse all

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"))

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))

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 becauserand 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))

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 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"))

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))

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