matlab.unittest.qualifications.Assumable Class

Namespace: matlab.unittest.qualifications

Qualification to filter test content

expand all in page

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 entire Test 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

Events

Event NameTriggerEvent DataEvent Attributes
AssumptionFailedTriggered upon failing assumption. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

AssumptionPassedTriggered upon passing assumption. A QualificationEventData object is passed to listener callback functions.matlab.unittest.qualifications.QualificationEventData

NotifyAccess: private

ListenAccess: public

Examples

collapse all

Open Live Script

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.

runtests("LinuxTests")
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

Version History

Introduced in R2013a

expand all

See Also

Classes

Topics