Documentation Center

  • Trial Software
  • Product Updates

matlab.unittest.qualifications.Assumable class

Package: matlab.unittest.qualifications

Qualification to filter test content

Description

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

Upon an assumption failure, the Assumable class informs the testing framework of the failure by throwing an AssumptionFailedException. The test framework then marks the test content as filtered and continues testing. Often, assumptions are used to ensure that the test is run only when certain preconditions are met. However, running the test without satisfying the preconditions does not produce a test failure. Ensure that the test content is Exception Safe. If the failure condition is meant to produce a test failure, use assertions or verifications instead of assumptions.

The attributes specified in the TestCase method definition determine which tests are filtered. The following behavior occurs when the test framework encounters an assumption failure inside of a TestCase method:

  • If you define the TestCase method using the Test attribute, the framework marks the entire method as filtered and runs subsequent test methods.

  • If you define the TestCase method using the TestMethodSetup or TestMethodTeardown attributes, the test framework marks the method to run for that instance as filtered.

  • If you define the TestCase method using the TestClassSetup or TestClassTeardown attributes, the test framework filters the entire TestCase class.

Filtering test content using assumptions does not produce test failures. Therefore, dead test code can result. Avoid this by monitoring filtered tests.

Methods

assumeClassAssume exact class of specified value
assumeEmptyAssume value is empty
assumeEqualAssume value is equal to specified value
assumeErrorAssume function throws specified exception
assumeFailProduce unconditional assumption failure
assumeFalseAssume value is false
assumeGreaterThanAssume value is greater than specified value
assumeGreaterThanOrEqualAssume value is greater than or equal to specified value
assumeInstanceOfAssume value is object of specified type
assumeLengthAssume value has specified length
assumeLessThanAssume value is less than specified value
assumeLessThanOrEqualAssume value is less than or equal to specified value
assumeMatchesAssume string matches specified regular expression
assumeNotEmptyAssume value is not empty
assumeNotEqualAssume value is not equal to specified value
assumeNotSameHandleAssume value is not handle to specified instance
assumeNumElementsAssume value has specified element count
assumeReturnsTrueAssume function returns true when evaluated
assumeSameHandleAssume two values are handles to same instance
assumeSizeAssume value has specified size
assumeSubstringAssume string contains specified string
assumeThatAssume value meets specified constraint
assumeTrueAssume value is true
assumeWarningAssume function issues specified warning
assumeWarningFreeAssume function issues no warnings

Events

AssumptionFailed

Triggered upon failing assumption. A QualificationEventData object is passed to listener callback functions.

AssumptionPassed

Triggered upon passing assumption. A QualificationEventData object is passed to listener callback functions.

Definitions

Exception Safe

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.assumeEqual(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.assumeEqual(actual, expected);

However, tearing down a fixture using addTeardown does not guarantee code is exception safe. This code shows a failure in assumeEqual.

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

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Examples

expand all

Write TestClassSetup Method Using Assumptions

Assumptions assure that a test runs only when certain preconditions are satisfied and when such an event should not produce a test failure. When an assumption failure occurs, the test is marked as filtered.

Create IsSupportedTest test case. Refer to the following IsSupportedTest test case in the subsequent steps in this example, which highlight specific functions in the file.

 IsSupportedTest Class Definition File

To execute the MATLAB commands in this example, add the IsSupportedTest.m file to a folder on your MATLAB path.

Write Test to Verify Platform. All tests in this test case must run on UNIX® platforms only. The TestPlatform function uses the assumeFalse method to test if MATLAB is running on a Windows® platform. If it is, the test fails.

function TestPlatform(testcase)
    testcase.assumeFalse(ispc,...
        'Do not run any of these tests on Windows.');
end

Make TestPlatform a TestClassSetup Test. To make the TestPlatform test a precondition, add it inside the methods (TestClassSetup) block.

Run the test case. Create a test case object and run the tests on a Windows platform.

tc = IsSupportedTest;
res = tc.run;
Running IsSupportedTest

================================================================================
All tests in IsSupportedTest were filtered.
    Test Diagnostic: Do not run any of these tests on Windows.
    Details
================================================================================

Done IsSupportedTest
__________

Failure Summary:

     Name                   Failed  Incomplete  Reason(s)
    ====================================================================
     IsSupportedTest/test1              X       Filtered by assumption.

The test(s) were filtered, and did not run (marked Incomplete).

For more information, click the Details link.

================================================================================
The TestClassSetup or TestClassTeardown for IsSupportedTest was filtered by an assumption.
All tests in this class were also filtered as a result.

    ----------------
    Test Diagnostic:
    ----------------
    Do not run any of these tests on Windows.

    ---------------------
    Framework Diagnostic:
    ---------------------
    assumeFalse failed.
    --> The value must evaluate to "false".
    
    Actual Value:
             1

    ------------------
    Stack Information:
    ------------------
    In C:\Program Files\MATLAB\R2013a\toolbox\matlab\testframework\+matlab\+unittest\+qualifications\Assumable.m (Assumable.assumeFalse) at 331
    In c:\work\IsSupportedTest.m (IsSupportedTest.TestPlatform) at 4
================================================================================

The link to IsSupportedTest.TestPlatform under Stack Information takes you to the failed assumeFalse method.

See Also

| | | | |

More About

Was this topic helpful?