matlab.unittest.TestCase Class

Namespace: matlab.unittest
Superclasses: matlab.unittest.qualifications.Assertable, matlab.unittest.qualifications.Assumable, matlab.unittest.qualifications.FatalAssertable, matlab.unittest.qualifications.Verifiable

Superclass of all test classes

Description

The matlab.unittest.TestCase class is the superclass of all test classes in MATLAB^®. It provides an interface to write and identify test content, including test fixture setup and teardown routines.

Creating class-based tests requires subclassing the TestCase class. To specify tests and test fixtures, subclasses can leverage framework-specific attributes. For more information, see TestCase Class Attributes, TestCase Method Attributes, and TestCase Property Attributes.

The matlab.unittest.TestCase class is a handle class.

Class Attributes

Abstract

true

For information on class attributes, see Class Attributes.

Creation

In most cases, you are not required to create an instance of the TestCase class directly. The test runner automatically creates TestCase instances when running the tests.

To create a TestCase instance for interactive, command-line testing, use the forInteractiveUse static method.

Methods

Public Methods

In addition to these methods, the matlab.unittest.TestCase class inherits methods from the Assertable, Assumable, FatalAssertable, and Verifiable classes.

addTeardown	Dynamically add teardown code to test case
applyFixture	Use fixture with test case
createTemporaryFolder	Create temporary folder
matlab.unittest.TestCase.forInteractiveUse	Create test case 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 tests corresponding to test case

Events

In addition to these events, the matlab.unittest.TestCase class inherits events from the Assertable, Assumable, FatalAssertable, and Verifiable classes.

Event Name	Trigger	Event Data	Event Attributes
ExceptionThrown	Triggered when the test runner catches an exception in the test content. An ExceptionEventData object is passed to listener callback functions.	matlab.unittest.qualifications.ExceptionEventData	NotifyAccess: private ListenAccess: public
DiagnosticLogged	Triggered upon a call to the log method. A LoggedDiagnosticEventData object is passed to listener callback functions.	matlab.unittest.diagnostics.LoggedDiagnosticEventData	NotifyAccess: private ListenAccess: public

Examples

Write Class-Based Tests

Test the properties of a figure by creating and running a test class.

In a file named FigurePropertiesTest.m in your current folder, create the FigurePropertiesTest test class by:

• Subclassing the matlab.unittest.TestCase class

• Adding a property to represent the figure to test

• Adding setup and teardown code for each test in a TestMethodSetup methods block

• Adding tests in a Test methods block

classdef FigurePropertiesTest < matlab.unittest.TestCase
    properties
        TestFigure
    end

    methods (TestMethodSetup)
        function createFigure(testCase)
            testCase.TestFigure = figure;
            testCase.addTeardown(@close,testCase.TestFigure)
        end
    end

    methods (Test)
        function defaultCurrentPoint(testCase)
            cp = testCase.TestFigure.CurrentPoint;
            testCase.verifyEqual(cp,[0 0], ...
                "Default current point must be [0 0].")
        end

        function defaultCurrentObject(testCase)
            import matlab.unittest.constraints.IsEmpty
            co = testCase.TestFigure.CurrentObject;
            testCase.verifyThat(co,IsEmpty, ...
                "Default current object must be empty.")
        end
    end
end

Run the tests in the test class. In this example, both of the tests pass.

results = runtests("FigurePropertiesTest")

Running FigurePropertiesTest

.

.
Done FigurePropertiesTest
__________

results = 
  1×2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 0 Failed, 0 Incomplete.
   1.1899 seconds testing time.

More About

TestCase Class Attributes

These class attributes are specific to TestCase subclasses.

SharedTestFixtures	classdef block to contain shared test fixtures. Specify the value of this attribute as a cell array of matlab.unittest.fixtures.Fixture instances.
TestTags	classdef block to contain tests tagged with a specified value. Specify the value of this attribute as a string array or cell array. Each element of the array must be a textual value containing more than zero characters, which represents a test tag.

Standard attributes also apply to TestCase subclasses. For details, see Class Attributes.

TestCase Method Attributes

These method attributes are specific to TestCase subclasses.

Test	methods block to contain the tests.
TestMethodSetup	methods block to contain setup code for each test.
TestMethodTeardown	methods block to contain teardown code for each test.
TestClassSetup	methods block to contain class-level setup code.
TestClassTeardown	methods block to contain class-level teardown code.
ParameterCombination	methods block to contain parameterized testing code. Specify this attribute as one of these values: "exhaustive" (default) — The testing framework invokes Test methods for all combinations of parameters. "sequential" — The testing framework invokes Test methods with corresponding parameter values. Each parameterization property must specify the same number of parameter values. "pairwise" — The testing framework invokes Test methods for every pair of parameter values at least once. "n-wise" — The testing framework invokes Test methods for every n-tuple of parameter values at least once (requires MATLAB Test™). You can specify n as an integer between 2 and 10.
TestParameterDefinition	methods block to contain code that initializes parameterization properties at suite creation time. The methods defined using this attribute must be static.
TestTags	methods block to contain tests tagged with a specified value. Specify the value of this attribute as a string array or cell array. Each element of the array must be a textual value containing more than zero characters, which represents a test tag.

Standard attributes also apply to methods of TestCase subclasses. For details, see Method Attributes.

TestCase Property Attributes

These property attributes are specific to TestCase subclasses.

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

Standard attributes also apply to properties of TestCase subclasses. For details, see Property Attributes.

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

R2023a: Combine parameters using "n-wise" attribute value

You can specify the value of the ParameterCombination method attribute as "n-wise", where n is an integer between 2 and 10. For more information, see Use Parameters in Class-Based Tests.

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.