matlab.unittest.constraints.Constraint Class

R2026b

Namespace: matlab.unittest.constraints

Fundamental interface for constraints

Description

The matlab.unittest.constraints.Constraint class provides an interface that you can use to encode comparison logic in qualifications and produce diagnostic information. All constraints are derived from the Constraint class, whether they are user-supplied constraints or framework constraints.

To create a custom constraint class, derive your class from matlab.unittest.constraints.Constraint and implement its abstract methods:

• Implement the satisfiedBy method to encode the comparison logic.

• Implement the getDiagnosticFor method to produce diagnostic information when the testing framework evaluates the actual value against the constraint.

Then, you can use your Constraint subclass with the assertThat, assumeThat, fatalAssertThat, and verifyThat qualification methods from the matlab.unittest.qualifications namespace.

To create a constraint that can be combined and negated using the and (&), or (|), and not (~) operators, derive your class from matlab.unittest.constraints.BooleanConstraint instead.

Class Attributes

Abstract	true
HandleCompatible	true

For information on class attributes, see Class Attributes.

Methods

Public Methods

satisfiedBy

tf = satisfiedBy(constraint,actual) Determine if the value satisfies the constraint. This method provides the comparison logic. Input Arguments constraint — Constraint, specified as a matlab.unittest.constraints.Constraint object. actual — Value to test. Output Arguments tf — Whether the value satisfies the constraint, returned as a 1 or 0 of data type logical. Abstract: true

getDiagnosticFor

diagnostic = getDiagnosticFor(constraint,actual) Produce diagnostic information for the value being evaluated against the constraint. Typically, the testing framework calls this method when it encounters a qualification failure. Therefore, a more detailed analysis after a failure can be more efficiently handled by getDiagnosticFor than the satisfiedBy method. Input Arguments constraint — Constraint, specified as a matlab.unittest.constraints.Constraint object. actual — Value to test. Output Arguments diagnostic — Diagnostic information to display, returned as a matlab.automation.diagnostics.Diagnostic object. Abstract: true Tip To create preformatted constraint diagnostics, implement the getDiagnosticFor method using the createPassingDiagnostic and createFailingDiagnostic convenience methods. (since R2026b)

Protected Methods

createPassingDiagnostic (since R2026b)

diagnostic = createPassingDiagnostic(constraint,Name=Value) Create a preformatted constraint diagnostic when constraint is satisfied. Use this convenience method to implement the getDiagnosticFor method. Input Arguments constraint — Constraint, specified as a matlab.unittest.constraints.Constraint object. Name-Value Arguments ActualValue — Actual value to include in the preformatted constraint diagnostic, specified as a value of any data type. ExpectedValue — Expected value to include in the preformatted constraint diagnostic, specified as a value of any data type. Output Arguments diagnostic — Preformatted constraint diagnostic, returned as a matlab.unittest.diagnostics.ConstraintDiagnostic object. By default, diagnostic includes a description and is configured to display any conditions that you add to it using its addCondition and addConditionsFrom methods. If you specify name-value arguments, diagnostic also includes the values you specify using these arguments. You can customize the returned ConstraintDiagnostic object by modifying its properties. Sealed: true

createFailingDiagnostic (since R2026b)

diagnostic = createFailingDiagnostic(constraint,Name=Value) Create a preformatted constraint diagnostic when constraint is not satisfied. Use this convenience method to implement the getDiagnosticFor method. Input Arguments constraint — Constraint, specified as a matlab.unittest.constraints.Constraint object. Name-Value Arguments ActualValue — Actual value to include in the preformatted constraint diagnostic, specified as a value of any data type. ExpectedValue — Expected value to include in the preformatted constraint diagnostic, specified as a value of any data type. Output Arguments diagnostic — Preformatted constraint diagnostic, returned as a matlab.unittest.diagnostics.ConstraintDiagnostic object. By default, diagnostic includes a description and is configured to display any conditions that you add to it using its addCondition and addConditionsFrom methods. If you specify name-value arguments, diagnostic also includes the values you specify using these arguments. You can customize the returned ConstraintDiagnostic object by modifying its properties. Sealed: true

Examples

Create Constraint to Test for Size

Create a constraint that determines if a value is the same size as an expected value.

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.

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

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

        % Determine if the actual value satisfies the constraint
        function tf = satisfiedBy(constraint,actual)
            tf = constraint.sizeMatchesExpected(actual);
        end

        % Produce a diagnostic for the constraint
        function diagnostic = getDiagnosticFor(constraint,actual)
            if constraint.sizeMatchesExpected(actual)
                diagnostic = constraint.createPassingDiagnostic;
            else
                diagnostic = constraint.createFailingDiagnostic( ...
                    ActualValue=size(actual), ...
                    ExpectedValue=size(constraint.ValueWithExpectedSize));
                diagnostic.ActValHeader = "Actual Size:";
                diagnostic.ExpValHeader = "Expected Size:";
            end
        end
    end

    methods (Access=private)
        % Determine if the actual and expected values are the same size
        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;

Verify that a 5-by-5 matrix of zeros is the same size as a 5-by-5 matrix of ones by using the IsSameSizeAs constraint.

testCase.verifyThat(zeros(5),IsSameSizeAs(ones(5)))

Verification passed.

Test a failing case.

testCase.verifyThat(zeros(5),IsSameSizeAs(ones(1,5)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsSameSizeAs failed.
    
    Actual Size:
         5     5
    Expected Size:
         1     5

Tips

• By default, the testing framework displays diagnostics only when a qualification fails. You can override the default behavior by customizing the test runner. For example, use a DiagnosticsOutputPlugin instance to display both failing and passing event diagnostics.

Version History

Introduced in R2013a

R2026b: Create preformatted diagnostics for constraints

To create preformatted diagnostics for a constraint, use the createPassingDiagnostic and createFailingDiagnostic convenience methods when implementing the getDiagnosticFor method of the constraint class.