matlab.unittest.qualifications.Assertable 类

命名空间: matlab.unittest.qualifications

用来确认测试前提条件的鉴定

描述

Assertable 类提供了一种用来确认测试前提条件的鉴定机制。除了对失败执行的操作外，Assertable 类与 matlab.unittest.qualifications 命名空间中的其他鉴定类的工作方式相同。

断言失败时，Assertable 类将抛出 AssertionFailedException 对象以告知测试框架发生失败。如果希望通过断言点处的失败来表示当前测试的其余部分无效，但又不想阻止后续测试的正常执行，这种行为会很有用。通常情况下，您可以使用断言来确保符合当前测试的前提条件，或是正确设置了脚手架。如果您不能保证脚手架拆解满足异常安全条件或不能在失败后恢复环境状态，请改用致命断言。

当在 TestCase 类的一个方法中产生断言失败时，该方法的类型确定哪些测试受到影响：

Test 方法 - 框架将整个 Test 方法标记为失败和不完整。
TestMethodSetup 或 TestMethodTeardown 方法 - 框架将针对该方法实例运行的 Test 方法标记为失败和不完整。
TestClassSetup 或 TestClassTeardown 方法 - 框架将整个测试类标记为失败和不完整。

当测试中出现违反前提条件但状态可恢复的情况时，断言可确保使用其余的测试。对于因不满足前提条件而导致失败的情况，它们不执行后续确认，从而防止不必要的失败。如果失败不影响测试的前提条件，也不会导致脚手架设置或拆解问题时，请使用确认，这样可以确保运行完整测试内容。

matlab.unittest.qualifications.Assertable 类是一个 handle 类。

方法

全部展开

公共方法

Assertable 类为测试值和如何响应失败提供了几种鉴定方法。例如，assertEmpty 测试某个值为空，而 assertTrue 测试 actual 值为 true。

注意

Assertable 类的方法对应于 Verifiable 类的方法。它们仅在鉴定类型方面有所不同。您可以像调用 Verifiable 方法一样调用 Assertable 方法。

一般用途

`assertEqual`	`assertEqual(testCase,actual,expected,diagnostic,Name,Value)` 断言 `actual` 严格等于 `expected`。类似于 `verifyEqual`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `expected` - 预期值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。名称-值参量 `AbsTol` - 绝对误差，指定为一个数值数组。 `RelTol` - 相对误差，指定为数值数组。
`assertFail`	`assertFail(testCase,diagnostic)` 生成无条件的断言失败。类似于 `verifyFail`。输入参量 `testCase` - 测试用例。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertFalse`	`assertFalse(testCase,actual,diagnostic)` 断言 `actual` 的值是逻辑值 `0` (`false`)。类似于 `verifyFalse`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertNotEqual`	`assertNotEqual(testCase,actual,prohibited,diagnostic)` 断言 `actual` 不等于 `prohibited`。类似于 `verifyNotEqual`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `prohibited` - 要用于比较的值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertNotSameHandle`	`assertNotSameHandle(testCase,actual,prohibited,diagnostic)` 断言 `actual` 与禁止的句柄数组不同。类似于 `verifyNotSameHandle`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `prohibited` - 要用于比较的值，指定为句柄数组。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertReturnsTrue`	`assertReturnsTrue(testCase,actual,diagnostic)` 断言 `actual` 是返回逻辑标量 `1` (`true`) 的函数句柄。类似于 `verifyReturnsTrue`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertSameHandle`	`assertSameHandle(testCase,actual,expected,diagnostic)` 断言 `actual` 与预期的句柄数组相同。类似于 `verifySameHandle`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `expected` - 预期值，指定为句柄数组。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertThat`	`assertThat(testCase,actual,constraint,diagnostic)` 断言 `actual` 是一个满足指定约束的值。类似于 `verifyThat`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `constraint` - actual 值必须满足的约束，指定为 `matlab.unittest.constraints.Constraint` 类的实例。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertTrue`	`assertTrue(testCase,actual,diagnostic)` 断言 `actual` 的值是逻辑值 `1` (`true`)。类似于 `verifyTrue`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

错误和警告

assertError

[output1,...,outputN] = assertError(testCase,actual,identifier,diagnostic)

断言 actual 是抛出 identifier 指定的异常的函数句柄。类似于 verifyError。

输入参量

testCase - 测试用例。
actual - 要测试的值。
identifier - 错误标识符，指定为字符串标量、字符向量或 matlab.metadata.Class 实例。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

输出参量

output1,...,outputN - 从 actual 请求的输出参量 1 到 N。

assertWarning

[output1,...,outputN] = assertWarning(testCase,actual,identifier,diagnostic)

断言 actual 是发出由 identifier 指定的警告的函数句柄。类似于 verifyWarning。

输入参量

testCase - 测试用例。
actual - 要测试的值。
identifier - 警告标识符，指定为字符向量、字符向量元胞数组或字符串数组。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

输出参量

output1,...,outputN - 调用 actual 时生成的输出参量 1 到 N（如果有）。

assertWarningFree

[output1,...,outputN] = assertWarningFree(testCase,actual,diagnostic)

断言 actual 是未发出警告的函数句柄。类似于 verifyWarningFree。

输入参量

testCase - 测试用例。
actual - 要测试的值。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

输出参量

output1,...,outputN - 调用 actual 时生成的输出参量 1 到 N（如果有）。

不相等性

`assertGreaterThan`	`assertGreaterThan(testCase,actual,floor,diagnostic)` 断言 `actual` 的所有元素都大于 `floor` 的所有元素。类似于 `verifyGreaterThan`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `floor` - 最小值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertGreaterThanOrEqual`	`assertGreaterThanOrEqual(testCase,actual,floor,diagnostic)` 断言 `actual` 的所有元素都大于或等于 `floor` 的所有元素。类似于 `verifyGreaterThanOrEqual`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `floor` - 最小值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertLessThan`	`assertLessThan(testCase,actual,ceiling,diagnostic)` 断言 `actual` 的所有元素都小于 `ceiling` 的所有元素。类似于 `verifyLessThan`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `ceiling` - 最大值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertLessThanOrEqual`	`assertLessThanOrEqual(testCase,actual,ceiling,diagnostic)` 断言 `actual` 的所有元素都小于或等于 `ceiling` 的所有元素。类似于 `verifyLessThanOrEqual`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `ceiling` - 最大值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

数组大小

`assertEmpty`	`assertEmpty(testCase,actual,diagnostic)` 断言 `actual` 是空的 MATLAB^® 数组。类似于 `verifyEmpty`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertLength`	`assertLength(testCase,actual,expectedLength,diagnostic)` 断言 `actual` 是具有预期长度的 MATLAB 数组。类似于 `verifyLength`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `expectedLength` - 预期的数组长度。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertNotEmpty`	`assertNotEmpty(testCase,actual,diagnostic)` 断言 `actual` 是非空 MATLAB 数组。类似于 `verifyNotEmpty`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertNumElements`	`assertNumElements(testCase,actual,expectedNumElements,diagnostic)` 断言 `actual` 是具有预期元素数的 MATLAB 数组。类似于 `verifyNumElements`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `expectedNumElements` - 预期的元素数。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。
`assertSize`	`assertSize(testCase,actual,expectedSize,diagnostic)` 断言 `actual` 是具有预期大小的 MATLAB 数组。类似于 `verifySize`。输入参量 `testCase` - 测试用例。 `actual` - 要测试的值。 `expectedSize` - 预期的数组大小。 `diagnostic` - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

类型

assertClass

assertClass(testCase,actual,class,diagnostic)

断言 actual 的类是指定的类。类似于 verifyClass。

输入参量

testCase - 测试用例。
actual - 要测试的值。
class - 预期的类，指定为字符串标量、字符向量或 matlab.metadata.Class 实例。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

assertInstanceOf

assertInstanceOf(testCase,actual,class,diagnostic)

断言 actual 是指定类的实例。类似于 verifyInstanceOf。

输入参量

testCase - 测试用例。
actual - 要测试的值。
class - 预期的类，指定为字符串标量、字符向量或 matlab.metadata.Class 实例。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

字符串

assertMatches

assertMatches(testCase,actual,expression,diagnostic)

断言 actual 是一个与指定的正则表达式匹配的字符串标量或字符向量。类似于 verifyMatches。

输入参量

testCase - 测试用例。
actual - 要测试的值。
expression - 要匹配的正则表达式。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

assertSubstring

assertSubstring(testCase,actual,substring,diagnostic)

断言 actual 是一个包含 substring 的字符串标量或字符向量。类似于 verifySubstring。

输入参量

testCase - 测试用例。
actual - 要测试的值。
substring - actual 值中包含的文本。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

基线

assertEqualsBaseline（需要 MATLAB Test™）

assertEqualsBaseline(testCase,actual,baseline,diagnostic,Name=Value)

断言 actual 严格等于 baseline 表示的基线数据。类似于 verifyEqualsBaseline (MATLAB Test)。

输入参量

testCase - 测试用例。
actual - 要测试的值。
baseline - 基线数据的表示，指定为 matlabtest.baselines.MATFileBaseline 对象。
diagnostic - 鉴定通过或失败时显示的诊断信息。有关详细信息，请参阅诊断。

名称-值参量

AbsTol - 绝对容差，指定为非负实数标量。
RelTol - 相对容差，指定为非负实数标量。

事件

事件名称触发器事件数据事件属性

事件名称	触发器	事件数据	事件属性
`AssertionFailed`	断言失败时触发。`QualificationEventData` 对象传递给侦听程序回调函数。	`matlab.unittest.qualifications.QualificationEventData`	`NotifyAccess: private` `ListenAccess: public`
`AssertionPassed`	通过断言时触发。`QualificationEventData` 对象传递给侦听程序回调函数。	`matlab.unittest.qualifications.QualificationEventData`	`NotifyAccess: private` `ListenAccess: public`

AssertionFailed

断言失败时触发。QualificationEventData 对象传递给侦听程序回调函数。

matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

AssertionPassed

通过断言时触发。QualificationEventData 对象传递给侦听程序回调函数。

matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

示例

全部折叠

验证测试的前提条件

打开实时脚本

测试写入临时文件夹中的文本文件。使用断言使测试失败，如果无法打开文件，则跳过对文件的写入。

在当前文件夹中名为 TextFileTest.m 的文件中，创建 TextFileTest 类，该类测试将数据写入在临时文件夹中打开的一个文本文件。如果无法打开文件进行写入，则测试失败，并通过使用断言跳过其余测试内容。

classdef TextFileTest < matlab.unittest.TestCase
    methods (Test)
        function testWithTemporaryFolder(testCase)
            folder = testCase.createTemporaryFolder();
            file = fullfile(folder,"myFile.txt");
            fid = fopen(file,"w");
            testCase.addTeardown(@fclose,fid)
            testCase.assertNotEqual(fid,-1,"IO Problem")
            
            txt = repmat("ab",1,1000);
            dataToWrite = join(txt);
            fprintf(fid,"%s",dataToWrite);
            testCase.verifyEqual(string(fileread(file)),dataToWrite)
        end
    end
end

运行 TextFileTest 类。在此示例中，断言通过，测试运行完毕。

runtests("TextFileTest")

Running TextFileTest
.
Done TextFileTest
__________

ans = 
  TestResult with properties:

          Name: 'TextFileTest/testWithTemporaryFolder'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 0.0467
       Details: [1×1 struct]

Totals:
   1 Passed, 0 Failed, 0 Incomplete.
   0.046653 seconds testing time.

详细信息

全部展开

诊断

根据测试运行器的配置，测试框架可能会在鉴定通过或失败时显示诊断信息。默认情况下，框架仅在鉴定失败时显示诊断信息。您可以通过自定义测试运行器来覆盖默认行为。例如，您可以使用 DiagnosticsOutputPlugin 实例来显示失败和通过事件诊断信息。

要将诊断消息添加到测试用例中，请在任何鉴定方法中使用可选的 diagnostic 参量。您可以将 diagnostic 指定为字符串数组、字符数组、函数句柄或 matlab.automation.diagnostics.Diagnostic 对象数组。

异常安全

测试内容有时会更改其环境的状态。当环境可以还原到其原始状态时，即使存在异常，内容也满足异常安全条件。异常安全可确保抛出异常的测试不会因破坏环境而影响后续测试。为了实现异常安全，请使用 addTeardown 方法执行所有拆解操作。在原始状态更改之前或之后立即调用 addTeardown，中间没有任何可能抛出异常的其他代码。

例如，下面的代码不满足异常安全条件。如果测试失败，测试框架不会关闭图窗。此图窗的存在可能导致后续测试失败。

% Not exception safe
f = figure;
testCase.assertEqual(actual,expected)
close(f)

另一方面，以下代码满足异常安全条件，因为不管测试结果如何，框架都会关闭图窗。

% Exception safe
f = figure;
testCase.addTeardown(@close,f)
testCase.assertEqual(actual,expected)

使用 addTeardown 拆解脚手架并不能保证代码就是异常安全的。以下代码不满足异常安全条件，因为对 addTeardown 的调用是在测试后进行的。如果测试失败，框架不会关闭图窗。

% Not exception safe
f = figure;
testCase.assertEqual(actual,expected)
testCase.addTeardown(@close,f)

版本历史记录

在 R2013a 中推出

全部展开

R2024b: 测试值是否等于基线数据

如果您有 MATLAB Test 许可证，可以使用 assertEqualsBaseline 方法来测试某个值是否等于基线数据。

另请参阅

类

matlab.unittest.qualifications.Verifiable | matlab.unittest.qualifications.Assumable | matlab.unittest.qualifications.FatalAssertable | matlab.unittest.TestCase | matlab.unittest.qualifications.QualificationEventData

主题

验证、断言及其他鉴定一览表