matlab.unittest.TestCase class

Package: matlab.unittest

Superclass of all matlab.unittest test classes

Description

The TestCase class is the means by which a test is written in the matlab.unittest framework. It provides the means to write and identify test content, as well as test fixture setup and teardown routines. Creating such a test requires deriving from TestCase to produce a TestCase subclass. Then, subclasses can leverage the metadata attributes to specify tests and test fixtures.

Construction

Use the forInteractiveUse static method to create a TestCase for interactive, command line use. When tests are run in the framework, TestCase instances are constructed by the matlab.unittest.TestRunner.

Methods

addTeardown	Dynamically add teardown routine to `TestCase` instance
applyFixture	Use fixture with `TestCase`
createTemporaryFolder	Create temporary folder
forInteractiveUse	Create TestCase for interactive use
getSharedTestFixtures	Provide access to shared test fixtures
log	Record diagnostic information during test execution
onFailure	Dynamically add diagnostics for test failures
run	Run `TestCase` test

Inherited Methods

The TestCase class inherits methods from the following classes:

`matlab.unittest.qualifications.Assertable`	Qualification to validate preconditions of a test
`matlab.unittest.qualifications.Assumable`	Qualification to filter test content
`matlab.unittest.qualifications.FatalAssertable`	Qualification to abort test execution
`matlab.unittest.qualifications.Verifiable`	Qualification to produce soft-failure conditions

Attributes

Class Attributes

TestCase objects support the following class level attributes. Specify class-level attributes in the classdef block before the class name.

`SharedTestFixtures`	Class block to contain shared test fixtures. You must define `SharedTestFixtures` as a cell array of `matlab.unittest.fixtures.Fixture` instances.
`TestTags`	Class block to contain tests tagged with a specified value. You must define `TestTags` as a cell array of non-empty character vectors or an array of non-empty strings, where each element is a tag for the test.

Method Attributes

Classes that derive from TestCase can define methods blocks which contain matlab.unittest framework-specific attributes to specify test content.

`Test`	Method block to contain test methods.
`TestMethodSetup`	Method block to contain setup code.
`TestMethodTeardown`	Method block to contain teardown code.
`TestClassSetup`	Method block to contain class level setup code.
`TestClassTeardown`	Method block to contain class level teardown code.
`ParameterCombination`	Method block to contain parameterized testing code. This attribute accepts the following values: `'exhaustive'` (default): Test methods are invoked for all combinations of parameters. `'sequential'`: Test methods are invoked with corresponding values from each parameter. Each parameter must contain the same number of values. `'pairwise'`: Test methods are invoked for every pair of parameter values at least once.
`TestParameterDefinition`	Method block to contain code that initializes parameterization properties at suite creation time. The methods defined using this attribute must be static.
`TestTags`	Method block to contain tests tagged with a specified value. You must define `TestTags` as a cell array of non-empty character vectors or an array of non-empty strings, where each element is a tag for the test.

Property Attributes

Classes that derive from TestCase can define properties blocks which contain matlab.unittest framework-specific attributes to specify test content.

`ClassSetupParameter`	Property block to define parameterization properties for methods in the `TestClassSetup` block.
`MethodSetupParameter`	Property block to define parameterization properties for methods in the `TestMethodSetup` block.
`TestParameter`	Property block to define parameterization properties for methods in the `Test` block.

Events

`VerificationFailed`	Triggered upon failing verification. A `QualificationEventData` object is passed to listener callback functions.
`VerificationPassed`	Triggered upon passing verification. A `QualificationEventData` object is passed to listener callback functions.
`AssertionFailed`	Triggered upon failing assertion. A `QualificationEventData` object is passed to listener callback functions.
`AssertionPassed`	Triggered upon passing assertion. A `QualificationEventData` object is passed to listener callback functions.
`FatalAssertionFailed`	Triggered upon failing fatal assertion. A `QualificationEventData` object is passed to listener callback functions.
`FatalAssertionPassed`	Triggered upon passing fatal assertion. A `QualificationEventData` object is passed to listener callback functions.
`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.
`ExceptionThrown`	Triggered by the `TestRunner` when an exception is thrown. An `ExceptionEventData` object is passed to listener callback functions.
`DiagnosticLogged`	Triggered by the `TestRunner` upon a call to the `log` method. A `LoggedDiagnosticEventData` object is passed to the listener callback functions.

Examples

collapse all

Create Test Case Class

Create a test case class, FigurePropertiesTest, with TestMethodSetup and TestMethodTeardown methods.

classdef FigurePropertiesTest < matlab.unittest.TestCase
 
    properties
        TestFigure
    end
 
    methods(TestMethodSetup)
        function createFigure(testCase)
            testCase.TestFigure = figure;
        end
    end
 
    methods(TestMethodTeardown)
        function closeFigure(testCase)
            close(testCase.TestFigure)
        end
    end
 
    methods(Test)
 
        function defaultCurrentPoint(testCase)
 
            cp = testCase.TestFigure.CurrentPoint;
            testCase.verifyEqual(cp, [0 0], ...
                'Default current point is incorrect')
        end
 
        function defaultCurrentObject(testCase)
            import matlab.unittest.constraints.IsEmpty
 
            co = testCase.TestFigure.CurrentObject;
            testCase.verifyThat(co, IsEmpty, ...
                'Default current object should be empty')
        end
 
    end
 
end

Tips

Defining constructor or destructor methods in a TestCase subclass is not recommended. TestCase constructor and destructor methods are not considered test content and should not be used to perform qualifications. For example, the SampleTest class specifies qualifications using a constructor method and a Test method. However, the qualification in the constructor method does not produce a test failure. The testing framework reports only one test failure as a result of the qualification performed within the testSize method.
```
classdef SampleTest < matlab.unittest.TestCase
    methods
        function testCase = SampleTest % Constructor method not recommended
            testCase.verifyEqual(1,2)  % Does not produce a test failure
        end
    end

    methods(Test)
       function testSize(testCase)
           testCase.verifySize([1 2 3; 4 5 6],[2 4]) % Produces a test failure
       end
    end
end
```

Version History

Introduced in R2013a

expand all

R2022a: Create temporary folders that are automatically removed

The matlab.unittest.TestCase class has a new method createTemporaryFolder that creates a temporary folder for your tests. The lifecycle of the folder is tied to the test case. Once the test case goes out of scope, the testing framework removes the folder.

R2021a: Initialize parameterization properties at suite creation time

You can initialize a parameterization property at test suite creation time using a static method with the new TestParameterDefinition attribute. This feature is useful when parameters cannot be determined at the time MATLAB^® loads the test class definition. For more information, see Define Parameters at Suite Creation Time.