matlab.unittest.constraints.IssuesWarnings class

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

Constraint specifying function that issues expected warning profile

expand all in page

Description

The IssuesWarnings class creates a constraint that issues an expected warning profile. The constraint is satisfied only if the actual value is a function handle that issues a specific set of warnings. You specify warnings using warning identifiers.

By default, the constraint only confirms that when the testing framework invokes the function handle, MATLAB® issues the specified set of warnings. It ignores the number of times the warnings are issued, in what order they are issued, and whether or not any unspecified warnings are issued. However, you can set parameters to respect the order, the count, and the warning set. Alternatively, you can specify the exact warning profile for comparison.

Construction

outConstObj = IssuesWarnings(warnArr) creates a constraint, outConstObj, specifying a function that issues expected warnings, warnArr.

outConstObj = IssuesWarnings(expVal,Name,Value) creates 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

warnArr

Warning identifiers expected when the testing framework invokes the function handle, specified as a cell array of warning identifiers. If warnArr is empty, the 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.

'Exactly'

Indicator if the value is a function handle that must issue a warning profile that is an exact match, specified as false or true (logical 0 or 1). When this value is false, the instance relies on specification of other parameters and default instance behavior to determine the strictness of its comparison. When set to true, the instance requires the warning profile to be exactly the same as the specified warning profile.

Default: false

'RespectingCount'

Indicator whether to respect element counts, specified as false or true (logical 0 or 1). When this value is false, the instance is insensitive to the number of occurrences of members and ignores their frequency. When set to true, the instance is sensitive to the total number of set members. This means that, in addition to ensuring that all of the specified warnings are issued, this instance is not satisfied if the number of times that a particular warning issues differs from the number of times that warning is specified in warnArr.

Default: false

'RespectingOrder'

Indicator whether to respect the order of elements, specified as false or true (logical 0 or 1). When this value is false, the instance is insensitive to the order of the set members. When set to true, the instance is sensitive to the order of the set members. This means that this instance is not satisfied if the order of the issued warnings differs from the order the warnings are specified in warnArr.

The order of a given set of warnings is determined by trimming the warning profiles to a profile with no repeated adjacent warnings. For example, the warning profile {id:A, id:A, id:B, id:C, id:C, id:C, id:A, id:A, id:A} is trimmed to {id:A, id:B, id:C, id:A}.

When this constraint respects order, the order of the warnings that are issued and expected must match the order of the expected warning profile. Warnings issued that are not listed in warnArr are ignored when determining order.

Default: false

'RespectingSet'

Indicator whether to respect set elements, specified as false or true (logical 0 or 1). When this value is false, the instance ignores additional set members. When set to true, the instance is sensitive to additional set members. This means that, in addition to ensuring that all of the specified warnings are issued, this instance is not satisfied if any extra, unspecified warnings are issued.

Default: false

'WhenNargoutIs'

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

Default: 0

Properties

Exact

Indicator of whether the constraint performs exact comparisons. Set this property through the constructor via the name-value pair argument, 'Exactly'.

ExpectedWarnings

Expected warning identifiers. Set this read-only property through the constructor via the warnArr input argument.

FunctionOutputs

Output arguments produced at invocation of the supplied function handle, specified as a cell array. This property provides access to output arguments. It is read only and the testing framework sets it when it invokes the function handle. The number of outputs is determined by the Nargout property.

Nargout

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

RespectCount

Indicator if the constraint respects the element counts, specified through the constructor via the name-value pair argument, 'RespectingCount'.

RespectOrder

Indicator if the constraint respects the order of elements, specified through the constructor via the name-value pair argument, 'RespectingOrder'.

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

testCase = TestCase.forInteractiveUse;

Create a helper anonymous function for use in this example. Create several warning identifiers.

issueWarnings = @(idCell) cellfun(@(id) warning(id,'Message'), idCell);
firstID =   'first:id';
secondID =  'second:id';
thirdID =   'third:id';

Verify that the helper function issues a particular warning.

testCase.verifyThat(@() issueWarnings({firstID}),...
    IssuesWarnings({firstID}))
Interactive verification passed.

Verify the function issues a warning ignoring count, warning set, and order.

testCase.verifyThat(@() issueWarnings({firstID, thirdID, secondID,...
    firstID}), IssuesWarnings({secondID, firstID}))
Interactive verification passed.

Verify the function issues a warning while respecting the warning set.

testCase.verifyThat(@() issueWarnings({firstID, thirdID, secondID,...
    firstID}), IssuesWarnings({firstID, secondID, thirdID}, ...
    'RespectingSet', true))
Interactive verification passed.

Verify the function issues a warning while respecting the warning count.

testCase.verifyThat(@() issueWarnings({secondID, firstID, thirdID,...
    secondID}), IssuesWarnings({firstID, secondID, secondID}, ...
    'RespectingCount', true))
Interactive verification passed.

Verify the function issues a warning while respecting the warning order.

testCase.verifyThat(@() issueWarnings({firstID, secondID, secondID,...
    thirdID}), IssuesWarnings({firstID, secondID}, 'RespectingOrder', true))
Interactive verification passed.

Verify the function issues an exact match to the expected warning profile.

testCase.verifyThat(@() issueWarnings({firstID, secondID, secondID,...
    thirdID}), IssuesWarnings({firstID, secondID, secondID, thirdID}, ...
    'Exactly', true))
Interactive verification passed.

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

testCase.verifyThat(5, IssuesWarnings({firstID}))
Interactive 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

Verify that the constraint is not satisfied if the function does not issue a warning.

testCase.verifyThat(@rand, IssuesWarnings({firstID}))
Interactive 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:
        --> 'first:id'

Evaluated Function:
        @rand

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

testCase.verifyThat(@() issueWarnings({firstID}), IssuesWarnings({secondID}))
Warning: Message 
> In @(id)warning(id,'Message')
  In @(idCell)cellfun(@(id)warning(id,'Message'),idCell)
  In @()issueWarnings({firstID})
  In matlab.unittest.internal.constraints.FunctionHandleConstraint/invoke (line 36)
  In matlab.unittest.internal.constraints.WarningQualificationConstraint/invoke (line 39)
  In matlab.unittest.constraints.IssuesWarnings/invoke (line 431)
  In matlab.unittest.constraints.IssuesWarnings/invokeCapturingOutput (line 510)
  In matlab.unittest.constraints.IssuesWarnings/issuesExpectedWarnings (line 519)
  In matlab.unittest.constraints.IssuesWarnings/satisfiedBy (line 239)
  In matlab.unittest.internal.qualifications.QualificationDelegate/qualifyThat (line 62)
  In matlab.unittest.qualifications.Verifiable/verifyThat (line 228) 
Interactive 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 warnings.
        
        Missing Warnings:
            --> 'second:id'
    
    Actual Warning Profile:
        --> 'first:id'
    Expected Warning Profile:
        --> 'second:id'

Evaluated Function:
        @()issueWarnings({firstID})

Consider the following actual value and warning array.

actVal = @() issueWarnings({firstID, firstID, secondID, firstID});
warnArr = {firstID, secondID, firstID, firstID};

Test whether the warning array is exactly the same as the expected array.

testCase.verifyThat(actVal, IssuesWarnings(warnArr, 'Exactly', true))
Warning: Message 
> In @(id)warning(id,'Message')
  In @(idCell)cellfun(@(id)warning(id,'Message'),idCell)
  In @()issueWarnings({firstID,firstID,secondID,firstID})
  In matlab.unittest.internal.constraints.FunctionHandleConstraint/invoke (line 36)
  In matlab.unittest.internal.constraints.WarningQualificationConstraint/invoke (line 39)
  In matlab.unittest.constraints.IssuesWarnings/invoke (line 431)
  In matlab.unittest.constraints.IssuesWarnings/invokeCapturingOutput (line 510)
  In matlab.unittest.constraints.IssuesWarnings/issuesExpectedWarnings (line 519)
  In matlab.unittest.constraints.IssuesWarnings/satisfiedBy (line 239)
  In matlab.unittest.internal.qualifications.QualificationDelegate/qualifyThat (line 62)
  In matlab.unittest.qualifications.Verifiable/verifyThat (line 228) 
Warning: Message 
> In @(id)warning(id,'Message')
  In @(idCell)cellfun(@(id)warning(id,'Message'),idCell)
  In @()issueWarnings({firstID,firstID,secondID,firstID})
  In matlab.unittest.internal.constraints.FunctionHandleConstraint/invoke (line 36)
  In matlab.unittest.internal.constraints.WarningQualificationConstraint/invoke (line 39)
  In matlab.unittest.constraints.IssuesWarnings/invoke (line 431)
  In matlab.unittest.constraints.IssuesWarnings/invokeCapturingOutput (line 510)
  In matlab.unittest.constraints.IssuesWarnings/issuesExpectedWarnings (line 519)
  In matlab.unittest.constraints.IssuesWarnings/satisfiedBy (line 239)
  In matlab.unittest.internal.qualifications.QualificationDelegate/qualifyThat (line 62)
  In matlab.unittest.qualifications.Verifiable/verifyThat (line 228) 
Warning: Message 
> In @(id)warning(id,'Message')
  In @(idCell)cellfun(@(id)warning(id,'Message'),idCell)
  In @()issueWarnings({firstID,firstID,secondID,firstID})
  In matlab.unittest.internal.constraints.FunctionHandleConstraint/invoke (line 36)
  In matlab.unittest.internal.constraints.WarningQualificationConstraint/invoke (line 39)
  In matlab.unittest.constraints.IssuesWarnings/invoke (line 431)
  In matlab.unittest.constraints.IssuesWarnings/invokeCapturingOutput (line 510)
  In matlab.unittest.constraints.IssuesWarnings/issuesExpectedWarnings (line 519)
  In matlab.unittest.constraints.IssuesWarnings/satisfiedBy (line 239)
  In matlab.unittest.internal.qualifications.QualificationDelegate/qualifyThat (line 62)
  In matlab.unittest.qualifications.Verifiable/verifyThat (line 228) 
Warning: Message 
> In @(id)warning(id,'Message')
  In @(idCell)cellfun(@(id)warning(id,'Message'),idCell)
  In @()issueWarnings({firstID,firstID,secondID,firstID})
  In matlab.unittest.internal.constraints.FunctionHandleConstraint/invoke (line 36)
  In matlab.unittest.internal.constraints.WarningQualificationConstraint/invoke (line 39)
  In matlab.unittest.constraints.IssuesWarnings/invoke (line 431)
  In matlab.unittest.constraints.IssuesWarnings/invokeCapturingOutput (line 510)
  In matlab.unittest.constraints.IssuesWarnings/issuesExpectedWarnings (line 519)
  In matlab.unittest.constraints.IssuesWarnings/satisfiedBy (line 239)
  In matlab.unittest.internal.qualifications.QualificationDelegate/qualifyThat (line 62)
  In matlab.unittest.qualifications.Verifiable/verifyThat (line 228) 
Interactive 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:
        --> 'first:id'
        --> 'first:id'
        --> 'second:id'
        --> 'first:id'
    Expected Warning Profile:
        --> 'first:id'
        --> 'second:id'
        --> 'first:id'
        --> 'first:id'

Evaluated Function:
        @()issueWarnings({firstID,firstID,secondID,firstID})

Test whether the warning array is the same as the expected array when respecting set, order and count.

testCase.verifyThat(actVal, IssuesWarnings(warnArr,...
    'RespectingSet',true,'RespectingOrder',true,'RespectingCount',true))
Interactive verification passed.

In this example, a constraint that specifies a warning profile that respects set, order and count is not the same as one that specifies an exact warning profile.

See Also

| | |

MATLAB Documentation

Support