matlab.unittest.fixtures.Fixture - Fundamental interface for test fixtures - MATLAB (original) (raw)
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 thesetup 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 sameFixture subclass correspond to the same shared test fixture state.
The matlab.unittest.fixtures.Fixture class is a handle class.
Properties
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 |
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
| 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 |
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
| assumeEqualassertEqualfatalAssertEqual | __Equal(fixture,actual,expected,diagnostic,Name,Value)Test if actual is strictly equal toexpected. Replace with assume, assert, orfatalAssert.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. |
|---|---|
| assumeFailassertFailfatalAssertFail | Fail(fixture,diagnostic)Produce an unconditional qualification failure. Replace with assume,assert, orfatalAssert.Input Arguments fixture — Fixture.diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. |
| assumeFalseassertFalsefatalAssertFalse | __False(fixture,actual,diagnostic)Test if the value of actual is logical 0 (false). Replace with assume, assert, orfatalAssert.Input Arguments fixture — Fixture.actual — Value to test.diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. |
| assumeNotEqualassertNotEqualfatalAssertNotEqual | __NotEqual(fixture,actual,prohibited,diagnostic)Test if actual is not equal to prohibited. Replace with assume,assert, orfatalAssert.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. |
| assumeNotSameHandleassertNotSameHandlefatalAssertNotSameHandle | __NotSameHandle(fixture,actual,prohibited,diagnostic)Test if actual is not the same as the prohibited handle array. Replace with assume,assert, orfatalAssert.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. |
| assumeReturnsTrueassertReturnsTruefatalAssertReturnsTrue | ReturnsTrue(fixture,actual,diagnostic)Test if actual is a function handle that returns the logical scalar 1 (true). Replace with assume,assert, orfatalAssert.Input Arguments fixture — Fixture.actual — Value to test.diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. |
| assumeSameHandleassertSameHandlefatalAssertSameHandle | SameHandle(fixture,actual,expected,diagnostic)Test if actual is the same as the expected handle array. Replace with assume,assert, orfatalAssert.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. |
| assumeThatassertThatfatalAssertThat | __That(fixture,actual,constraint,diagnostic)Test if actual is a value that satisfies the specified constraint. Replace withassume, assert, orfatalAssert.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. |
| assumeTrueassertTruefatalAssertTrue | __True(fixture,actual,diagnostic)Test if the value of actual is logical 1 (true). Replace with assume, assert, orfatalAssert.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
| assumeErrorassertErrorfatalAssertError | [output1,...,outputN] = Error(fixture,actual,identifier,diagnostic)Test if actual is a function handle that throws the exception specified by identifier. Replace with assume,assert, orfatalAssert.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. |
|---|---|
| assumeWarningassertWarningfatalAssertWarning | [output1,...,outputN] = Warning(fixture,actual,identifier,diagnostic)Test if actual is a function handle that issues the warning specified by identifier. Replace with assume,assert, orfatalAssert.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. |
| assumeWarningFreeassertWarningFreefatalAssertWarningFree | [output1,...,outputN] = __WarningFree(fixture,actual,diagnostic)Test if actual is a function handle that issues no warnings. Replace with assume,assert, orfatalAssert.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
| assumeGreaterThanassertGreaterThanfatalAssertGreaterThan | __GreaterThan(fixture,actual,floor,diagnostic)Test if all elements of actual are greater than all elements offloor. Replace with assume, assert, orfatalAssert.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. |
|---|---|
| assumeGreaterThanOrEqualassertGreaterThanOrEqualfatalAssertGreaterThanOrEqual | GreaterThanOrEqual(fixture,actual,floor,diagnostic)Test if all elements of actual are greater than or equal to all elements of floor. Replace with assume,assert, orfatalAssert.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. |
| assumeLessThanassertLessThanfatalAssertLessThan | __LessThan(fixture,actual,ceiling,diagnostic)Test if all elements of actual are less than all elements ofceiling. Replace with assume, assert, orfatalAssert.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. |
| assumeLessThanOrEqualassertLessThanOrEqualfatalAssertLessThanOrEqual | LessThanOrEqual(fixture,actual,ceiling,diagnostic)Test if all elements of actual are less than or equal to all elements of ceiling. Replace with assume,assert, orfatalAssert.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
| assumeEmptyassertEmptyfatalAssertEmpty | __Empty(fixture,actual,diagnostic)Test if actual is an empty MATLAB® array. Replace withassume, assert, orfatalAssert.Input Arguments fixture — Fixture.actual — Value to test.diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. |
|---|---|
| assumeLengthassertLengthfatalAssertLength | Length(fixture,actual,expectedLength,diagnostic)Test if actual is a MATLAB array with the expected length. Replace with assume,assert, orfatalAssert.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. |
| assumeNotEmptyassertNotEmptyfatalAssertNotEmpty | __NotEmpty(fixture,actual,diagnostic)Test if actual is a nonempty MATLAB array. Replace withassume, assert, orfatalAssert.Input Arguments fixture — Fixture.actual — Value to test.diagnostic — (Optional) Diagnostic information to display when the qualification passes or fails. For details, see Diagnostics. |
| assumeNumElementsassertNumElementsfatalAssertNumElements | NumElements(fixture,actual,expectedNumElements,diagnostic)Test if actual is a MATLAB array with the expected number of elements. Replace with assume,assert, orfatalAssert.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. |
| assumeSizeassertSizefatalAssertSize | Size(fixture,actual,expectedSize,diagnostic)Test if actual is a MATLAB array with the expected size. Replace with assume,assert, orfatalAssert.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
| assumeClassassertClassfatalAssertClass | Class(fixture,actual,class,diagnostic)Test if the class of actual is the specified class. Replace with assume,assert, orfatalAssert.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. |
|---|---|
| assumeInstanceOfassertInstanceOffatalAssertInstanceOf | InstanceOf(fixture,actual,class,diagnostic)Test if actual is an instance of the specified class. Replace with assume,assert, orfatalAssert.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
| assumeMatchesassertMatchesfatalAssertMatches | Matches(fixture,actual,expression,diagnostic)Test if actual is a string scalar or character vector that matches the specified regular expression. Replace with assume,assert, orfatalAssert.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. |
|---|---|
| assumeSubstringassertSubstringfatalAssertSubstring | Substring(fixture,actual,substring,diagnostic)Test if actual is a string scalar or character vector that contains substring. Replace with assume,assert, orfatalAssert.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
Examples
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 thematlab.unittest.fixtures.Fixture interface. Implement thesetup 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 thesetup 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 theExampleTest 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.
Running ExampleTest . Done ExampleTest
More About
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 optionaldiagnostic 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
The matlab.unittest.fixtures.Fixture class has a new methodapplyAndRun that lets you run a function in the environment provided by one or more fixtures.
The matlab.unittest.fixtures.Fixture class has a new methodneedsReset 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.