matlab.unittest.qualifications.Assumable Class
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
orTestMethodTeardown
method — The framework marks theTest
method to run for that method instance as filtered.TestClassSetup
orTestClassTeardown
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
Public Methods
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 the
Verifiable
class. They differ only in terms of
qualification type. You can call the Assumable
methods in the same way you
call the Verifiable
methods.
assumeEqual |
Assume
that Input Arguments
Name-Value Arguments
|
assumeFail |
Produce
an unconditional assumption failure. Similar to Input Arguments
|
assumeFalse |
Assume
that the value of Input Arguments
|
assumeNotEqual |
Assume
that Input Arguments
|
assumeNotSameHandle |
Assume
that Input Arguments
|
assumeReturnsTrue |
Assume
that Input Arguments
|
assumeSameHandle |
Assume
that Input Arguments
|
assumeThat |
Assume
that Input Arguments
|
assumeTrue |
Assume
that the value of Input Arguments
|
assumeError |
Assume
that Input Arguments
Output Arguments
|
assumeWarning |
Assume
that Input Arguments
Output Arguments
|
assumeWarningFree |
Assume
that Input Arguments
Output Arguments
|
assumeGreaterThan |
Assume
that all elements of Input Arguments
|
assumeGreaterThanOrEqual |
Assume
that all elements of Input Arguments
|
assumeLessThan |
Assume
that all elements of Input Arguments
|
assumeLessThanOrEqual |
Assume
that all elements of Input Arguments
|
assumeEmpty |
Assume
that Input Arguments
|
assumeLength |
Assume
that Input Arguments
|
assumeNotEmpty |
Assume
that Input Arguments
|
assumeNumElements |
Assume
that Input Arguments
|
assumeSize |
Assume
that Input Arguments
|
assumeClass |
Assume
that the class of Input Arguments
|
assumeInstanceOf |
Assume
that Input Arguments
|
assumeMatches |
Assume
that Input Arguments
|
assumeSubstring |
Assume
that Input Arguments
|
assumeEqualsBaseline (requires MATLAB
Test™) |
Assume
that Input Arguments
Name-Value Arguments
|
Events
Event Name | Trigger | Event Data | Event Attributes |
---|---|---|---|
AssumptionFailed | Triggered upon failing assumption. A QualificationEventData
object is passed to listener callback functions. | matlab.unittest.qualifications.QualificationEventData |
|
AssumptionPassed | Triggered upon passing assumption. A QualificationEventData
object is passed to listener callback functions. | matlab.unittest.qualifications.QualificationEventData |
|
Examples
Run Tests Only on Linux Platform
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
Diagnostics
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 optional
diagnostic
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.
Exception Safe
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 to
addTeardown
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 R2013aR2024b: Test if value is equal to baseline data
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
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)