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 for added information that the full test content was run.

Methods

assertClassAssert exact class of specified value
assertEmptyAssert value is empty
assertEqualAssert value is equal to specified value
assertErrorAssert function throws specified exception
assertFailProduce unconditional assertion failure
assertFalseAssert value is false
assertGreaterThanAssert value is greater than specified value
assertGreaterThanOrEqualAssert value is greater than or equal to specified value
assertInstanceOfAssert value is object of specified type
assertLengthAssert value has specified length
assertLessThanAssert value is less than specified value
assertLessThanOrEqualAssert value is less than or equal to specified value
assertMatchesAssert string matches specified regular expression
assertNotEmptyAssert value is not empty
assertNotEqualAssert value is not equal to specified value
assertNotSameHandleAssert value is not handle to specified instance
assertNumElementsAssert value has specified element count
assertReturnsTrueAssert function returns true when evaluated
assertSameHandleAssert two values are handles to same instance
assertSizeAssert value has specified size
assertSubstringAssert string contains specified string
assertThatAssert that value meets specified constraint
assertTrueAssert value is true
assertWarningAssert function issues specified warning 
assertWarningFreeAssert 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.

Definitions

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);

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Examples

expand all

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

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
__________
Was this topic helpful?