matlab.unittest.diagnostics.ConstraintDiagnostic Class

R2026b

Namespace: matlab.unittest.diagnostics
Superclasses: matlab.automation.diagnostics.Diagnostic

Diagnostic with fields common to constraints

expand all in page

Description

The matlab.unittest.diagnostics.ConstraintDiagnostic class provides a diagnostic with fields that are common to constraints. These fields include the description, conditions, actual value, and expected value. For more information, see Diagnostic Fields.

The ConstraintDiagnostic class provides a convenient way to add a common look and feel to diagnostics produced by your custom constraints. You can use ConstraintDiagnostic objects to implement the getDiagnosticFor method of Constraint subclasses or the getNegativeDiagnosticFor method of BooleanConstraint subclasses.

The matlab.unittest.diagnostics.ConstraintDiagnostic class is a handle class.

Creation

Description

diagnostic = matlab.unittest.diagnostics.ConstraintDiagnostic creates a ConstraintDiagnostic object. You can then set properties of the object to customize the constraint diagnostic.

Tip

To produce preformatted constraint diagnostics, create ConstraintDiagnostic objects using the convenience methods of the Constraint and BooleanConstraint classes:

  • To create ConstraintDiagnostic objects inside the getDiagnosticFor method, use the createPassingDiagnostic and createFailingDiagnostic convenience methods of the Constraint class.

  • To create ConstraintDiagnostic objects inside the getNegativeDiagnosticFor method, use the createNegativePassingDiagnostic and createNegativeFailingDiagnostic convenience methods of the BooleanConstraint class.

These convenience methods automatically set the properties required to display the diagnostic information. (since R2026b)

example

Properties

expand all

In addition to the following properties, the ConstraintDiagnostic class inherits the Artifacts and DiagnosticText properties from the Diagnostic class.

Description

General diagnostic information, specified as a string scalar or character vector.

Attributes:

GetAccess
public
SetAccess
public

Option to display the text in the Description property, specified as a numeric or logical 0 (false) or 1 (true). By default, the constraint does not display the description.

Attributes:

GetAccess
public
SetAccess
public

Conditions

Formatted list of conditions, returned as a character vector. When the framework displays the diagnostic, each condition starts on a new line and begins with an arrow (-->) delimiter.

A condition contains information specific to the cause of the test failure and acts as a “subdiagnostic.” Add conditions to the list using the addCondition and addConditionsFrom methods.

Attributes:

GetAccess
public
SetAccess
private

Number of conditions in the condition list stored in the Conditions property, returned as a nonegative integer scalar.

Attributes:

GetAccess
public
SetAccess
private

Data Types: double

Option to display the condition list in the Conditions property, specified as a numeric or logical 0 (false) or 1 (true). By default, the constraint does not display the condition list.

Attributes:

GetAccess
public
SetAccess
public

Actual Value

Actual value to test, specified as a value of any data type.

Attributes:

GetAccess
public
SetAccess
public

Header information for the actual value, specified as a string scalar or character vector.

Attributes:

GetAccess
public
SetAccess
public

Option to display the actual value and its header information, specified as a numeric or logical 0 (false) or 1 (true). By default, the constraint does not display the actual value.

Attributes:

GetAccess
public
SetAccess
public

Expected Value

Expected value, if applicable, specified as a value of any data type.

Attributes:

GetAccess
public
SetAccess
public

Header information for the expected value, specified as a string scalar or character vector.

Attributes:

GetAccess
public
SetAccess
public

Option to display the expected value and its header information, specified as a numeric or logical 0 (false) or 1 (true). By default, the constraint does not display the expected value.

Attributes:

GetAccess
public
SetAccess
public

Methods

expand all

Examples

collapse all

Create a custom constraint that determines if a value is the same size as an expected value. To produce diagnostic information for the constraint, implement its getDiagnosticFor method to return a ConstraintDiagnostic object. The ConstraintDiagnostic class provides a convenient way to customize various diagnostic fields for passing or failing tests.

In a file in your current folder, create a class named IsSameSizeAs that derives from matlab.unittest.constraints.Constraint, and implement the satisfiedBy and getDiagnosticFor methods. To implement the getDiagnosticFor method, use the createPassingDiagnostic and createFailingDiagnostic convenience methods of the matlab.unittest.constraints.Constraint class. These methods create a preformatted diagnostic by configuring a ConstraintDiagnostic object. (since R2026b)

classdef IsSameSizeAs < matlab.unittest.constraints.Constraint
    properties (SetAccess=immutable)
        ValueWithExpectedSize
    end

    methods
        function constraint = IsSameSizeAs(value)
            constraint.ValueWithExpectedSize = value;
        end

        function tf = satisfiedBy(constraint,actual)
            tf = constraint.sizeMatchesExpected(actual);
        end

        function diagnostic = getDiagnosticFor(constraint,actual)
            if constraint.sizeMatchesExpected(actual)
                diagnostic = constraint.createPassingDiagnostic;
            else
                diagnostic = constraint.createFailingDiagnostic( ...
                    ActualValue=size(actual), ...
                    ExpectedValue=size(constraint.ValueWithExpectedSize));
                diagnostic.addCondition("Sizes must be the same.")
                diagnostic.ActValHeader = "Actual Size:";
                diagnostic.ExpValHeader = "Expected Size:";
            end
        end
    end

    methods (Access=private)
        function tf = sizeMatchesExpected(constraint,actual)
            tf = isequal(size(actual), ...
                size(constraint.ValueWithExpectedSize));
        end
    end
end

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

Test a failing case. The framework uses the preformatted constraint diagnostic created with the createFailingDiagnostic convenience method. The ConstraintDiagnostic object returned by the method is customized using the addCondition method and the ActValHeader and ExpValHeader properties.

testCase.verifyThat(zeros(5),IsSameSizeAs(ones(1,5)))
Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsSameSizeAs failed.
    --> Sizes must be the same.
    
    Actual Size:
         5     5
    Expected Size:
         1     5

Create a constraint diagnostic that injects text before the description field of the diagnostic.

In a file in your current folder, create a class named CustomConstraintDiagnostic that derives from matlab.unittest.diagnostics.ConstraintDiagnostic. Implement the getPreDescriptionString method that the custom diagnostic class inherits from its superclass to inject text before the optional description field of the diagnostic.

classdef CustomConstraintDiagnostic < ...
        matlab.unittest.diagnostics.ConstraintDiagnostic
    properties (SetAccess=immutable)
        Context
    end

    methods
        function diag = CustomConstraintDiagnostic(context)
            arguments
                context (1,1) string = "Test Outcome Information"
            end
            diag.Context = context;
        end
    end

    methods (Access=protected)
        function str = getPreDescriptionString(diag)
            str = diag.Context;
        end
    end
end

Import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo

Create a constraint diagnostic by instantiating the CustomConstraintDiagnostic class.

diagnostic = CustomConstraintDiagnostic;
diagnostic.DisplayDescription = true;
diagnostic.Description = "My Custom Diagnostic";

In practice, you typically use constraint diagnostics to implement custom constraints. To simplify this example, create a test case for interactive testing, and display diagnostic information upon a test failure by using the CustomConstraintDiagnostic object. The framework displays both the specified description and the default text injected before the description.

testCase = TestCase.forInteractiveUse;
testCase.verifyThat(1,IsEqualTo(2),diagnostic)
Verification failed.
    ----------------
    Test Diagnostic:
    ----------------
    Test Outcome Information
    My Custom Diagnostic
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                Actual    Expected    Error    RelativeError
                ______    ________    _____    _____________
                                                            
                  1          2         -1          -0.5     
        
        Actual Value:
             1
        Expected Value:
             2

More About

expand all

Version History

Introduced in R2013a

See Also

Functions

Classes

Topics