Qualification to validate preconditions of a test
Assertable class provides a qualification
to validate preconditions of a test. Apart from actions performed
for failures, the
Assertable class works the same
Upon an assertion failure, the
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.
|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
Triggered upon passing assertion. A
Handle. To learn how handle classes affect copy operations, see Copying Objects.
Use assertable qualifications to test for preconditions. This example will create a test case to write a polynomial to a MAT-file.
Case. Refer to the following
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
to a folder on your MATLAB path.
testSaveLoad function consists
of the following phases:
Phase 1: Setup — Create and verify precondition code.
Phase 2: Exercise — Create a
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
tempFolder = tempname; [success, message] = mkdir(tempFolder);
Test the results of the
assertTrue method to test the
for errors. If an assertion occurs, the remainder of the
method is invalid, and the test is marked
testCase.assertTrue(success, ... Diagnostic.join('Could not create the temporary folder.', ... message))
mkdir function fails, MATLAB displays
the diagnostic message,
Could not create the temporary folder,
as well as the contents of the
Add teardown fixture code. Creating a temporary folder
is setup code, which requires a corresponding call to the
to restore MATLAB to the original state. Use the
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
occurs in the same code block as the
cleanUpTemporaryFolder code is executed
in phase 4 of the test method.
DocPolynomSaveLoadTest test case,
the helper function,
Define the precondition for creating valid MAT-File. A
precondition for verifying that the
was correctly saved and loaded is that the MAT-file,
was successfully created. The following code in the
2: Exercise block tests this condition. If an assertion
occurs, the remainder of the
method is invalid, and the test is marked
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
The mat file was not saved correctly,
as well as the contents of the temporary folder.
DocPolynomSaveLoadTest Test Case.
tc = DocPolynomSaveLoadTest; run(tc);
Running DocPolynomSaveLoadTest . Done DocPolynomSaveLoadTest __________
Test content is exception safe when
all fixture teardown is performed with
through the appropriate object destructors when a failure occurs.
This ensures that the failure does not affect later testing due to
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
not guarantee code is exception safe. This code shows a failure in
% Not exception safe f = figure; testCase.assertEqual(actual, expected); testCase.addTeardown(@close, f);