matlab.unittest.qualifications.Assumable - Qualification to filter test content - MATLAB (original) (raw)

Namespace: matlab.unittest.qualifications

Qualification to filter test content

Description

The Assumable class provides a qualification to filter test content. Apart from actions performed for failures, the Assumable class works the same as other qualification classes in the matlab.unittest.qualifications namespace.

Upon an assumption failure, the Assumable class informs the testing framework of the failure by throwing an AssumptionFailedException object. The framework then marks the current test content as filtered and continues testing. Assumptions ensure that a test is run only when certain preconditions are met, but running the test without satisfying the preconditions does not produce a test failure. If the unmet preconditions are meant to produce a test failure, use assertions instead of assumptions.

When an assumption failure is produced within a method of the TestCase class, the type of the method determines which tests are filtered:

• Test method — The framework marks the entireTest method as filtered.
• TestMethodSetup or TestMethodTeardown method — The framework marks the Test method to run for that method instance as filtered.
• TestClassSetup or TestClassTeardown method — The framework marks the entire test class as filtered.

When you use assumptions, ensure that your test content is exception safe. Because assumptions do not produce test failures, portions of your test code might silently be filtered. To avoid the creation of dead test code, consider monitoring your filtered tests.

The matlab.unittest.qualifications.Assumable class is a handle class.

Methods

expand all

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

Note

The methods of the Assumable class correspond to the methods of theVerifiable class. They differ only in terms of qualification type. You can call the Assumable 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

Use an assumption to ensure that your tests can run only on a Linux® platform. Instruct the testing framework to filter the tests if MATLAB is installed on a Microsoft® Windows® or macOS platform.

In a file in your current folder, create the LinuxTests class. To test for the platform, define the testPlatform method within a TestClassSetup methods block. The method uses a call to the assumeTrue method to test that MATLAB is installed on a Linux platform. If the assumption fails, the framework filters the entire test class.

classdef LinuxTests < matlab.unittest.TestCase methods (TestClassSetup) function testPlatform(testCase) testCase.assumeTrue(isunix && ~ismac, ... "Tests must run on a Linux platform.") end end end

Define your tests within a methods block with the Test attribute. The tests in this example are for illustration purposes only.

classdef LinuxTests < matlab.unittest.TestCase methods (TestClassSetup) function testPlatform(testCase) testCase.assumeTrue(isunix && ~ismac, ... "Tests must run on a Linux platform.") end end

methods (Test)
    function test1(testCase)
        testCase.verifyWarningFree(@rand)
    end
    function test2(testCase)
        testCase.verifyWarningFree(@() size([]))
    end
end

end

Run the tests on a Windows machine. Because the assumption fails at the class-setup level, the framework filters the tests defined by the LinuxTests class.

Running LinuxTests

================================================================================ All tests in LinuxTests were filtered. Test Diagnostic: Tests must run on a Linux platform. Details

Done LinuxTests

Failure Summary:

 Name              Failed  Incomplete  Reason(s)
===============================================================
 LinuxTests/test1              X       Filtered by assumption.
---------------------------------------------------------------
 LinuxTests/test2              X       Filtered by assumption.

ans = 1×2 TestResult array with properties:

Name
Passed
Failed
Incomplete
Duration
Details

Totals: 0 Passed, 0 Failed, 2 Incomplete. 0.27782 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.assumeEqual(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.assumeEqual(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.assumeEqual(actual,expected) testCase.addTeardown(@close,f)

Version History

Introduced in R2013a

expand all

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

See Also

Classes

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

Topics

• Table of Verifications, Assertions, and Other Qualifications
• Dynamically Filtered Tests