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
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
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
Contract Details for Missing Values
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 thePrototypeValue
property.The
MissingValue
andPrototypeValue
values are scalar.The
ismissing
function called with the value ofMissingValue
returnstrue
.The
ismissing
function called with the value ofPrototypeValue
returnsfalse
.
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.
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 tests verify that arrays of objects of your class can be concatenated with missing values.
Equality tests verify that isequal
returns
false
for two missing values and isequaln
returns true
for two missing values.
SupportsComparison
PropertyBy 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
==
returnsfalse
.The comparison of two missing values with
~=
returnstrue
.
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
PropertyBy 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
PropertyBy 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
PropertyThe 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
PropertyThe 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 R2018bR2023b: 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 Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)