matlab.test.behavior.Missing Class

Namespace: matlab.test.behavior
Superclasses: matlab.unittest.TestCase

Test if class satisfies contract for missing values

Description

To test if the missing value for your class satisfies the missing contract in MATLAB^®, create a test class that derives from the matlab.test.behavior.Missing class. If your class represents a data type and you want MATLAB to treat missing values of your class similarly to built-in classes, make sure that your class satisfies the missing contract.

Typically, you use the behavior test as part of a test-driven development workflow. If you want the missing value for your class to satisfy the missing contract in MATLAB, write the behavior test and modify the class under test until the tests pass. For example, if your class supports comparisons and ordering and is usable as a missing value indicator, all tests should pass. If your class does not support ordering, set the SupportsOrdering property to false so that MATLAB filters out tests associated with ordering.

Your behavior test must derive only from matlab.test.behavior.Missing and define the abstract properties. However, because matlab.test.behavior.Missing is a subclass of matlab.unittest.TestCase, you can use the features of the unit testing framework.

Class Attributes

`Abstract`	`true`
`HandleCompatible`	`true`

For information on class attributes, see Class Attributes.

Properties

expand all

Define values for all abstract properties in the properties block of your test class.

`MissingValue` — Missing value for class under test
valid MATLAB scalar value | expression that returns missing value

Missing value for the class under test, specified as a valid MATLAB scalar value or an expression that returns a missing value.

Example: NaN

Example: missing

Example: ' '

Attributes:

`SetAccess`	`public`
`GetAccess`	`public`
`Abstract`	`true`

`PrototypeValue` — Any nonmissing value for class under test
valid MATLAB scalar value | expression that returns nonmissing value

Any nonmissing value for the class under test, specified as a valid MATLAB scalar value or an expression that returns a nonmissing value. Typically, if the class constructor returns a nonmissing value, PrototypeValue is a call to the constructor.

Example: 0

Example: datetime

Attributes:

`SetAccess`	`public`
`GetAccess`	`public`
`Abstract`	`true`

`ClassesWithSupportedConversions` — Classes that can be converted to class under test
string vector of class names

Classes that can be converted to the class under test, specified as a string vector of class names.

If you can convert your class to the other class and back, then your class has a supported conversion from the other class. For example, if MyClass(OtherClass(missing)) == MyClass(missing), then OtherClass is a class with supported conversions.

Example: "string"

Example: ["double" "single"]

Attributes:

`SetAccess`	`public`
`GetAccess`	`public`
`Abstract`	`true`

If necessary, redefine values for concrete properties in the TestClassSetup methods block of your test class.

`SupportsComparison` — Whether class supports comparison
`1` (default) | `0`

Whether the class supports comparison, returned as a 1 or 0 of data type logical. A class that supports comparison allows the use of == and ~=.

If you set SupportsComparison to false, then MATLAB filters out comparison and ordering tests by assumption failure. MATLAB does not run the tests.

Attributes:

`SetAccess`	`protected`
`GetAccess`	`public`

`SupportsOrdering` — Whether class supports ordering
`1` (default) | `0`

Whether the class supports ordering, returned as a 1 or 0 of data type logical. A class that supports ordering allows the use of <, >, <=, and >=.

If you set SupportsOrdering to false, then MATLAB filters out ordering tests by assumption failure. MATLAB does not run the tests.

Attributes:

`SetAccess`	`protected`
`GetAccess`	`public`

`UsableAsMissingIndicator` — Whether class is usable as missing value indicator
`1` (default) | `0`

Whether the class is usable as a missing value indicator with the ismissing function, returned as a 1 or 0 of data type logical.

If you set UsableAsMissingIndicator to false, then MATLAB filters out associated tests by assumption failure. MATLAB does not run the tests.

Attributes:

`SetAccess`	`protected`
`GetAccess`	`public`

`FillValue` — Fill value for growing arrays
value of `MissingValue` property (default) | valid MATLAB scalar value

Fill value that the class uses for growing arrays, returned as a MATLAB scalar value. By default, the value of FillValue is the same as the value of the MissingValue property.

Example: 0

Attributes:

`SetAccess`	`protected`
`GetAccess`	`public`

`ExtraConstructorArguments` — Class constructor arguments that result in incompatible values
`{}` (default) | cell vector

Since R2023b

Class constructor arguments that result in incompatible values, returned as a cell vector. Use this property if the class under test has such constructor arguments. For example, the datetime class supports two categories, zoned and unzoned values, corresponding to whether the TimeZone name-value argument of the class constructor is specified. These values are incompatible; for instance, you cannot concatenate or compare zoned and unzoned values. To test against the arguments that result in incompatible values, set the ExtraConstructorArguments property.

If you set the ExtraConstructorArguments property, the values you assign to the MissingValue and PrototypeValue properties must use the arguments specified in ExtraConstructorArguments. For an example of how to test using the ExtraConstructorArguments property, see Write Behavior Tests for datetime Class.

Example: {"TimeZone","Asia/Tokyo"}

Attributes:

`SetAccess`	`protected`
`GetAccess`	`public`

Examples

collapse all

Verify Class Satisfies Missing Value Contract

In your current folder, create a class named MyDataClass that supports a missing value. If you call the constructor with no inputs, it returns a missing value.

classdef MyDataClass
    properties
        SomeData;
        MissingVal = false;
    end
    
    methods
        function obj = MyDataClass(value)
            if nargin
                m = size(value,1);
                n = size(value,2);
                for i = 1:m
                    for j = 1:n
                        if ismissing(value(i,j))
                            obj(i,j).MissingVal = true;
                        else
                            obj(i,j).SomeData = value(i,j);
                            obj(i,j).MissingVal = false;
                        end
                    end
                end
            else
                obj.MissingVal = true;
            end
        end
        
        % Define ismissing behavior
        function m = ismissing(obj,v)
            if nargin > 1
                m = isequaln(obj,v);
            else
                m = [obj.MissingVal];
            end
            m = reshape(m,size(obj));
        end
    end
end

To create a simple test class that checks that MyDataClass satisfies the missing contract, subclass matlab.test.behavior.Missing and define the abstract properties. The test can use the features of the unit testing framework, but MissingValueTest checks the missing contract only.

classdef MissingValueTest < matlab.test.behavior.Missing
    properties
        MissingValue = MyDataClass;
        PrototypeValue = MyDataClass(7);
        ClassesWithSupportedConversions = [];
    end
end

Run the tests and review the results. The tests for comparison, ordering, equality, and using MyDataClass as the second input to ismissing fail.

results = runtests("MissingValueTest");

Running MissingValueTest
....
================================================================================
Error occurred in MissingValueTest/comparison and it did not run to completion.

    ---------
    Error ID:
    ---------
    'MATLAB:UndefinedFunction'

    --------------
    Error Details:
    --------------
    Undefined function 'eq' for input arguments of type 'MyDataClass'.
    
    Error in matlab.test.behavior.Missing/comparison (line 129)
                testCase.verifyFalse(testCase.MissingValue == testCase.MissingValue,
                getString(message('MATLAB:test:behavior:missing:EqualFalse')));
================================================================================
.
================================================================================
Error occurred in MissingValueTest/ordering and it did not run to completion.

    ---------
    Error ID:
    ---------
    'MATLAB:UndefinedFunction'

    --------------
    Error Details:
    --------------
    Undefined function 'lt' for input arguments of type 'MyDataClass'.
    
    Error in matlab.test.behavior.Missing/ordering (line 136)
                testCase.verifyFalse(testCase.MissingValue < testCase.MissingValue,
                getString(message('MATLAB:test:behavior:missing:LessThanFalse')));
================================================================================
.
================================================================================
Verification failed in MissingValueTest/isequalRules.

    ----------------
    Test Diagnostic:
    ----------------
    isequal(MissingValue, MissingValue) must return false, because all missing values are unequal.

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyFalse failed.
    --> The value must evaluate to "false".
    
    Actual Value:
      logical
    
       1

    ------------------
    Stack Information:
    ------------------
    In <matlabroot>\toolbox\matlab\datatypes\+matlab\+test\+behavior\Missing.m (Missing.isequalRules) at 145
================================================================================

================================================================================
Verification failed in MissingValueTest/isequalRules.

    ----------------
    Test Diagnostic:
    ----------------
    isequaln(MissingValue, missing) must return true.

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyTrue failed.
    --> The value must evaluate to "true".
    
    Actual Value:
      logical
    
       0

    ------------------
    Stack Information:
    ------------------
    In <matlabroot>\toolbox\matlab\datatypes\+matlab\+test\+behavior\Missing.m (Missing.isequalRules) at 147
================================================================================
.
================================================================================
Verification failed in MissingValueTest/IsMissing2ndInput.

    ----------------
    Test Diagnostic:
    ----------------
    ismissing(MissingValue, missing) must return true.

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyTrue failed.
    --> The value must evaluate to "true".
    
    Actual Value:
      logical
    
       0

    ------------------
    Stack Information:
    ------------------
    In <matlabroot>\toolbox\matlab\datatypes\+matlab\+test\+behavior\Missing.m (Missing.IsMissing2ndInput) at 154
================================================================================
...
Done MissingValueTest
__________

Failure Summary:

     Name                                Failed  Incomplete  Reason(s)
    =================================================================================
     MissingValueTest/comparison           X         X       Errored.
    ---------------------------------------------------------------------------------
     MissingValueTest/ordering             X         X       Errored.
    ---------------------------------------------------------------------------------
     MissingValueTest/isequalRules         X                 Failed by verification.
    ---------------------------------------------------------------------------------
     MissingValueTest/IsMissing2ndInput    X                 Failed by verification.

Iteratively update MyDataClass to satisfy the missing contract. To satisfy comparison and ordering, define eq, ne, lt, gt, le, and ge in the methods block of MyDataClass.

        % Class supports comparison
        function tf = eq(obj1,obj2)
            tf = ~any(ismissing([obj1 obj2])) && eq(obj1.SomeData,obj2.SomeData);
        end
        function tf = ne(obj1,obj2)
            tf = ~eq(obj1,obj2);
        end
        
        % Class supports ordering
        function tf = lt(obj1,obj2)
            tf = ~any(ismissing([obj1 obj2])) && lt(obj1.SomeData,obj2.SomeData);
        end
        function tf = gt(obj1,obj2)
            tf = lt(obj2,obj1);
        end   
        function tf = le(obj1,obj2)
            tf = ~any(ismissing([obj1 obj2])) && ~gt(obj1,obj2);
        end
        function tf = ge(obj1,obj2)
            tf = le(obj2,obj1);
        end

Run the tests with a terse level of output detail and review the results.

results = runtests("MissingValueTest","OutputDetail",1);

......
FAIL: MissingValueTest/isequalRules in Missing.isequalRules at 145 :: verifyFalse failed.

FAIL: MissingValueTest/isequalRules in Missing.isequalRules at 147 :: verifyTrue failed.
.
FAIL: MissingValueTest/IsMissing2ndInput in Missing.IsMissing2ndInput at 154 :: verifyTrue failed.
...

Iteratively update MyDataClass to satisfy the equality rules and be accepted as the second input to the ismissing function. Define isequal and isequaln in the methods block of MyDataClass.

        % Class supports isequal/isequaln rules
        function tf = isequal(obj1,obj2)
            tf = eq(obj1,obj2);
        end
        function tf = isequaln(obj1,obj2)
            tf = all(ismissing([obj1 obj2])) || eq(obj1,obj2);
        end

Run the tests and review the results. The tests pass, so MyDataClass satisfies the missing value contract.

results = runtests("MissingValueTest");

Running MissingValueTest
..........
Done MissingValueTest
__________

Write Behavior Tests for `datetime` Class

Write tests to verify that the datetime class satisfies the missing contract in MATLAB for both zoned and unzoned datetime values. A zoned datetime value is a value you create by specifying the TimeZone name-value argument during creation. This example is for illustration purposes only. In practice, you test user-defined classes.

In your current folder, create the MissingDatetimeTest test class by subclassing matlab.test.behavior.Missing. Define the abstract properties that the class inherits in a properties block. Note that the MissingDatetimeTest class contains unzoned datetime values (that is, datetime and NaT).

classdef MissingDatetimeTest < matlab.test.behavior.Missing
    properties
        MissingValue = NaT
        PrototypeValue = datetime
        ClassesWithSupportedConversions = "string"
    end
end

Run the MissingDatetimeTest test class. The tests pass, which indicates that the datetime class satisfies the missing contract for unzoned datetime values.

runtests("MissingDatetimeTest");

Running MissingDatetimeTest
..........
Done MissingDatetimeTest
__________

datetime values that you create with the TimeZone name-value argument are not compatible with unzoned values. For example, you cannot concatenate zoned and unzoned datetime values. Because the TimeZone constructor argument results in incompatible values, create another behavior test to make sure that the datetime class satisfies the missing contract for zoned values as well. In your current folder, create the ZonedMissingDatetimeTest test class by subclassing matlab.test.behavior.Missing. Define the abstract properties, and additionally specify the constructor argument to test against by setting the ExtraConstructorArguments property in a TestClassSetup methods block. The values you assign to the MissingValue and PrototypeValue properties must use the specified name-value argument in ExtraConstructorArguments.

classdef ZonedMissingDatetimeTest < matlab.test.behavior.Missing
    properties
        MissingValue = NaT(TimeZone="Asia/Tokyo")
        PrototypeValue = datetime(2023,6,23,TimeZone="Asia/Tokyo")
        ClassesWithSupportedConversions = "string"
    end

    methods (TestClassSetup)
        function zonedDatetimeConstructorArgs(testCase)
            testCase.ExtraConstructorArguments = {"TimeZone","Asia/Tokyo"};
        end
    end
end

Run the ZonedMissingDatetimeTest test class. The tests pass, which indicates that the datetime class satisfies the missing contract for zoned datetime values as well.

runtests("ZonedMissingDatetimeTest");

Running ZonedMissingDatetimeTest
..........
Done ZonedMissingDatetimeTest
__________

More About

expand all

Contract Details for Missing Values

Basic Validation

The behavior test asserts that these conditions are true:

The missing value in the MissingValue property is of the same class as the value in the PrototypeValue property.
The MissingValue and PrototypeValue values are scalar.
The ismissing function called with the value of MissingValue returns true.
The ismissing function called with the value of PrototypeValue returns false.

Conversion

The behavior test verifies that converting the missing value to an instance of your class returns the same value as the MissingValue property.

Additionally, for each class that your class can convert, the behavior test verifies conversion of missing values. For example, if you can convert between OtherClass and MyClass, the behavior test verifies that MyClass(OtherClass(missing)) == MyClass(missing). The ClassesWithSupportedConversions property indicates which classes your class can convert.

Subscripted Assignment

Given an array of objects of your class, subscripted assignment tests verify that you can expand the array using the missing value and assign the missing value to a range of elements in the array.

Concatenation

Concatenation tests verify that arrays of objects of your class can be concatenated with missing values.

Equality

Equality tests verify that isequal returns false for two missing values and isequaln returns true for two missing values.

SupportsComparison Property

By default, the behavior test assumes that your class supports comparison of values, including missing values. Comparison tests verify that you implemented == and ~= as MATLAB expects, with respect to missing values:

The comparison of two missing values with == returns false.
The comparison of two missing values with ~= returns true.

If your class does not support comparisons, set the SupportsComparison property to false so MATLAB does not run these tests. In this case, comparison tests are filtered as assumption failures (filtered tests). Additionally, if SupportsComparison is false, MATLAB does not run the ordering tests.

SupportsOrdering Property

By default, the behavior test assumes that your class supports ordering of values, including missing values. Ordering tests verify that you implemented <, >, <=, and >= as MATLAB expects, with respect to missing values. For missing values, MATLAB expects that all the ordering operations return false.

If your class supports ordering, to satisfy the missing contract, it must also support comparisons. If SupportsComparison is false, MATLAB does not run the ordering tests or the comparison tests. In this case, ordering tests are marked as assumption failures (filtered tests).

If your class does not support ordering, set the SupportsOrdering property to false so MATLAB does not run these tests. In this case, ordering tests are marked as assumption failures (filtered tests).

UsableAsMissingIndicator Property

By default, the behavior test assumes that an instance of your class can be used as the optional input argument of the ismissing function that represents the missing value indicator.

If your class cannot be a missing value indicator, set the UsableAsMissingIndicator property to false so MATLAB does not run these tests. In this case, associated tests are marked as assumption failures (filtered tests).

FillValue Property

The behavior test verifies that when MATLAB grows an array of elements of your class, the new elements have the value specified by the FillValue property. By default, the FillValue property has the same value as the MissingValue property. However, you can specify a different value for FillValue.

ExtraConstructorArguments Property

The behavior test verifies that instances of your class constructed using the arguments in ExtraConstructorArguments satisfy the missing contract. Setting this property is useful when the class under test has constructor arguments that can result in incompatible values (for example, values that cannot be concatenated with the values created using another constructor syntax).

Version History

Introduced in R2018b

expand all

R2023b: Test against constructor arguments that result in incompatible values

Specify the ExtraConstructorArguments property to test if a class using the specified constructor arguments satisfies the contract for missing values. Use this property to test against constructor arguments that result in incompatible values.

matlab.test.behavior.Missing Class

Description

Class Attributes

Properties

`MissingValue` — Missing value for class under test
valid MATLAB scalar value | expression that returns missing value

Attributes:

`PrototypeValue` — Any nonmissing value for class under test
valid MATLAB scalar value | expression that returns nonmissing value

Attributes:

`ClassesWithSupportedConversions` — Classes that can be converted to class under test
string vector of class names

Attributes:

`SupportsComparison` — Whether class supports comparison
`1` (default) | `0`

Attributes:

`SupportsOrdering` — Whether class supports ordering
`1` (default) | `0`

Attributes:

`UsableAsMissingIndicator` — Whether class is usable as missing value indicator
`1` (default) | `0`

Attributes:

`FillValue` — Fill value for growing arrays
value of `MissingValue` property (default) | valid MATLAB scalar value

Attributes:

`ExtraConstructorArguments` — Class constructor arguments that result in incompatible values
`{}` (default) | cell vector

Attributes:

Examples

Verify Class Satisfies Missing Value Contract

Write Behavior Tests for `datetime` Class

More About

Contract Details for Missing Values

Version History

R2023b: Test against constructor arguments that result in incompatible values

See Also

Functions

Classes

matlab.test.behavior.Missing Class

Description

Class Attributes

Properties

MissingValue — Missing value for class under test valid MATLAB scalar value | expression that returns missing value

Attributes:

PrototypeValue — Any nonmissing value for class under test valid MATLAB scalar value | expression that returns nonmissing value

Attributes:

ClassesWithSupportedConversions — Classes that can be converted to class under test string vector of class names

Attributes:

SupportsComparison — Whether class supports comparison 1 (default) | 0

Attributes:

SupportsOrdering — Whether class supports ordering 1 (default) | 0

Attributes:

UsableAsMissingIndicator — Whether class is usable as missing value indicator 1 (default) | 0

Attributes:

FillValue — Fill value for growing arrays value of MissingValue property (default) | valid MATLAB scalar value

Attributes:

ExtraConstructorArguments — Class constructor arguments that result in incompatible values {} (default) | cell vector

Attributes:

Examples

Verify Class Satisfies Missing Value Contract

Write Behavior Tests for datetime Class

More About

Contract Details for Missing Values

Version History

R2023b: Test against constructor arguments that result in incompatible values

See Also

Functions

Classes

`MissingValue` — Missing value for class under test
valid MATLAB scalar value | expression that returns missing value

`PrototypeValue` — Any nonmissing value for class under test
valid MATLAB scalar value | expression that returns nonmissing value

`ClassesWithSupportedConversions` — Classes that can be converted to class under test
string vector of class names

`SupportsComparison` — Whether class supports comparison
`1` (default) | `0`

`SupportsOrdering` — Whether class supports ordering
`1` (default) | `0`

`UsableAsMissingIndicator` — Whether class is usable as missing value indicator
`1` (default) | `0`

`FillValue` — Fill value for growing arrays
value of `MissingValue` property (default) | valid MATLAB scalar value

`ExtraConstructorArguments` — Class constructor arguments that result in incompatible values
`{}` (default) | cell vector

Write Behavior Tests for `datetime` Class