Main Content

matlab.unittest.constraints.IssuesWarnings Class

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

Test if function issues specified warnings

expand all in page

Description

The matlab.unittest.constraints.IssuesWarnings class provides a constraint to test if a function handle issues specified warnings.

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

Creation

Description

c = matlab.unittest.constraints.IssuesWarnings(identifiers) creates a constraint to test if a function handle issues warnings with the specified identifiers. The constraint is satisfied if the actual value is a function handle that issues the specified warnings when the testing framework invokes it. By default, the constraint ignores the number of times the warnings occur, the order in which they occur, and whether the function handle issues any unspecified warnings.

example

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

example

Input Arguments

expand all

Warning identifiers, specified as a string array or cell array of character vectors.

This argument sets the ExpectedWarnings property.

Example: "MATLAB:MKDIR:DirectoryExists"

Example: ["MyComponent:FirstID" "MyComponent:SecondID"]

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.IssuesWarnings(identifiers,WhenNargoutIs=2)

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

Example: c = matlab.unittest.constraints.IssuesWarnings(identifiers,"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 property.

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

Option to respect the set of expected warnings when comparing the issued and expected warnings, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the constraint is not satisfied if the function handle issues any warnings that are not listed in identifiers. By default, the constraint ignores any unexpected warnings that the function handle issues.

This argument sets the RespectSet property.

Option to respect the count when comparing the issued and expected warnings, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the constraint is not satisfied if the number of times that the function handle issues an expected warning differs from the number of times that the warning is listed in identifiers. By default, the constraint ignores the number of times the warnings occur.

This argument sets the RespectCount property.

Option to respect the order when comparing the issued and expected warnings, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the constraint is not satisfied if the order in which the function handle issues the warnings does not match the order in which they are listed in identifiers. By default, the constraint ignores the order in which the warnings occur.

The constraint determines the order of a given warning profile by trimming it to a profile with no repeated adjacent warnings. For example, the warning profile {id1,id1,id2,id3,id3,id3,id1,id1} becomes {id1,id2,id3,id1} when testing for order. Additionally, the constraint ignores any issued warnings that are not listed in identifiers when testing for order.

This argument sets the RespectOrder property.

Option to test for an exact match when comparing the issued and expected warnings, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the constraint is not satisfied if the issued and expected warning profiles are not exactly the same. By default, the constraint does not perform exact comparisons.

This argument sets the Exact property.

Properties

expand all

Expected warning identifiers, returned as a cell array of character vectors. Specify the value of this property during creation of the constraint.

This property is set by the identifiers input argument.

Attributes:

GetAccess
public
SetAccess
immutable

Outputs produced by the function handle when the testing framework invokes it, returned as a cell array.

Attributes:

GetAccess
public
SetAccess
private

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

Option to respect the set of expected warnings when comparing the issued and expected warnings, returned as a 0 or 1 of data type logical. By default, the constraint ignores any unexpected warnings that the function handle issues.

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

Attributes:

GetAccess
public
SetAccess
private

Option to respect the count when comparing the issued and expected warnings, returned as a 0 or 1 of data type logical. By default, the constraint ignores the number of times the warnings occur.

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

Attributes:

GetAccess
public
SetAccess
private

Option to respect the order when comparing the issued and expected warnings, returned as a 0 or 1 of data type logical. By default, the constraint ignores the order in which the warnings occur.

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

Attributes:

GetAccess
public
SetAccess
private

Option to test for an exact match when comparing the issued and expected warnings, returned as a 0 or 1 of data type logical. By default, the constraint does not perform exact comparisons.

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

Attributes:

GetAccess
public
SetAccess
private

Examples

collapse all

Test if the actual value is a function handle that issues a specified warning.

Import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IssuesWarnings

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

This example assumes that your current folder has a subfolder named myFolder. Create the subfolder if it does not exist.

[~,~] = mkdir("myFolder")

The mkdir function issues a warning if it is used to create a folder that already exists. Return the warning identifier.

mkdir myFolder
[~,id] = lastwarn
Warning: Directory already exists. 

id =

    'MATLAB:MKDIR:DirectoryExists'

Verify that if mkdir is called to create an existing folder, it warns and the warning has the identifier "MATLAB:MKDIR:DirectoryExists".

testCase.verifyThat(@() mkdir("myFolder"), ...
    IssuesWarnings("MATLAB:MKDIR:DirectoryExists"))
Verification passed.

Test a function handle that does not issue any warnings. The test fails.

testCase.verifyThat(@dir,IssuesWarnings("MATLAB:MKDIR:DirectoryExists"))
.         ..        myFolder  

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IssuesWarnings failed.
    --> The function handle did not issue a correct warning profile.
        The expected warning profile ignores:
          Set
          Count
          Order
        --> The function handle did not issue any warnings.
        
        Expected Warning Profile:
            --> 'MATLAB:MKDIR:DirectoryExists'
    
    Evaluated Function:
      function_handle with value:
    
        @dir

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

testCase.verifyThat(5,IssuesWarnings("MATLAB:MKDIR:DirectoryExists"))
Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IssuesWarnings failed.
    --> The value must be an instance of the expected type.
        
        Actual Class:
            double
        Expected Type:
            function_handle
    
    Actual Value:
         5

Test a function handle that can issue multiple warnings by using the IssuesWarnings constraint.

In a file in your current folder, create the myfun function. The function takes as input an array of warning identifiers and issues warnings corresponding to the specified identifiers.

function myfun(id)
arguments
    id {mustBeText,mustBeNonempty}
end

for i = 1:numel(id)
    warning(string(id(i)),"Warning!")
end
end

Import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IssuesWarnings

To experiment with the IssuesWarnings constraint, create several warning identifiers and a test case for interactive testing.

id1 = "MyComponent:FirstID";
id2 = "MyComponent:SecondID";
id3 = "MyComponent:ThirdID";

testCase = TestCase.forInteractiveUse;

Verify that myfun issues a warning when called with a particular identifier.

testCase.verifyThat(@() myfun(id1),IssuesWarnings(id1))
Verification passed.

Verify that the constraint is not satisfied if myfun issues an unexpected warning.

testCase.verifyThat(@() myfun(id1),IssuesWarnings(id2))
Warning: Warning! 
...

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IssuesWarnings failed.
    --> The function handle did not issue a correct warning profile.
        The expected warning profile ignores:
          Set
          Count
          Order
        --> The function handle did not issue the correct warning(s).
            
            Missing Warning(s):
                --> 'MyComponent:SecondID'
        
        Actual Warning Profile:
            --> 'MyComponent:FirstID'
        Expected Warning Profile:
            --> 'MyComponent:SecondID'
    
    Evaluated Function:
      function_handle with value:
    
        @()myfun(id1)

Test the function handle when it issues several warnings. This test passes because myfun issues both the expected warnings.

testCase.verifyThat(@() myfun([id1 id3 id2 id1]), ...
    IssuesWarnings([id2 id1]))
Verification passed.

Test again while respecting the set of expected warnings. The test fails because, in addition to the expected warnings, myfun issues the id3 warning.

testCase.verifyThat(@() myfun([id1 id3 id2 id1]), ...
    IssuesWarnings([id2 id1],"RespectingSet",true))
Warning: Warning! 
...

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IssuesWarnings failed.
    --> The function handle did not issue a correct warning profile.
        The expected warning profile respects:
          Set
        The expected warning profile ignores:
          Count
          Order
        --> The function handle did not issue the correct warning(s).
            
            Extra Warning(s):
                --> 'MyComponent:ThirdID'
        
        Actual Warning Profile:
            --> 'MyComponent:FirstID'
            --> 'MyComponent:ThirdID'
            --> 'MyComponent:SecondID'
            --> 'MyComponent:FirstID'
        Expected Warning Profile:
            --> 'MyComponent:SecondID'
            --> 'MyComponent:FirstID'
    
    Evaluated Function:
      function_handle with value:
    
        @()myfun([id1,id3,id2,id1])

Test if myfun issues the specified warnings while respecting the warning count. The test passes because the function handle issues each expected warning the same number of times as in the expected warning profile.

testCase.verifyThat(@() myfun([id2 id1 id3 id2]), ...
    IssuesWarnings([id1 id2 id2],"RespectingCount",true))
Verification passed.

Verify that myfun issues the specified warnings while respecting the warning order.

testCase.verifyThat(@() myfun([id1 id2 id2 id3]), ...
    IssuesWarnings([id1 id2],"RespectingOrder",true))
Verification passed.

Test if myfun issues the specified warnings while respecting the warning set, count, and order. The test passes.

testCase.verifyThat(@() myfun([id1 id1 id2 id1]), ...
    IssuesWarnings([id1 id2 id1 id1], ...
    "RespectingSet",true,"RespectingCount",true,"RespectingOrder",true))
Verification passed.

In the previous test, even though the function handle satisfies the constraint while respecting the warning set, count, and order, the issued and expected warning profiles are not exactly the same. If you test for an exact match, the constraint is not satisfied.

testCase.verifyThat(@() myfun([id1 id1 id2 id1]), ...
    IssuesWarnings([id1 id2 id1 id1],"Exactly",true))
Warning: Warning! 
...

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IssuesWarnings failed.
    --> The function handle did not issue a correct warning profile.
        The expected warning profile must match exactly.
        --> The function handle did not issue the exact warning profile expected.
        
        Actual Warning Profile:
            --> 'MyComponent:FirstID'
            --> 'MyComponent:FirstID'
            --> 'MyComponent:SecondID'
            --> 'MyComponent:FirstID'
        Expected Warning Profile:
            --> 'MyComponent:FirstID'
            --> 'MyComponent:SecondID'
            --> 'MyComponent:FirstID'
            --> 'MyComponent:FirstID'
    
    Evaluated Function:
      function_handle with value:
    
        @()myfun([id1,id1,id2,id1])

Version History

Introduced in R2013a

See Also

Functions

Classes