Main Content

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

expand all

Events

Event NameTriggerEvent DataEvent Attributes
AssertionFailedTriggered upon failing assertion. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

AssertionPassedTriggered upon passing assertion. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

Examples

collapse all

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

expand all

Version History

Introduced in R2013a

expand all