Qualification to filter test content
Assumable class provides a qualification
to filter test content. Apart from actions performed in the event
of failures, the
Assumable class works the same
Upon an assumption failure, the
informs the testing framework of the failure by throwing an
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
definition determine which tests are filtered. The following behavior
occurs when the test framework encounters an assumption failure inside
If you define the
Test attribute, the framework marks the
entire method as filtered and runs subsequent test methods.
If you define the
the test framework marks the method to run for that instance as filtered.
If you define the
the test framework filters the entire
Filtering test content using assumptions does not produce test failures. Therefore, dead test code can result. Avoid this by monitoring filtered tests.
|assumeClass||Assume exact class of specified value|
|assumeEmpty||Assume value is empty|
|assumeEqual||Assume value is equal to specified value|
|assumeError||Assume function throws specified exception|
|assumeFail||Produce unconditional assumption failure|
|assumeFalse||Assume value is false|
|assumeGreaterThan||Assume value is greater than specified value|
|assumeGreaterThanOrEqual||Assume value is greater than or equal to specified value|
|assumeInstanceOf||Assume value is object of specified type|
|assumeLength||Assume value has specified length|
|assumeLessThan||Assume value is less than specified value|
|assumeLessThanOrEqual||Assume value is less than or equal to specified value|
|assumeMatches||Assume string matches specified regular expression|
|assumeNotEmpty||Assume value is not empty|
|assumeNotEqual||Assume value is not equal to specified value|
|assumeNotSameHandle||Assume value is not handle to specified instance|
|assumeNumElements||Assume value has specified element count|
|assumeReturnsTrue||Assume function returns true when evaluated|
|assumeSameHandle||Assume two values are handles to same instance|
|assumeSize||Assume value has specified size|
|assumeSubstring||Assume string contains specified string|
|assumeThat||Assume value meets specified constraint|
|assumeTrue||Assume value is true|
|assumeWarning||Assume function issues specified warning|
|assumeWarningFree||Assume function issues no warnings|
Triggered upon failing assumption. A
Triggered upon passing assumption. A
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.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
not guarantee code is exception safe. This code shows a failure in
% Not exception safe f = figure; testCase.assumeEqual(actual, expected) testCase.addTeardown(@close, f)
Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB® documentation.
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.
IsSupportedTest test case. Refer
to the following
IsSupportedTest test case in the
subsequent steps in this example, which highlight specific functions
in the file.
To execute the MATLAB commands in this example,
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
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
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
For more information, click the Details link.
================================================================================ An assumption was not met while setting up or tearing down IsSupportedTest. As a result, all IsSupportedTest tests were filtered. ---------------- 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:\work\IsSupportedTest.m (IsSupportedTest.TestPlatform) at 4 ================================================================================
The link to
Information takes you to the failed