matlab.unittest.qualifications.Assertable - Qualification to validate preconditions of a test - MATLAB (original) (raw)

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 entireTest 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

The Assertable class provides several qualification methods for testing values and responding to failures. For example, assertEmpty tests that a value is empty, and assertTrue tests that the actual value is true.

Note

The methods of the Assertable class correspond to the methods of theVerifiable class. They differ only in terms of qualification type. You can call the Assertable methods in the same way you call the Verifiable methods.

General Purpose

Errors and Warnings

Inequalities

Array Size

Type

Strings

Baselines

Events

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.

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

Depending on the test runner configuration, the testing framework might display diagnostics when a qualification passes or fails. By default, the framework displays diagnostics only when the qualification fails. You can override the default behavior by customizing the test runner. For example, you can use a DiagnosticsOutputPlugin instance to display both failing and passing event diagnostics.

To add a diagnostic message to a test case, use the optionaldiagnostic argument in any of the qualification methods. You can specify diagnostic as a string array, character array, function handle, or array of matlab.automation.diagnostics.Diagnostic objects.

Test content sometimes changes the state of its environment. The content is exception safe when the environment can be restored to its original state, even in the presence of exceptions. Exception safety ensures that a test that throws an exception does not affect subsequent tests by corrupting the environment. To achieve exception safety, perform all teardown actions using the addTeardown method. Call addTeardown immediately before or after the original state change, without any other code in between that can throw an exception.

For example, this code is not exception safe. If the test fails, the testing framework does not close the figure. The presence of this figure might cause subsequent tests to fail.

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

On the other hand, this code is exception safe, because the framework closes the figure regardless of the test outcome.

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

Tearing down a fixture using addTeardown does not guarantee that code is exception safe. This code is not exception safe, because the call toaddTeardown is after the test. If the test fails, the framework does not close the figure.

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

Version History

Introduced in R2013a

expand all

If you have a MATLAB Test license, you can use the assertEqualsBaseline method to test if a value is equal to baseline data.

See Also

Classes

• matlab.unittest.qualifications.Verifiable | matlab.unittest.qualifications.Assumable | matlab.unittest.qualifications.FatalAssertable | matlab.unittest.TestCase | matlab.unittest.qualifications.QualificationEventData

Topics

• Table of Verifications, Assertions, and Other Qualifications