matlab.unittest.diagnostics.ConstraintDiagnostic 类

命名空间: matlab.unittest.diagnostics
超类: matlab.automation.diagnostics.Diagnostic

此诊断的字段对约束通用

描述

matlab.unittest.diagnostics.ConstraintDiagnostic 类提供对约束通用的字段的诊断。这些字段包括描述、条件、实际值和预期值。有关详细信息，请参阅诊断字段。

使用 ConstraintDiagnostic 类可以方便地向由您的自定义约束生成的诊断添加通用外观。您可以使用 ConstraintDiagnostic 对象来实现 Constraint 子类的 getDiagnosticFor 方法或 BooleanConstraint 子类的 getNegativeDiagnosticFor 方法。

matlab.unittest.diagnostics.ConstraintDiagnostic 类是一个 handle 类。

创建对象

描述

diag = matlab.unittest.diagnostics.ConstraintDiagnostic 创建一个 ConstraintDiagnostic 对象。然后，您可以设置该对象的属性来自定义约束诊断。

示例

属性

全部展开

除了以下属性之外，ConstraintDiagnostic 类还从 Diagnostic 类继承 Artifacts 和 DiagnosticText 属性。

描述

`Description` — 常规诊断信息
字符串标量 | 字符向量

常规诊断信息，指定为字符串标量或字符向量。

属性：

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

`DisplayDescription` — 显示描述的选项
`false` 或 `0` (默认) | `true` 或 `1`

显示 Description 属性中文本的选项，指定为数值或逻辑值 0 (false) 或 1 (true)。默认情况下，约束不显示描述。

属性：

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

条件

`Conditions` — 格式化的条件列表
字符向量

格式化的条件列表，以字符向量形式返回。当框架显示诊断结果时，每个条件另起一个新行，以箭头 (-->) 分隔符开头。

一个条件包含特定于测试失败原因的信息，充当“子诊断”。使用 addCondition 和 addConditionsFrom 方法向列表中添加条件。

属性：

`GetAccess`	`public`
`SetAccess`	`private`

`ConditionsCount` — 条件列表中的条件数
非负整数标量

存储在 Conditions 属性中的条件列表中的条件数，以非负整数标量形式返回。

属性：

`GetAccess`	`public`
`SetAccess`	`private`

数据类型: double

`DisplayConditions` — 显示条件列表的选项
`false` 或 `0` (默认) | `true` 或 `1`

显示 Conditions 属性中条件列表的选项，指定为数值或逻辑值 0 (false) 或 1 (true)。默认情况下，约束不显示条件列表。

属性：

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

实际值

`ActVal` — 实际值
任何值

要测试的实际值，指定为任何数据类型的值。

属性：

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

`ActValHeader` — 实际值的头部信息
`'Actual Value:'` (默认) | 字符串标量 | 字符向量

实际值的头部信息，指定为字符串标量或字符向量。

属性：

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

`DisplayActVal` — 显示实际值的选项
`false` 或 `0` (默认) | `true` 或 `1`

显示实际值及其头部信息的选项，指定为数值或逻辑值 0 (false) 或 1 (true)。默认情况下，约束不显示实际值。

属性：

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

预期值

`ExpVal` — 预期值
任何值

预期值，指定为任意数据类型的值（如果适用）。

属性：

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

`ExpValHeader` — 预期值的头部信息
`'Expected Value:'` (默认) | 字符串标量 | 字符向量

预期值的头部信息，指定为字符串标量或字符向量。

属性：

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

`DisplayExpVal` — 显示预期值的选项
`false` 或 `0` (默认) | `true` 或 `1`

显示预期值及其头部信息的选项，指定为数值或逻辑值 0 (false) 或 1 (true)。默认情况下，约束不显示预期值。

属性：

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

方法

全部展开

公共方法

除了以下方法之外，ConstraintDiagnostic 类还从 Diagnostic 类继承 diagnose 和 matlab.automation.diagnostics.Diagnostic.join 方法。

addCondition

addCondition(diag,cond)

将条件 cond 添加到 diag 的条件列表。当测试框架显示条件列表时，每个条件另起一个新的缩进行，该行以箭头 (-->) 分隔符开头。

输入参量

diag - 诊断，指定为 matlab.unittest.diagnostics.ConstraintDiagnostic 对象。
cond - 条件，指定为字符串标量、字符向量或 matlab.automation.diagnostics.Diagnostic 对象。要添加多个条件，请通过指定各个条件多次调用该方法，或通过将 cond 指定为字符串数组或 Diagnostic 对象数组来一次调用该方法。

addConditionsFrom

addConditionsFrom(diag,otherDiag)

将另一 ConstraintDiagnostic 实例中的所有条件添加到 diag 的条件列表中。当一个约束包含另一个约束，且需要使用该被包含约束的诊断生成的条件时，此方法特别有用。

输入参量

diag - 条件所要添加到的诊断，指定为 matlab.unittest.diagnostics.ConstraintDiagnostic 对象。
otherDiag - 要添加的条件所来自的诊断，指定为 matlab.unittest.diagnostics.ConstraintDiagnostic 对象。

matlab.unittest.diagnostics.ConstraintDiagnostic.getDisplayableString

str = matlab.unittest.diagnostics.ConstraintDiagnostic.getDisplayableString(value)

将 value 转换为字符向量以显示在诊断结果中。

输入参量

value - 要转换的值，指定为任何数据类型的值。

输出参量

str - 值的文本表示形式，以字符向量形式返回。

Static: true

受保护方法

您可以在 ConstraintDiagnostic 子类中覆盖这些受保护方法，以向诊断添加更多字段。框架调用这些方法来获取字段，并在方法指定的位置将它们注入诊断结果。除非被覆盖，否则每个方法都返回一个空字符向量。

`getPreDescriptionString`	`str = getPreDescriptionString(diag)` 返回在描述之前要显示的文本。覆盖此方法以在 `diag` 的 `Description` 属性之前显示文本。输入参量 `diag` - 诊断，指定为 `matlab.unittest.diagnostics.ConstraintDiagnostic` 对象。输出参量 `str` - 要显示的文本，以字符串标量或字符向量形式返回。
`getPostDescriptionString`	`str = getPostDescriptionString(diag)` 返回在描述之后要显示的文本。覆盖此方法以在 `diag` 的 `Description` 属性之后显示文本。输入参量 `diag` - 诊断，指定为 `matlab.unittest.diagnostics.ConstraintDiagnostic` 对象。输出参量 `str` - 要显示的文本，以字符串标量或字符向量形式返回。
`getPostConditionsString`	`str = getPostConditionsString(diag)` 返回在条件列表之后要显示的文本。覆盖此方法以在 `diag` 的 `Conditions` 属性之后显示文本。输入参量 `diag` - 诊断，指定为 `matlab.unittest.diagnostics.ConstraintDiagnostic` 对象。输出参量 `str` - 要显示的文本，以字符串标量或字符向量形式返回。
`getPostActValString`	`str = getPostActValString(diag)` 返回在实际值之后要显示的文本。覆盖此方法以在 `diag` 的 `ActVal` 属性之后显示文本。输入参量 `diag` - 诊断，指定为 `matlab.unittest.diagnostics.ConstraintDiagnostic` 对象。输出参量 `str` - 要显示的文本，以字符串标量或字符向量形式返回。
`getPostExpValString`	`str = getPostExpValString(diag)` 返回在预期值之后要显示的文本。覆盖此方法以在 `diag` 的 `ExpVal` 属性之后显示文本。输入参量 `diag` - 诊断，指定为 `matlab.unittest.diagnostics.ConstraintDiagnostic` 对象。输出参量 `str` - 要显示的文本，以字符串标量或字符向量形式返回。

示例

全部折叠

生成约束诊断

创建一个自定义约束，该约束确定一个值的大小是否与预期值的大小相同。要为约束生成诊断信息，请使用 ConstraintDiagnostic 类实现其 getDiagnosticFor 方法。

在当前文件夹下的一个文件中，创建一个名为 IsSameSizeAs 的类，该类派生自 matlab.unittest.constraints.Constraint，并实现 satisfiedBy 和 getDiagnosticFor 方法。要实现 getDiagnosticFor 方法，请使用 ConstraintDiagnostic 类的实例。使用 ConstraintDiagnostic 类可以方便地自定义通过或未通过测试的各种诊断字段。

classdef IsSameSizeAs < matlab.unittest.constraints.Constraint
    properties (SetAccess=immutable)
        ValueWithExpectedSize
    end

    methods
        function constraint = IsSameSizeAs(value)
            constraint.ValueWithExpectedSize = value;
        end

        function tf = satisfiedBy(constraint,actual)
            tf = constraint.sizeMatchesExpected(actual);
        end

        function diagnostic = getDiagnosticFor(constraint,actual)
            if constraint.sizeMatchesExpected(actual)
                diagnostic = diagnosticForPassingTest;
            else
                diagnostic = diagnosticForFailingTest(constraint,actual);
            end
        end
    end

    methods (Access=private)
        function tf = sizeMatchesExpected(constraint,actual)
            tf = isequal(size(actual), ...
                size(constraint.ValueWithExpectedSize));
        end

        function diag = diagnosticForPassingTest(~,~)
            import matlab.unittest.diagnostics.ConstraintDiagnostic
            diag = ConstraintDiagnostic;
            
            diag.DisplayDescription = true;
            diag.Description = "IsSameSizeAs passed.";
        end

        function diag = diagnosticForFailingTest(constraint,actual)
            import matlab.unittest.diagnostics.ConstraintDiagnostic
            diag = ConstraintDiagnostic;
            
            diag.DisplayDescription = true;
            diag.Description = "IsSameSizeAs failed.";

            diag.DisplayConditions = true;
            diag.addCondition("Sizes did not match.")

            diag.DisplayActVal = true;
            diag.ActValHeader = "Actual Size:";
            diag.ActVal = size(actual);

            diag.DisplayExpVal = true;
            diag.ExpValHeader = "Expected Size:";
            diag.ExpVal = size(constraint.ValueWithExpectedSize);
        end
    end
end

创建一个供交互测试的测试用例。

testCase = matlab.unittest.TestCase.forInteractiveUse;

测试一个失败的用例。框架显示在 diagnosticForFailingTest 辅助方法中实现的约束诊断。

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

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsSameSizeAs failed.
    --> Sizes did not match.
    
    Actual Size:
         5     5
    Expected Size:
         1     5

在诊断描述之前显示文本

创建一个约束诊断，它在诊断的描述字段之前注入文本。

在当前文件夹中的一个文件中，创建名为 CustomConstraintDiagnostic 的类，该类派生自 matlab.unittest.diagnostics.ConstraintDiagnostic 类。实现自定义诊断类从其超类继承的 getPreDescriptionString 方法，以在诊断的可选描述字段之前插入文本。

classdef CustomConstraintDiagnostic < ...
        matlab.unittest.diagnostics.ConstraintDiagnostic
    properties (SetAccess=immutable)
        Context
    end

    methods
        function diag = CustomConstraintDiagnostic(context)
            arguments
                context (1,1) string = "Test Outcome Information"
            end
            diag.Context = context;
        end
    end

    methods (Access=protected)
        function str = getPreDescriptionString(diag)
            str = diag.Context;
        end
    end
end

导入此示例中使用的类。

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo

通过实例化 CustomConstraintDiagnostic 类来创建一个约束诊断。

diagnostic = CustomConstraintDiagnostic;
diagnostic.DisplayDescription = true;
diagnostic.Description = "My Custom Diagnostic";

在实践中，您通常使用约束诊断来实现自定义约束。为了简化此示例，请为交互式测试创建一个测试用例，并通过使用 CustomConstraintDiagnostic 对象在测试失败时显示诊断信息。框架既显示指定的描述，也显示在描述之前注入的默认文本。

testCase = TestCase.forInteractiveUse;
testCase.verifyThat(1,IsEqualTo(2),diagnostic)

Verification failed.
    ----------------
    Test Diagnostic:
    ----------------
    Test Outcome Information
    My Custom Diagnostic
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                Actual    Expected    Error    RelativeError
                ______    ________    _____    _____________
                                                            
                  1          2         -1          -0.5     
        
        Actual Value:
             1
        Expected Value:
             2

详细信息

全部展开

诊断字段

一个约束诊断由以下文本字段组成，按以下顺序显示：

描述 - 常规诊断信息。
条件 - 描述失败原因的格式化条件列表。每个条件另起一行，以箭头 (-->) 分隔符开头。
实际值 - 与约束相关联的实际值。为了正确显示，文本可能截断或格式化。
预期值 - 与约束相关联的预期值（如果适用）。

ConstraintDiagnostic 类从 matlab.automation.diagnostics.Diagnostic 继承 diagnose 方法，并实现它来使用这些字段构造约束诊断。

版本历史记录

在 R2013a 中推出

另请参阅

函数

verifyThat

类

matlab.unittest.constraints.Constraint | matlab.unittest.constraints.BooleanConstraint

matlab.unittest.diagnostics.ConstraintDiagnostic 类

描述

创建对象

描述

属性

描述

Description — 常规诊断信息 字符串标量 | 字符向量

属性：

DisplayDescription — 显示描述的选项 false 或 0 (默认) | true 或 1

属性：

条件

Conditions — 格式化的条件列表 字符向量

属性：

ConditionsCount — 条件列表中的条件数 非负整数标量

属性：

DisplayConditions — 显示条件列表的选项 false 或 0 (默认) | true 或 1

属性：

实际值

ActVal — 实际值 任何值

属性：

ActValHeader — 实际值的头部信息 'Actual Value:' (默认) | 字符串标量 | 字符向量

属性：

DisplayActVal — 显示实际值的选项 false 或 0 (默认) | true 或 1

属性：

预期值

ExpVal — 预期值 任何值

属性：

ExpValHeader — 预期值的头部信息 'Expected Value:' (默认) | 字符串标量 | 字符向量

属性：

DisplayExpVal — 显示预期值的选项 false 或 0 (默认) | true 或 1

属性：

方法

公共方法

受保护方法

示例

生成约束诊断

在诊断描述之前显示文本

详细信息

诊断字段

版本历史记录

另请参阅

函数

类

主题

`Description` — 常规诊断信息
字符串标量 | 字符向量

`DisplayDescription` — 显示描述的选项
`false` 或 `0` (默认) | `true` 或 `1`

`Conditions` — 格式化的条件列表
字符向量

`ConditionsCount` — 条件列表中的条件数
非负整数标量

`DisplayConditions` — 显示条件列表的选项
`false` 或 `0` (默认) | `true` 或 `1`

`ActVal` — 实际值
任何值

`ActValHeader` — 实际值的头部信息
`'Actual Value:'` (默认) | 字符串标量 | 字符向量

`DisplayActVal` — 显示实际值的选项
`false` 或 `0` (默认) | `true` 或 `1`

`ExpVal` — 预期值
任何值

`ExpValHeader` — 预期值的头部信息
`'Expected Value:'` (默认) | 字符串标量 | 字符向量

`DisplayExpVal` — 显示预期值的选项
`false` 或 `0` (默认) | `true` 或 `1`