matlab.unittest.fixtures.Fixture Class

Namespace: matlab.unittest.fixtures

Fundamental interface for test fixtures

Description

The matlab.unittest.fixtures.Fixture class provides an interface for test fixtures. Fixtures specify setup and teardown code that sets up the test environment and restores it to its original state after running the test.

A Fixture subclass must implement the setup method, which makes changes to the environment when the testing framework sets up the fixture. To restore the environment when the framework tears down the fixture, call the addTeardown method within the setup method, or implement the teardown method.

In addition to specifying setup and teardown actions in your Fixture subclass, you must implement the isCompatible method if the fixture is configurable (for example, if its class constructor accepts input arguments). The testing framework calls isCompatible to determine whether instances of the same Fixture subclass correspond to the same shared test fixture state.

The matlab.unittest.fixtures.Fixture class is a handle class.

Class Attributes

Abstract

true

For information on class attributes, see Class Attributes.

Properties

SetupDescription — Description of setup actions

character vector

Description of the setup actions, returned as a character vector. Set this property in your Fixture implementation to describe the actions the fixture performs when the testing framework invokes the setup method. If you use the fixture as a shared test fixture, the framework displays the property value when setting up the fixture.

Attributes:

GetAccess	public
SetAccess	protected

TeardownDescription — Description of teardown actions

character vector

Description of the teardown actions, returned as a character vector. Set this property in your Fixture implementation to describe the actions the fixture performs when the testing framework invokes the teardown method or the function handle passed to the addTeardown method. If you use the fixture as a shared test fixture, the framework displays the property value when tearing down the fixture.

Attributes:

GetAccess	public
SetAccess	protected

Methods

Public Methods

addTeardown	Dynamically add teardown code to fixture
applyAndRun	Run function in environment provided by fixture
setup	Set up fixture
teardown	Tear down fixture

Protected Methods

applyFixture	Set up fixture to delegate work to another fixture
isCompatible	Determine if two fixtures are compatible
log	Record diagnostic information during fixture setup and teardown
needsReset	Determine if shared test fixture needs to be reset
onFailure	Dynamically add diagnostics for failures during fixture setup and teardown

Qualification-Based Protected Methods

Similar to the Assumable, Assertable, and FatalAssertable classes, the Fixture class provides several qualification methods for testing values and responding to failures. For example, you can use these protected methods to implement the setup and teardown methods in Fixture subclasses.

The Fixture class supports assumptions, assertions, and fatal assertions. These qualification types have parallel methods for the same types of tests. The methods use a common naming convention. For instance, the methods that test for equality use the form <qualify>Equal, where <qualify> can be assume, assert, or fatalAssert. That is:

• assumeEqual — Assume that two values are equal.

• assertEqual — Assert that two values are equal.

• fatalAssertEqual — Fatally assert that two values are equal.

General Purpose

assumeEqual assertEqual fatalAssertEqual	<qualify>Equal(fixture,actual,expected,diagnostic,Name,Value) Test if actual is strictly equal to expected. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. expected — Expected value. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Name-Value Arguments AbsTol — Absolute tolerance, specified as a numeric array. RelTol — Relative tolerance, specified as a numeric array.
assumeFail assertFail fatalAssertFail	<qualify>Fail(fixture,diagnostic) Produce an unconditional qualification failure. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeFalse assertFalse fatalAssertFalse	<qualify>False(fixture,actual,diagnostic) Test if the value of actual is logical 0 (false). Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeNotEqual assertNotEqual fatalAssertNotEqual	<qualify>NotEqual(fixture,actual,prohibited,diagnostic) Test if actual is not equal to prohibited. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. prohibited — Value to compare against. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeNotSameHandle assertNotSameHandle fatalAssertNotSameHandle	<qualify>NotSameHandle(fixture,actual,prohibited,diagnostic) Test if actual is not the same as the prohibited handle array. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. prohibited — Value to compare against, specified as a handle array. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeReturnsTrue assertReturnsTrue fatalAssertReturnsTrue	<qualify>ReturnsTrue(fixture,actual,diagnostic) Test if actual is a function handle that returns the logical scalar 1 (true). Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeSameHandle assertSameHandle fatalAssertSameHandle	<qualify>SameHandle(fixture,actual,expected,diagnostic) Test if actual is the same as the expected handle array. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. expected — Expected value, specified as a handle array. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeThat assertThat fatalAssertThat	<qualify>That(fixture,actual,constraint,diagnostic) Test if actual is a value that satisfies the specified constraint. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. constraint — Constraint that the actual value must satisfy, specified as an instance of the matlab.unittest.constraints.Constraint class. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeTrue assertTrue fatalAssertTrue	<qualify>True(fixture,actual,diagnostic) Test if the value of actual is logical 1 (true). Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Errors and Warnings

assumeError assertError fatalAssertError	[output1,...,outputN] = <qualify>Error(fixture,actual,identifier,diagnostic) Test if actual is a function handle that throws the exception specified by identifier. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. identifier — Error identifier, specified as a string scalar, character vector, or matlab.metadata.Class instance. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Output Arguments (Optional) output1,...,outputN — Output arguments, 1 through N (if any), requested from actual.
assumeWarning assertWarning fatalAssertWarning	[output1,...,outputN] = <qualify>Warning(fixture,actual,identifier,diagnostic) Test if actual is a function handle that issues the warning specified by identifier. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. identifier — Warning identifier, specified as a character vector, cell array of character vectors, or string array. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Output Arguments (Optional) output1,...,outputN — Output arguments, 1 through N (if any), produced by actual.
assumeWarningFree assertWarningFree fatalAssertWarningFree	[output1,...,outputN] = <qualify>WarningFree(fixture,actual,diagnostic) Test if actual is a function handle that issues no warnings. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. Output Arguments (Optional) output1,...,outputN — Output arguments, 1 through N (if any), produced by actual.

Inequalities

assumeGreaterThan assertGreaterThan fatalAssertGreaterThan	<qualify>GreaterThan(fixture,actual,floor,diagnostic) Test if all elements of actual are greater than all elements of floor. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. floor — Minimum value. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeGreaterThanOrEqual assertGreaterThanOrEqual fatalAssertGreaterThanOrEqual	<qualify>GreaterThanOrEqual(fixture,actual,floor,diagnostic) Test if all elements of actual are greater than or equal to all elements of floor. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. floor — Minimum value. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeLessThan assertLessThan fatalAssertLessThan	<qualify>LessThan(fixture,actual,ceiling,diagnostic) Test if all elements of actual are less than all elements of ceiling. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. ceiling — Maximum value. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeLessThanOrEqual assertLessThanOrEqual fatalAssertLessThanOrEqual	<qualify>LessThanOrEqual(fixture,actual,ceiling,diagnostic) Test if all elements of actual are less than or equal to all elements of ceiling. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. ceiling — Maximum value. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Array Size

assumeEmpty assertEmpty fatalAssertEmpty	<qualify>Empty(fixture,actual,diagnostic) Test if actual is an empty MATLAB® array. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeLength assertLength fatalAssertLength	<qualify>Length(fixture,actual,expectedLength,diagnostic) Test if actual is a MATLAB array with the expected length. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. expectedLength — Expected array length. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeNotEmpty assertNotEmpty fatalAssertNotEmpty	<qualify>NotEmpty(fixture,actual,diagnostic) Test if actual is a nonempty MATLAB array. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeNumElements assertNumElements fatalAssertNumElements	<qualify>NumElements(fixture,actual,expectedNumElements,diagnostic) Test if actual is a MATLAB array with the expected number of elements. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. expectedNumElements — Expected number of elements. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.
assumeSize assertSize fatalAssertSize	<qualify>Size(fixture,actual,expectedSize,diagnostic) Test if actual is a MATLAB array with the expected size. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. expectedSize — Expected array size. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Type

assumeClass assertClass fatalAssertClass

<qualify>Class(fixture,actual,class,diagnostic) Test if the class of actual is the specified class. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. class — Expected class, specified as a string scalar, character vector, or matlab.metadata.Class instance. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

assumeInstanceOf assertInstanceOf fatalAssertInstanceOf

<qualify>InstanceOf(fixture,actual,class,diagnostic) Test if actual is an instance of the specified class. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. class — Expected class, specified as a string scalar, character vector, or matlab.metadata.Class instance. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

Strings

assumeMatches assertMatches fatalAssertMatches

<qualify>Matches(fixture,actual,expression,diagnostic) Test if actual is a string scalar or character vector that matches the specified regular expression. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. expression — Regular expression to match. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

assumeSubstring assertSubstring fatalAssertSubstring

<qualify>Substring(fixture,actual,substring,diagnostic) Test if actual is a string scalar or character vector that contains substring. Replace <qualify> with assume, assert, or fatalAssert. Input Arguments fixture — Fixture. actual — Value to test. substring — Text contained within actual value. diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics.

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	NotifyAccess: private ListenAccess: public
AssumptionPassed	Triggered upon passing assumption. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public
AssertionFailed	Triggered upon failing assertion. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public
AssertionPassed	Triggered upon passing assertion. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public
FatalAssertionFailed	Triggered upon failing fatal assertion. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public
FatalAssertionPassed	Triggered upon passing fatal assertion. A QualificationEventData object is passed to listener callback functions.	matlab.unittest.qualifications.QualificationEventData	NotifyAccess: private ListenAccess: public
ExceptionThrown	Triggered by the test runner when it 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

Create and Use Test Fixture

Create and use a custom fixture that changes the output display format for numeric values to the currency format with two digits after the decimal point.

In a file named CurrencyFormatFixture.m in your current folder, create the CurrencyFormatFixture class by subclassing the matlab.unittest.fixtures.Fixture interface. Implement the setup method in the class so that the fixture changes the display format for numeric values to the currency format. To restore the display format to its original state after testing, call the addTeardown method within the setup method.

classdef CurrencyFormatFixture < matlab.unittest.fixtures.Fixture
    methods
        function setup(fixture)
            originalFormat = format;
            fixture.addTeardown(@format,originalFormat)
            format bank
        end
    end
end

In a file named ExampleTest.m in your current folder, create the ExampleTest class that applies the custom fixture and verifies that a numeric value is displayed in the expected format. To simplify this example, the actual value is produced by a call to the formattedDisplayText function. In practice, you test user-defined code.

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function formatTest(testCase)
            testCase.applyFixture(CurrencyFormatFixture)
            actual = strtrim(formattedDisplayText(pi));
            expected = "3.14";
            testCase.verifyEqual(actual,expected)
        end
    end
end

Run the ExampleTest class. The testing framework sets up the fixture, which changes the display format to the currency format. Once the test run is complete, the framework tears down the fixture, which restores the original display format. In this example, the test passes.

runtests("ExampleTest");

Running ExampleTest
.
Done ExampleTest
__________

More About

Diagnostics

Depending on the test runner configuration, the testing framework can 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.

Version History

Introduced in R2014a

R2024b: Run function in environment provided by fixtures

The matlab.unittest.fixtures.Fixture class has a new method applyAndRun that lets you run a function in the environment provided by one or more fixtures.

R2020b: Report validity of shared test fixtures

The matlab.unittest.fixtures.Fixture class has a new method needsReset that lets you report the validity of shared test fixtures to the testing framework. A shared test fixture is valid if the test environment state, configured by the fixture, is maintained throughout the test session.