Qualification to validate preconditions of a test
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.
|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 warning|
|assertWarningFree||Assert function issues no warnings|
Triggered upon failing assertion. A QualificationEventData object is passed to listener callback functions.
Triggered upon passing assertion. A QualificationEventData object is passed to listener callback functions.
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);
Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB® documentation.
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.
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.
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 __________