matlab.unittest.qualifications.Assertable Class

Namespace: matlab.unittest.qualifications

Qualification to validate preconditions of a test

Description

The Assertable class provides a qualification to validate preconditions of a test. Apart from actions performed for failures, the Assertable class works the same as other qualification classes in the matlab.unittest.qualifications namespace.

Upon an assertion failure, the Assertable class informs the testing framework of the failure by throwing an AssertionFailedException object. This behavior is most useful when a failure at the assertion point renders the remainder of the current test invalid, but does not prevent proper execution of subsequent tests. Often, you use assertions to ensure that preconditions of the current test are not violated or that fixtures are set up correctly. If you cannot make the fixture teardown exception safe or restore the environment state after failure, use fatal assertions instead.

When an assertion failure is produced within a method of the TestCase class, the type of the method determines which tests are affected:

• Test method — The framework marks the entire Test method as failed and incomplete.

• TestMethodSetup or TestMethodTeardown method — The framework marks the Test method to run for that method instance as failed and incomplete.

• TestClassSetup or TestClassTeardown method — The framework marks the entire test class as failed and incomplete.

Assertions let remaining tests receive coverage when preconditions are violated in a test but the state is recoverable. They prevent unnecessary failures by not performing later verifications that fail due to invalidated preconditions. If the failure does not affect the preconditions of the test or cause problems with fixture setup or teardown, use verifications, which ensure that the full test content runs.

The matlab.unittest.qualifications.Assertable class is a handle class.

Methods

Public Methods

The Assertable class provides several qualification methods for testing values and responding to failures. For example, assertEmpty tests that a value is empty, and assertTrue tests that the actual value is true.

Note

The methods of the Assertable class correspond to the methods of the Verifiable class. They differ only in terms of qualification type. You can call the Assertable methods in the same way you call the Verifiable methods.

General Purpose

assertEqual	assertEqual(testCase,actual,expected,diagnostic,Name,Value) Assert that actual is strictly equal to expected. Similar to verifyEqual. Input Arguments testCase — Test case. actual — Value to test. expected — Expected value. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Name-Value Arguments AbsTol — Absolute tolerance, specified as a numeric array. RelTol — Relative tolerance, specified as a numeric array.
assertFail	assertFail(testCase,diagnostic) Produce an unconditional assertion failure. Similar to verifyFail. Input Arguments testCase — Test case. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertFalse	assertFalse(testCase,actual,diagnostic) Assert that the value of actual is logical 0 (false). Similar to verifyFalse. Input Arguments testCase — Test case. actual — Value to test. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertNotEqual	assertNotEqual(testCase,actual,prohibited,diagnostic) Assert that actual is not equal to prohibited. Similar to verifyNotEqual. Input Arguments testCase — Test case. actual — Value to test. prohibited — Value to compare against. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertNotSameHandle	assertNotSameHandle(testCase,actual,prohibited,diagnostic) Assert that actual is not the same as the prohibited handle array. Similar to verifyNotSameHandle. Input Arguments testCase — Test case. actual — Value to test. prohibited — Value to compare against, specified as a handle array. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertReturnsTrue	assertReturnsTrue(testCase,actual,diagnostic) Assert that actual is a function handle that returns the logical scalar 1 (true). Similar to verifyReturnsTrue. Input Arguments testCase — Test case. actual — Value to test. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertSameHandle	assertSameHandle(testCase,actual,expected,diagnostic) Assert that actual is the same as the expected handle array. Similar to verifySameHandle. Input Arguments testCase — Test case. actual — Value to test. expected — Expected value, specified as a handle array. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertThat	assertThat(testCase,actual,constraint,diagnostic) Assert that actual is a value that satisfies the specified constraint. Similar to verifyThat. Input Arguments testCase — Test case. actual — Value to test. constraint — Constraint that the actual value must satisfy, specified as an instance of the matlab.unittest.constraints.Constraint class. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertTrue	assertTrue(testCase,actual,diagnostic) Assert that the value of actual is logical 1 (true). Similar to verifyTrue. Input Arguments testCase — Test case. actual — Value to test. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Errors and Warnings

assertError	[output1,...,outputN] = assertError(testCase,actual,identifier,diagnostic) Assert that actual is a function handle that throws the exception specified by identifier. Similar to verifyError. Input Arguments testCase — Test case. actual — Value to test. identifier — Error identifier, specified as a string scalar, character vector, or matlab.metadata.Class instance. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Output Arguments output1,...,outputN — Output arguments, 1 through N, requested from actual.
assertWarning	[output1,...,outputN] = assertWarning(testCase,actual,identifier,diagnostic) Assert that actual is a function handle that issues the warning specified by identifier. Similar to verifyWarning. Input Arguments testCase — Test case. actual — Value to test. identifier — Warning identifier, specified as a character vector, cell array of character vectors, or string array. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Output Arguments output1,...,outputN — Output arguments, 1 through N (if any), produced when actual is invoked.
assertWarningFree	[output1,...,outputN] = assertWarningFree(testCase,actual,diagnostic) Assert that actual is a function handle that issues no warnings. Similar to verifyWarningFree. Input Arguments testCase — Test case. actual — Value to test. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Output Arguments output1,...,outputN — Output arguments, 1 through N (if any), produced when actual is invoked.

Inequalities

assertGreaterThan	assertGreaterThan(testCase,actual,floor,diagnostic) Assert that all elements of actual are greater than all elements of floor. Similar to verifyGreaterThan. Input Arguments testCase — Test case. actual — Value to test. floor — Minimum value. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertGreaterThanOrEqual	assertGreaterThanOrEqual(testCase,actual,floor,diagnostic) Assert that all elements of actual are greater than or equal to all elements of floor. Similar to verifyGreaterThanOrEqual. Input Arguments testCase — Test case. actual — Value to test. floor — Minimum value. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertLessThan	assertLessThan(testCase,actual,ceiling,diagnostic) Assert that all elements of actual are less than all elements of ceiling. Similar to verifyLessThan. Input Arguments testCase — Test case. actual — Value to test. ceiling — Maximum value. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertLessThanOrEqual	assertLessThanOrEqual(testCase,actual,ceiling,diagnostic) Assert that all elements of actual are less than or equal to all elements of ceiling. Similar to verifyLessThanOrEqual. Input Arguments testCase — Test case. actual — Value to test. ceiling — Maximum value. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Array Size

assertEmpty	assertEmpty(testCase,actual,diagnostic) Assert that actual is an empty MATLAB® array. Similar to verifyEmpty. Input Arguments testCase — Test case. actual — Value to test. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertLength	assertLength(testCase,actual,expectedLength,diagnostic) Assert that actual is a MATLAB array with the expected length. Similar to verifyLength. Input Arguments testCase — Test case. actual — Value to test. expectedLength — Expected array length. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertNotEmpty	assertNotEmpty(testCase,actual,diagnostic) Assert that actual is a nonempty MATLAB array. Similar to verifyNotEmpty. Input Arguments testCase — Test case. actual — Value to test. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertNumElements	assertNumElements(testCase,actual,expectedNumElements,diagnostic) Assert that actual is a MATLAB array with the expected number of elements. Similar to verifyNumElements. Input Arguments testCase — Test case. actual — Value to test. expectedNumElements — Expected number of elements. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assertSize	assertSize(testCase,actual,expectedSize,diagnostic) Assert that actual is a MATLAB array with the expected size. Similar to verifySize. Input Arguments testCase — Test case. actual — Value to test. expectedSize — Expected array size. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Type

assertClass

assertClass(testCase,actual,class,diagnostic) Assert that the class of actual is the specified class. Similar to verifyClass. Input Arguments testCase — Test case. actual — Value to test. class — Expected class, specified as a string scalar, character vector, or matlab.metadata.Class instance. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

assertInstanceOf

assertInstanceOf(testCase,actual,class,diagnostic) Assert that actual is an instance of the specified class. Similar to verifyInstanceOf. Input Arguments testCase — Test case. actual — Value to test. class — Expected class, specified as a string scalar, character vector, or matlab.metadata.Class instance. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Strings

assertMatches

assertMatches(testCase,actual,expression,diagnostic) Assert that actual is a string scalar or character vector that matches the specified regular expression. Similar to verifyMatches. Input Arguments testCase — Test case. actual — Value to test. expression — Regular expression to match. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

assertSubstring

assertSubstring(testCase,actual,substring,diagnostic) Assert that actual is a string scalar or character vector that contains substring. Similar to verifySubstring. Input Arguments testCase — Test case. actual — Value to test. substring — Text contained within actual value. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Baselines

assertEqualsBaseline (requires MATLAB Test™)

assertEqualsBaseline(testCase,actual,baseline,diagnostic,Name=Value) Assert that actual is strictly equal to the baseline data represented by baseline. Similar to verifyEqualsBaseline (MATLAB Test). Input Arguments testCase — Test case. actual — Value to test. baseline — Representation of the baseline data, specified as a matlabtest.baselines.MATFileBaseline object. diagnostic — Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Name-Value Arguments AbsTol — Absolute tolerance, specified as a nonnegative real scalar. RelTol — Relative tolerance, specified as a nonnegative real scalar.

Events

Event Name	Trigger	Event Data	Event Attributes
AssertionFailed	Triggered upon failing assertion. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public
AssertionPassed	Triggered upon passing assertion. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public

Examples

Validate Precondition of Test

Test writing to a text file within a temporary folder. Use an assertion to fail the test and skip writing to the file if it cannot be opened.

In a file named TextFileTest.m in your current folder, create the TextFileTest class, which tests writing data to a text file opened within a temporary folder. If the file cannot be opened for writing, fail the test and skip the remainder of the test content by using an assertion.

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

Run the TextFileTest class. In this example, the assertion passes and the test runs to completion.

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.

More About

Diagnostics

Depending on the test runner configuration, the testing framework might display diagnostics when a qualification passes or fails. By default, the framework displays diagnostics only when the qualification fails. You can override the default behavior by customizing the test runner. For example, you can use a DiagnosticsOutputPlugin instance to display both failing and passing event diagnostics.

To add a diagnostic message to a test case, use the optional diagnostic argument in any of the qualification methods. You can specify diagnostic as a string array, character array, function handle, or array of matlab.automation.diagnostics.Diagnostic objects.

Exception Safe

Test content sometimes changes the state of its environment. The content is exception safe when the environment can be restored to its original state, even in the presence of exceptions. Exception safety ensures that a test that throws an exception does not affect subsequent tests by corrupting the environment. To achieve exception safety, perform all teardown actions using the addTeardown method. Call addTeardown immediately before or after the original state change, without any other code in between that can throw an exception.

For example, this code is not exception safe. If the test fails, the testing framework does not close the figure. The presence of this figure might cause subsequent tests to fail.

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

On the other hand, this code is exception safe, because the framework closes the figure regardless of the test outcome.

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

Tearing down a fixture using addTeardown does not guarantee that code is exception safe. This code is not exception safe, because the call to addTeardown is after the test. If the test fails, the framework does not close the figure.

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

Version History

Introduced in R2013a

R2024b: Test if value is equal to baseline data

If you have a MATLAB Test license, you can use the assertEqualsBaseline method to test if a value is equal to baseline data.