matlab.test.behavior.Missing 类

命名空间: matlab.test.behavior
超类: matlab.unittest.TestCase

测试类是否满足缺失值契约

描述

要测试类的缺失值是否满足 MATLAB^® 中的缺失值契约，请创建一个派生自 matlab.test.behavior.Missing 类的测试类。如果您的类表示一种数据类型，并且您希望 MATLAB 以类似内置类的方式处理该类的缺失值，请确保您的类满足缺失值契约。

通常，您将行为测试用作测试驱动的开发工作流的一部分。如果希望类的缺失值满足 MATLAB 中的缺失值契约，请编写行为测试并修改在测类，直到测试通过。例如，如果您的类支持比较和排序，并且可用作缺失值指示符，则所有测试都应该通过。如果您的类不支持排序，请将 SupportsOrdering 属性设置为 false，以便 MATLAB 滤除与排序相关的测试。

您的行为测试只能从 matlab.test.behavior.Missing 派生并且必须定义抽象属性。然而，由于 matlab.test.behavior.Missing 是 matlab.unittest.TestCase 的子类，您可以使用单元测试框架的功能。

类属性

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

有关类属性的信息，请参阅类属性。

属性

全部展开

在测试类的 properties 块中定义所有抽象属性的值。

`MissingValue` — 待测类的缺失值
有效 MATLAB 标量值 | 返回缺失值的表达式

在测类的缺失值，指定为有效的 MATLAB 标量值或返回缺失值的表达式。

示例: NaN

示例: missing

示例: ' '

属性：

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

`PrototypeValue` — 在测类的任何非缺失值
有效 MATLAB 标量值 | 返回非缺失值的表达式

在测类的任何非缺失值，指定为有效的 MATLAB 标量值或返回非缺失值的表达式。通常，如果类构造函数返回非缺失值，则 PrototypeValue 是对构造函数的调用。

示例: 0

示例: datetime

属性：

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

`ClassesWithSupportedConversions` — 可转换为待测类的类
类名称的字符串向量

可转换为在测类的类，指定为由类名称组成的字符串向量。

如果您可以将您的类转换为其他类并转换回来，则您的类支持从其他类转换。例如，如果 MyClass(OtherClass(missing)) == MyClass(missing)，则 OtherClass 就是支持转换的类。

示例: "string"

示例: ["double" "single"]

属性：

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

如有必要，请在您的测试类的 TestClassSetup methods 块中重新定义具体属性的值。

`SupportsComparison` — 类是否支持比较
`1` (默认) | `0`

类是否支持比较，以 logical 数据类型的 1 或 0 形式返回。支持比较的类允许使用 == 和 ~=。

如果将 SupportsComparison 设置为 false，则 MATLAB 会根据假设失败滤除比较和排序测试。MATLAB 不会运行这些测试。

属性：

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

`SupportsOrdering` — 类是否支持排序
`1` (默认) | `0`

类是否支持排序，以 logical 数据类型的 1 或 0 形式返回。支持排序的类允许使用 <、>、<= 和 >=。

如果将 SupportsOrdering 设置为 false，则 MATLAB 会根据假设失败滤除排序测试。MATLAB 不会运行这些测试。

属性：

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

`UsableAsMissingIndicator` — 类是否可用作缺失值指示符
`1` (默认) | `0`

类是否可用作 ismissing 函数的缺失值指示符，以 logical 数据类型的 1 或 0 形式返回。

如果将 UsableAsMissingIndicator 设置为 false，则 MATLAB 会根据假设失败滤除相关联的测试。MATLAB 不会运行这些测试。

属性：

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

`FillValue` — 用于增大数组的填充值
`MissingValue` 属性的值 (默认) | 有效 MATLAB 标量值

类用于增大数组的填充值，以 MATLAB 标量值形式返回。默认情况下，FillValue 的值与 MissingValue 属性的值相同。

示例: 0

属性：

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

`ExtraConstructorArguments` — 导致不兼容值的类构造函数参量
`{}` (默认) | 元胞向量

自 R2023b 起

导致不兼容值的类构造函数参量，以元胞向量形式返回。如果在测类具有这样的构造函数参量，请使用此属性。例如，datetime 类支持两个类别 - 已设置时区的值和未设置时区的值，分别对应于是否指定类构造函数的 TimeZone 名称-值参量。这些值不兼容；例如，无法串联或比较已设置时区的值和未设置时区的值。要针对导致不兼容值的参量进行测试，请设置 ExtraConstructorArguments 属性。

如果设置 ExtraConstructorArguments 属性，则赋给 MissingValue 和 PrototypeValue 属性的值必须使用在 ExtraConstructorArguments 中指定的参量。有关如何使用 ExtraConstructorArguments 属性进行测试的示例，请参阅为 datetime 类编写行为测试。

示例: {"TimeZone","Asia/Tokyo"}

属性：

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

示例

全部折叠

验证类满足缺失值契约

在当前文件夹中，创建一个名为 MyDataClass 的类，该类支持缺失值。如果在没有输入的情况下调用构造函数，则返回缺失值。

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

要创建一个简单的测试类来检查 MyDataClass 是否满足缺失值契约，请子类化 matlab.test.behavior.Missing 并定义抽象属性。测试可以使用单元测试框架的功能，但 MissingValueTest 仅检查缺失值契约。

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

运行测试并查看结果。用于比较、排序、检测相等性以及使用 MyDataClass 作为 ismissing 的第二个输入的测试失败。

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.

以迭代方式更新 MyDataClass 以满足缺失值契约。要满足比较和排序，请在 MyDataClass 的 methods 块中定义 eq、ne、lt、gt、le 和 ge。

        % 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

使用简洁级别输出详细信息运行测试并查看结果。

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.
...

以迭代方式更新 MyDataClass 以满足等式规则，该类将被当作 ismissing 函数的第二个输入。在 MyDataClass 的 methods 块中定义 isequal 和 isequaln。

        % 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

运行测试并查看结果。测试通过，因此 MyDataClass 满足缺失值契约。

results = runtests("MissingValueTest");

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

为 `datetime` 类编写行为测试

编写测试以验证 datetime 类对于已设置时区和未设置时区的 datetime 值都满足 MATLAB 中的缺失值契约。已设置时区的 datetime 值是在创建过程中通过指定 TimeZone 名称-值参量创建的值。此示例仅用于说明目的。在实际操作中，您将测试用户定义的类。

在当前文件夹中，通过子类化 MissingDatetimeTest 创建 matlab.test.behavior.Missing 测试类。定义该类在 properties 块中继承的抽象属性。请注意，MissingDatetimeTest 类包含未设置时区的 datetime 值（即 datetime 和 NaT）。

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

运行 MissingDatetimeTest 测试类。测试通过，这表明 datetime 类满足未设置时区的 datetime 值的缺失值契约。

runtests("MissingDatetimeTest");

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

使用 TimeZone 名称-值参量创建的 datetime 值与未设置时区的值不兼容。例如，无法串联已设置时区和未设置时区的 datetime 值。由于 TimeZone 构造函数参量导致了不兼容的值，因此请创建另一个行为测试来确保 datetime 类也满足已设置时区的值的缺失值契约。在当前文件夹中，通过子类化 ZonedMissingDatetimeTest 创建 matlab.test.behavior.Missing 测试类。定义抽象属性，并通过在 TestClassSetup methods 块中设置 ExtraConstructorArguments 属性来指定要针对其进行测试的构造函数参量。赋给 MissingValue 和 PrototypeValue 属性的值必须使用在 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

运行 ZonedMissingDatetimeTest 测试类。测试通过，这表明 datetime 类也满足已设置时区的 datetime 值的缺失值契约。

runtests("ZonedMissingDatetimeTest");

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

详细信息

全部展开

缺失值契约的详细信息

基本验证

行为测试断言以下条件为 true：

MissingValue 属性中的缺失值与 PrototypeValue 属性中的值的类相同。
MissingValue 和 PrototypeValue 值是标量。
带 MissingValue 的值调用的 ismissing 函数返回 true。
带 PrototypeValue 的值调用的 ismissing 函数返回 false。

转换

行为测试验证将缺失值转换为类的实例所返回的值与 MissingValue 属性相同。

此外，对于您的类可以转换的每个类，行为测试将验证缺失值的转换。例如，如果可以在 OtherClass 和 MyClass 之间进行转换，则行为测试将验证 MyClass(OtherClass(missing)) == MyClass(missing)。ClassesWithSupportedConversions 属性指示您的哪些类可以转换。

下标赋值

给定类的对象的数组，下标赋值测试验证您可以使用缺失值扩展数组，并将缺失值赋给数组中的一系列元素。

串联

串联测试验证您的类的对象的数组可以与缺失值串联。

相等性

相等性测试验证 isequal 对两个缺失值返回 false，isequaln 对两个缺失值返回 true。

SupportsComparison 属性

默认情况下，行为测试假定您的类支持值的比较，包括缺失值。比较测试验证您已按照 MATLAB 的预期对缺失值实现 == 和 ~=：

使用 == 对两个缺失值进行比较返回 false。
使用 ~= 对两个缺失值进行比较返回 true。

如果您的类不支持比较，请将 SupportsComparison 属性设置为 false，以使 MATLAB 不运行这些测试。在这种情况下，比较测试会作为假设失败被滤除（滤除的测试）。此外，如果 SupportsComparison 为 false，MATLAB 不运行排序测试。

SupportsOrdering 属性

默认情况下，行为测试假定您的类支持值的排序，包括缺失值。排序测试验证您已按照 MATLAB 的预期对缺失值实现 <、>、<= 和 >=。对于缺失值，MATLAB 预期所有排序操作返回 false。

如果您的类支持排序，为了满足缺失值契约，它还必须支持比较。如果 SupportsComparison 为 false，MATLAB 不运行排序测试或比较测试。在这种情况下，排序测试被标记为假设失败（滤除的测试）。

如果您的类不支持排序，请将 SupportsOrdering 属性设置为 false，以使 MATLAB 不运行这些测试。在这种情况下，排序测试被标记为假设失败（滤除的测试）。

UsableAsMissingIndicator 属性

默认情况下，行为测试假定您的类的实例可以用作 ismissing 函数的可选输入参量，作为缺失值指示符。

如果您的类不能作为缺失值指示符，请将 UsableAsMissingIndicator 属性设置为 false，以使 MATLAB 不运行这些测试。在这种情况下，关联的测试被标记为假设失败（滤除的测试）。

FillValue 属性

行为测试验证当 MATLAB 增长类的元素的数组时，新元素具有 FillValue 属性指定的值。默认情况下，FillValue 属性与 MissingValue 属性具有相同的值。但是，您可以为 FillValue 指定不同值。

ExtraConstructorArguments 属性

行为测试验证使用 ExtraConstructorArguments 中的参量构造的类的实例是否满足缺失值契约。当在测类具有可能导致不兼容值的构造函数参量（例如，无法与使用另一种构造函数语法创建的值串联的值）时，设置此属性很有用。

版本历史记录

在 R2018b 中推出

全部展开

R2023b: 针对导致不兼容值的构造函数参量进行测试

指定 ExtraConstructorArguments 属性以测试使用指定的构造函数参量的类是否满足缺失值契约。使用此属性针对导致不兼容值的构造函数参量进行测试。

matlab.test.behavior.Missing 类

描述

类属性

属性

MissingValue — 待测类的缺失值 有效 MATLAB 标量值 | 返回缺失值的表达式

属性：

PrototypeValue — 在测类的任何非缺失值 有效 MATLAB 标量值 | 返回非缺失值的表达式

属性：

ClassesWithSupportedConversions — 可转换为待测类的类 类名称的字符串向量

属性：

SupportsComparison — 类是否支持比较 1 (默认) | 0

属性：

SupportsOrdering — 类是否支持排序 1 (默认) | 0

属性：

UsableAsMissingIndicator — 类是否可用作缺失值指示符 1 (默认) | 0

属性：

FillValue — 用于增大数组的填充值 MissingValue 属性的值 (默认) | 有效 MATLAB 标量值

属性：

ExtraConstructorArguments — 导致不兼容值的类构造函数参量 {} (默认) | 元胞向量

属性：

示例

验证类满足缺失值契约

为 datetime 类编写行为测试

详细信息

缺失值契约的详细信息

版本历史记录

R2023b: 针对导致不兼容值的构造函数参量进行测试

另请参阅

函数

类

WeChat

`MissingValue` — 待测类的缺失值
有效 MATLAB 标量值 | 返回缺失值的表达式

`PrototypeValue` — 在测类的任何非缺失值
有效 MATLAB 标量值 | 返回非缺失值的表达式

`ClassesWithSupportedConversions` — 可转换为待测类的类
类名称的字符串向量

`SupportsComparison` — 类是否支持比较
`1` (默认) | `0`

`SupportsOrdering` — 类是否支持排序
`1` (默认) | `0`

`UsableAsMissingIndicator` — 类是否可用作缺失值指示符
`1` (默认) | `0`

`FillValue` — 用于增大数组的填充值
`MissingValue` 属性的值 (默认) | 有效 MATLAB 标量值

`ExtraConstructorArguments` — 导致不兼容值的类构造函数参量
`{}` (默认) | 元胞向量

为 `datetime` 类编写行为测试