Main Content

matlab.unittest.diagnostics.ConstraintDiagnostic Class

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

Diagnostic with fields common to constraints

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

example

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

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 by using the ConstraintDiagnostic class.

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 instances of the ConstraintDiagnostic class. The ConstraintDiagnostic class provides a convenient way to customize various diagnostic fields for passing or failing tests.

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 = diagnosticForPassingTest;
            else
                diagnostic = diagnosticForFailingTest(constraint,actual);
            end
        end
    end

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

        function diag = diagnosticForPassingTest(~,~)
            import matlab.unittest.diagnostics.ConstraintDiagnostic
            diag = ConstraintDiagnostic;
            
            diag.DisplayDescription = true;
            diag.Description = "IsSameSizeAs passed.";
        end

        function diag = diagnosticForFailingTest(constraint,actual)
            import matlab.unittest.diagnostics.ConstraintDiagnostic
            diag = ConstraintDiagnostic;
            
            diag.DisplayDescription = true;
            diag.Description = "IsSameSizeAs failed.";

            diag.DisplayConditions = true;
            diag.addCondition("Sizes did not match.")

            diag.DisplayActVal = true;
            diag.ActValHeader = "Actual Size:";
            diag.ActVal = size(actual);

            diag.DisplayExpVal = true;
            diag.ExpValHeader = "Expected Size:";
            diag.ExpVal = size(constraint.ValueWithExpectedSize);
        end
    end
end

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

Test a failing case. The framework displays the constraint diagnostic implemented in the diagnosticForFailingTest helper method.

testCase.verifyThat(zeros(5),IsSameSizeAs(ones(1,5)))
Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsSameSizeAs failed.
    --> Sizes did not match.
    
    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