matlab.unittest.qualifications.Assertable class

Package: 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 matlab.unittest qualifications.

Upon an assertion failure, the Assertable class throws an AssertionFailedException to inform the testing framework of the failure. This is most useful when a failure at the assertion point renders the rest of the current test method invalid, yet does not prevent proper execution of other test methods. Often, you use assertions to ensure that preconditions of the current test are not violated or that fixtures are set up correctly. Make sure the test content is Exception Safe. If you cannot make the fixture teardown exception safe or if you cannot recover it after failure, use fatal assertions instead.

Use assertions to allow remaining test methods to receive coverage when preconditions are violated in a test and all fixture states are restorable. Assertions also reduce the noise level of failures by not performing later verifications that fail due the precondition failures. In the event of a failure, however, the test framework marks the full content of the test method that failed as incomplete. Therefore, if the failure does not affect the preconditions of the test or cause problems with fixture setup or teardown, use verifications, which give the added information that the full test content was run.

Methods

assertClass	Assert exact class of specified value
assertEmpty	Assert value is empty
assertEqual	Assert value is equal to specified value
assertError	Assert function throws specified exception
assertFail	Produce unconditional assertion failure
assertFalse	Assert value is false
assertGreaterThan	Assert value is greater than specified value
assertGreaterThanOrEqual	Assert value is greater than or equal to specified value
assertInstanceOf	Assert value is object of specified type
assertLength	Assert value has specified length
assertLessThan	Assert value is less than specified value
assertLessThanOrEqual	Assert value is less than or equal to specified value
assertMatches	Assert string matches specified regular expression
assertNotEmpty	Assert value is not empty
assertNotEqual	Assert value is not equal to specified value
assertNotSameHandle	Assert value is not handle to specified instance
assertNumElements	Assert value has specified element count
assertReturnsTrue	Assert function returns true when evaluated
assertSameHandle	Assert two values are handles to same instance
assertSize	Assert value has specified size
assertSubstring	Assert string contains specified string
assertThat	Assert that value meets specified constraint
assertTrue	Assert value is true
assertWarning	Assert function issues specified warnings
assertWarningFree	Assert function issues no warnings

Events

AssertionFailed	Triggered upon failing assertion. A QualificationEventData object is passed to listener callback functions.
AssertionPassed	Triggered upon passing assertion. A QualificationEventData object is passed to listener callback functions.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Examples

Test for Preconditions Using Assertions

Use assertable qualifications to test for preconditions. This example will create a test case to write a polynomial to a MAT-file.

Create DocPolynomSaveLoadTest Test Case. Refer to the following DocPolynomSaveLoadTest test case in the subsequent steps in this example. The steps highlight specific code in the testSaveLoad function; the code statements are not intended to be executed outside the context of the class definition file.

 DocPolynomSaveLoadTest Class Definition File

classdef DocPolynomSaveLoadTest < matlab.unittest.TestCase 
    
    methods (TestClassSetup) 
        function addDocPolynomClassToPath(testCase) 
            origPath = path; 
            testCase.addTeardown(@path, origPath); 
            addpath(fullfile(matlabroot, ... 
                'help', 'techdoc', 'matlab_oop', 'examples')); 
        end 
    end 
     
    methods (Test) 
        function testSaveLoad(testCase) 
             
            import matlab.unittest.diagnostics.Diagnostic; 
             
            %% Phase 1: Setup 
            % Create a temporary working folder 
            tempFolder = tempname; 
            [success, message] = mkdir(tempFolder); 
            testCase.assertTrue(success, ... 
                Diagnostic.join('Could not create temporary folder.',... 
                message)); 
            testCase.addTeardown(@() testCase.cleanUpTemporaryFolder(...
                tempFolder)); 
             
            % Change to the temporay folder and register the 
            % teardown, which restores the original folder 
            origFolder = pwd; 
            testCase.addTeardown(@cd, origFolder); 
            cd(tempFolder); 
             
            %% Phase 2: Exercise 
            % Save the instance to a mat file. 
            p = DocPolynom([1, 0, 1]); 
            save('DocPolynomFile', 'p'); 
             
            % Validate Precondition. Save resulted in valid .mat file 
            testCase.assertEqual(exist('DocPolynomFile.mat','file'),... 
                2, Diagnostic.join(...
                'mat file was not saved correctly.',@() dir(pwd))); 
             
            loaded = load('DocPolynomFile'); 
             
             
            %% Phase 3: Verify             
            testCase.verifyEqual(loaded.p, p,...
                'Loaded polynom did not equal original polynom.');
             
             
            %% Phase 4: Teardown 
            % Done inline via calls to addTeardown at the points
            % at which the state was changed. 

             
        end 
    end 
     
    methods(Access=private) 
        function cleanUpTemporaryFolder(testCase,tempFolder)
            % Clean up the temporary folder and fatally assert
            % that it was correctly cleaned up.
             
            import matlab.unittest.diagnostics.Diagnostic; 
             
            [success, message] = rmdir(tempFolder, 's'); 
            testCase.fatalAssertTrue(success, ... 
                Diagnostic.join('Could not remove temporary folder.',... 
                message)); 
        end 
    end 
             
end 

To execute the MATLAB^® commands in “Run DocPolynomSaveLoadTest Test Case”, add the DocPolynomSaveLoadTest.m file to a folder on your MATLAB path.

The testSaveLoad function consists of the following phases:

• Phase 1: Setup — Create and verify precondition code.

• Phase 2: Exercise — Create a DocPolynom object and save it to a MAT-file.

• Phase 3: Verify — Test that object was successfully saved.

• Phase 4: Teardown — Execute teardown code.

Define phase 1 precondition. For this test, use a temporary folder for creating a DocPolynom object. The precondition for continuing with this test is that the following commands execute successfully.

tempFolder = tempname; 
[success, message] = mkdir(tempFolder); 

Test the results of the mkdir function. Use the assertTrue method to test the mkdir success argument for errors. If an assertion occurs, the remainder of the testSaveLoad test method is invalid, and the test is marked Incomplete.

testCase.assertTrue(success, ... 
    Diagnostic.join('Could not create the temporary folder.', ... 
        message)) 

If the mkdir function fails, MATLAB displays the diagnostic message, Could not create the temporary folder, as well as the contents of the mkdir message argument.

Add teardown fixture code. Creating a temporary folder is setup code, which requires a corresponding call to the rmdir function to restore MATLAB to the original state. Use the addTeardown method to ensure the teardown code executes even when an exception is thrown in the middle of the test method. This makes the test Exception Safe.

testCase.addTeardown(@() testCase.cleanUpTemporaryFolder(tempFolder)) 

Place teardown code in the helper function. Although the addTeardown statement occurs in the same code block as the mkdir setup statement, the cleanUpTemporaryFolder code is executed in phase 4 of the test method.

In the DocPolynomSaveLoadTest test case, the helper function, cleanUpTemporaryFolder, executes the rmdir function.

Define the precondition for creating valid MAT-File. A precondition for verifying that the DocPolynom object was correctly saved and loaded is that the MAT-file, DocPolynomFile.mat, was successfully created. The following code in the Phase 2: Exercise block tests this condition. If an assertion occurs, the remainder of the testSaveLoad test method is invalid, and the test is marked Failed and Incomplete.

 testCase.assertEqual(exist('DocPolynomFile.mat','file'), 2, ... 
     Diagnostic.join('The mat file was not saved correctly.', ...
     @() dir(pwd)))

If the file was not created, MATLAB displays the diagnostic message, The mat file was not saved correctly, as well as the contents of the temporary folder.

Run DocPolynomSaveLoadTest Test Case.

tc = DocPolynomSaveLoadTest;
run(tc);

Running DocPolynomSaveLoadTest
.
Done DocPolynomSaveLoadTest
__________

More About

Exception Safe

Test content is exception safe when all fixture teardown is performed with addTeardown or through the appropriate object destructors when a failure occurs. This ensures that the failure does not affect later testing due to stale fixtures.

This code is not exception safe. After an assertion failure, the test framework does not close the figure.

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

This code is exception safe because the test framework closes the figure in all cases.

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

However, tearing down a fixture using addTeardown does not guarantee code is exception safe. This code shows a failure in assertEqual.

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