matlab.unittest.constraints.Constraint class

Package: matlab.unittest.constraints

Fundamental interface class for comparisons

Description

The Constraint interface class is the means by which matlab.unittest constraints encode comparison logic and the corresponding diagnostic information. Every comparison that conditionally can produce a failure inherits from the Constraint interface class.

Classes deriving from the Constraint interface class must provide a means to determine if a given value satisfies the constraint. To do this, implement the satisfiedBy method, which includes the definition of the underlying comparison logic. Classes deriving from the Constraint class also must provide a diagnostic for any given actual value. The testing framework uses the diagnostic when it encounters a qualification failure. To do this, implement the getDiagnosticFor method.

In exchange for meeting these requirements, all Constraint implementations are easily used with all qualification types through the verifyThat, assertThat, assumeThat, or fatalAssertThat methods. The qualifications use the comparison and diagnostic knowledge contained within the constraints. Also, the constraints can be used in situations where a test failure is not wanted, but the testing framework needs to reuse the comparison logic. For example, a constraint implementation may want to use the logic defined inside of another constraint. Since the constraint can interact with the other constraint directly, it can use the logic without the potential of causing a qualification failure.

Methods

getDiagnosticForProduce diagnostic for compared value
satisfiedByDetermine whether value satisfies constraint

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Examples

expand all

Create HasSameSizeAs Constraint

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

In a file in your working folder, create a HasSameSizeAs.m. The constructor accepts a value to compare to the actual size. This value is stored within the ValueWithExpectedSize property. Since, it is recommended that Constraint implementations are immutable, set the property SetAccess=immutable.

classdef HasSameSizeAs < matlab.unittest.constraints.Constraint
    
    properties(SetAccess=immutable)
        ValueWithExpectedSize
    end
    
    methods
        function constraint = HasSameSizeAs(value)
            constraint.ValueWithExpectedSize = value;
        end
    end
end

Classes that derive from Constraint must implement the satisfiedBy method. This method must contain the comparison logic and return a boolean value.

Include the satisfiedBy method in the methods block in HasSameSizeAs.m.

        function bool = satisfiedBy(constraint, actual)
            bool = isequal(size(actual), size(constraint.ValueWithExpectedSize));
        end

This method returns true if the actual size and expected size are equal.

Classes deriving from Constraint must implement the getDiagnosticFor method. This method must evaluate the actual value against the constraint and provide a Diagnostic object. In this example, getDiagnosticFor returns a StringDiagnostic. Include the getDiagnosticFor method in the methods block in HasSameSizeAs.m.

        function diag = getDiagnosticFor(constraint, actual)
            import matlab.unittest.diagnostics.StringDiagnostic
            
            if constraint.satisfiedBy(actual)
                diag = StringDiagnostic('HasSameSizeAs passed.');
            else
                diag = StringDiagnostic(sprintf(...
                    'HasSameSizeAs failed.\nActual Size: [%s]\nExpectedSize: [%s]',...
                    int2str(size(actual)),...
                    int2str(size(constraint.ValueWithExpectedSize))));
            end
        end

At the command prompt, create a test case for interactive testing.

import matlab.unittest.TestCase

testCase = TestCase.forInteractiveUse;

Test a passing case.

testCase.verifyThat(zeros(5), HasSameSizeAs(repmat(1,5)))
Interactive verification passed.

Test a failing case.

testCase.verifyThat(zeros(5), HasSameSizeAs(ones(1,5)))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
HasSameSizeAs failed.
Actual Size: [5  5]
ExpectedSize: [1  5]
Was this topic helpful?