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

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

Properties

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

Description

Description — General diagnostic information

string scalar | character vector

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

Attributes:

GetAccess	public
SetAccess	public

DisplayDescription — Option to display description

false or 0 (default) | true or 1

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

Conditions — Formatted list of conditions

character vector

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

ConditionsCount — Number of conditions in condition list

nonegative integer scalar

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

DisplayConditions — Option to display condition list

false or 0 (default) | true or 1

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

ActVal — Actual value

any value

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

Attributes:

GetAccess	public
SetAccess	public

ActValHeader — Header information for actual value

'Actual Value:' (default) | string scalar | character vector

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

Attributes:

GetAccess	public
SetAccess	public

DisplayActVal — Option to display actual value

false or 0 (default) | true or 1

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

ExpVal — Expected value

any value

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

Attributes:

GetAccess	public
SetAccess	public

ExpValHeader — Header information for expected value

'Expected Value:' (default) | string scalar | character vector

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

Attributes:

GetAccess	public
SetAccess	public

DisplayExpVal — Option to display expected value

false or 0 (default) | true or 1

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

Public Methods

In addition to the following methods, the ConstraintDiagnostic class inherits the diagnose and matlab.automation.diagnostics.Diagnostic.join methods from the Diagnostic class.

addCondition	addCondition(diag,cond) Add the condition cond to the condition list of diag. When the testing framework displays the condition list, each condition starts on a new indented line and begins with an arrow (-->) delimiter. Input Arguments diag — Diagnostic, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. cond — Condition, specified as a string scalar, character vector, or matlab.automation.diagnostics.Diagnostic object. To add multiple conditions, call the method multiple times by specifying individual conditions, or call the method a single time by specifying cond as a string array or array of Diagnostic objects.
addConditionsFrom	addConditionsFrom(diag,otherDiag) Add all the conditions from another ConstraintDiagnostic instance to the condition list of diag. This method is useful when a constraint composes another constraint and needs to use the conditions produced in the diagnostics of the composed constraint. Input Arguments diag — Diagnostic to add conditions to, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. otherDiag — Diagnostic to add conditions from, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object.
matlab.unittest.diagnostics.ConstraintDiagnostic.getDisplayableString	str = matlab.unittest.diagnostics.ConstraintDiagnostic.getDisplayableString(value) Convert value to a character vector for display in the diagnostic result. Input Arguments value — Value to convert, specified as a value of any data type. Output Arguments str — Text representation of the value, returned as a character vector. Static: true

Protected Methods

You can override these protected methods in ConstraintDiagnostic subclasses to add more fields to the diagnostic. The framework calls these methods to obtain fields and inject them into the diagnostic result at the locations specified by the methods. Each method returns an empty character vector unless overridden.

getPreDescriptionString	str = getPreDescriptionString(diag) Return the text to be displayed before the description. Override this method to display text before the Description property of diag. Input Arguments diag — Diagnostic, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. Output Arguments str — Text to display, returned as a string scalar or character vector.
getPostDescriptionString	str = getPostDescriptionString(diag) Return the text to be displayed after the description. Override this method to display text after the Description property of diag. Input Arguments diag — Diagnostic, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. Output Arguments str — Text to display, returned as a string scalar or character vector.
getPostConditionsString	str = getPostConditionsString(diag) Return the text to be displayed after the condition list. Override this method to display text after the Conditions property of diag. Input Arguments diag — Diagnostic, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. Output Arguments str — Text to display, returned as a string scalar or character vector.
getPostActValString	str = getPostActValString(diag) Return the text to be displayed after the actual value. Override this method to display text after the ActVal property of diag. Input Arguments diag — Diagnostic, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. Output Arguments str — Text to display, returned as a string scalar or character vector.
getPostExpValString	str = getPostExpValString(diag) Return the text to be displayed after the expected value. Override this method to display text after the ExpVal property of diag. Input Arguments diag — Diagnostic, specified as a matlab.unittest.diagnostics.ConstraintDiagnostic object. Output Arguments str — Text to display, returned as a string scalar or character vector.

Examples

Produce Constraint Diagnostic

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

Display Text Before Diagnostic Description

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

Diagnostic Fields

A constraint diagnostic consists of the following text fields, which are displayed in this order:

1. Description — General diagnostic information.

2. Conditions — Formatted list of conditions that describe the causes of the failure. Each condition starts on a new line and begins with an arrow (-->) delimiter.

3. Actual Value — Actual value associated with the constraint. The text might be truncated or formatted for proper display.

4. Expected Value — Expected value associated with the constraint (if applicable).

The ConstraintDiagnostic class inherits the diagnose method from matlab.automation.diagnostics.Diagnostic and implements it to construct the constraint diagnostic using these fields.

Version History

Introduced in R2013a