matlab.unittest.constraints.BooleanConstraint Class

Namespace: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.Constraint

Fundamental interface for constraints that support Boolean operations

Description

The matlab.unittest.constraints.BooleanConstraint class provides an interface that you can use to create constraints that can be combined and negated using the and (&), or (|), and not (~) operators.

To create a custom constraint class that supports Boolean operations, derive your class from matlab.unittest.constraints.BooleanConstraint and implement the required abstract methods:

• Implement the satisfiedBy method to encode the comparison logic. The BooleanConstraint class inherits this method from matlab.unittest.constraints.Constraint.

• Implement the getDiagnosticFor method to produce diagnostic information when the testing framework evaluates the actual value against the constraint. The BooleanConstraint class inherits this method from the Constraint class.

• Implement the getNegativeDiagnosticFor method to produce diagnostic information when the framework evaluates the actual value against the negated constraint. When a constraint is negated, the diagnostics must be written in a different form than for the standard (non-negated) usage.

Because the BooleanConstraint class derives from the Constraint class, BooleanConstraint subclasses support the functionality provided by Constraint subclasses. For example, you can use them with the assertThat, assumeThat, fatalAssertThat, and verifyThat qualification methods from the matlab.unittest.qualifications namespace. Additionally, you can negate a BooleanConstraint object or combine it with other BooleanConstraint objects.

Class Attributes

Abstract

true

For information on class attributes, see Class Attributes.

Methods

Specialized Operators and Functions

These methods specialize operators and functions for objects of this class.

and (&)	Return the logical conjunction of the constraint and another constraint. Combining two constraints this way specifies that both constraints must be satisfied by the actual value. If either constraint is not satisfied, a qualification failure occurs. Sealed: true
or (|)	Return the logical disjunction of the constraint and another constraint. Combining two constraints this way specifies that either constraint must be satisfied by the actual value. If both constraints are not satisfied, a qualification failure occurs. Sealed: true
not (~)	Return the logical complement of the constraint. Negating a constraint specifies that the constraint must not be satisfied by the actual value. If the constraint is satisfied, a qualification failure occurs. Sealed: true

Protected Methods

getNegativeDiagnosticFor

diagnostic = getNegativeDiagnosticFor(constraint,actual) Produce diagnostic information for the value being evaluated against the negated constraint. The diagnostics that this method produces are expressed in the negative sense of the constraint. For example, consider a hypothetical IsTasty constraint. When the negation of IsTasty is used in a qualification, the test fails if the actual value is found to be "tasty." Therefore, getNegativeDiagnosticFor should return the information that describes why the value incorrectly satisfied the constraint. Like the getDiagnosticFor method of the matlab.unittest.constraints.Constraint class, the getNegativeDiagnosticFor method is typically called for qualification failures. Therefore, a more detailed analysis after a failure can be more efficiently handled by getNegativeDiagnosticFor than the satisfiedBy method. Input Arguments constraint — Constraint, specified as a matlab.unittest.constraints.BooleanConstraint object. actual — Value to test. Output Arguments diagnostic — Diagnostic information to display, returned as a matlab.automation.diagnostics.Diagnostic object. Depending on the test runner configuration, the testing framework can display diagnostics when the qualification passes or fails. By default, the framework displays diagnostics only when the 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. Abstract: true

Examples

Use Boolean Constraints in Tests

Some built-in constraints, such as HasElementCount and HasLength, are subclasses of BooleanConstraint. You can combine and negate these constraints in your tests.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.HasElementCount
import matlab.unittest.constraints.HasLength
import matlab.unittest.constraints.HasInf
import matlab.unittest.constraints.HasNaN
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.IsGreaterThanOrEqualTo
import matlab.unittest.constraints.IsReal

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Verify that the value 3 is real and that it is greater than or equal to 3.

testCase.verifyThat(3,IsReal & IsGreaterThanOrEqualTo(3))

Verification passed.

Verify that the value 3 is not equal to 4.

testCase.verifyThat(3,~IsEqualTo(4))

Verification passed.

Test if the matrix [1 2 3; 4 5 6] has a length of six or has six elements. The test passes because one of the or conditions is true.

testCase.verifyThat([1 2 3; 4 5 6],HasLength(6) | HasElementCount(6))

Verification passed.

Test if the vector [3 NaN 5] has NaN and infinite values. The test fails because one of the and conditions is false.

testCase.verifyThat([3 NaN 5],HasNaN & HasInf)

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    AndConstraint failed.
    --> + [First Condition]:
         |   HasNaN passed.
         |   --> Indices that have NaN values:
         |           2
         |   
         |   Actual Value:
         |        3   NaN     5
    --> AND
        + [Second Condition]:
         |   HasInf failed.
         |   --> At least one element must be Inf or -Inf.
         |   
         |   Actual Value:
         |        3   NaN     5
        -+---------------------

Create Boolean Constraint to Test for Size

Create a Boolean 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.BooleanConstraint, and implement the satisfiedBy, getDiagnosticFor, and getNegativeDiagnosticFor methods.

classdef IsSameSizeAs < matlab.unittest.constraints.BooleanConstraint
    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)
            import matlab.automation.diagnostics.StringDiagnostic
            if constraint.sizeMatchesExpected(actual)
                diagnostic = StringDiagnostic("IsSameSizeAs passed.");
            else
                diagnostic = StringDiagnostic( ...
                    "IsSameSizeAs failed." + newline + "Actual Size: [" ...
                    + int2str(size(actual)) + "]" + newline ...
                    + "Expected Size: [" ...
                    + int2str(size(constraint.ValueWithExpectedSize)) ...
                    + "]");
            end
        end
    end

    methods (Access=protected)
        % Produce a diagnostic for the negated constraint
        function diagnostic = getNegativeDiagnosticFor(constraint,actual)
            import matlab.automation.diagnostics.StringDiagnostic
            if constraint.sizeMatchesExpected(actual)
                diagnostic = StringDiagnostic( ...
                    "Negated IsSameSizeAs failed." + newline + ...
                    "Actual and expected sizes were the same ([" ...
                    + int2str(size(actual)) + ...
                    "]) but should not have been.");
            else
                diagnostic = StringDiagnostic( ...
                    "Negated IsSameSizeAs passed.");
            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 both the same size as a 5-by-5 matrix of ones and not the same size as a 1-by-5 vector of ones by using the IsSameSizeAs Boolean constraint.

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

Verification passed.

Version History

Introduced in R2013a