matlabtest.constraints.EqualsBaseline Class

Namespace: matlabtest.constraints
Superclasses: matlab.unittest.constraints.Constraint

Test if value is equal to baseline data

Since R2024b

Description

The matlabtest.constraints.EqualsBaseline class provides a constraint to test for equality in baseline tests. The constraint compares values in the same way as the IsEqualTo constraint.

You can use the EqualsBaseline constraint within a test class that specifies baseline parameters. If the qualification fails, the testing framework provides you with options to either create new baseline data or update the existing baseline data using the actual value. For more information about baseline testing, see Create Baseline Tests for MATLAB Code.

Creation

Description

constraint = matlabtest.constraints.EqualsBaseline(baseline) creates a constraint to test if the actual value is equal to the baseline data. The constraint is satisfied if the actual value is strictly equal to the baseline data represented by baseline.

constraint = matlabtest.constraints.EqualsBaseline(baseline,Within=tol) uses the specified tolerance when testing for equality. For example, constraint = matlabtest.constraints.EqualsBaseline(baseline,Within=matlab.unittest.constraints.RelativeTolerance(0.01)) creates a constraint to test if the difference between the corresponding elements of the actual and baseline numeric arrays is within 1%. For more information about comparison using a tolerance, see Comparison Details.

Input Arguments

baseline — Representation of baseline data

matlabtest.baselines.MATFileBaseline object

Representation of the baseline data, specified as a matlabtest.baselines.MATFileBaseline object.

This argument sets the Baseline property.

tol — Tolerance to use when testing for equality

matlab.unittest.constraints.Tolerance object

Tolerance to use when testing for equality, specified as a matlab.unittest.constraints.Tolerance object.

This argument sets the Tolerance property.

Example: matlab.unittest.constraints.AbsoluteTolerance(1)

Example: matlab.unittest.constraints.AbsoluteTolerance(1) | matlab.unittest.constraints.RelativeTolerance(0.1)

Properties

Baseline — Representation of baseline data

matlabtest.baselines.MATFileBaseline object

Representation of the baseline data, returned as a matlabtest.baselines.MATFileBaseline object.

This property is set by the baseline input argument.

Attributes:

GetAccess	public
SetAccess	immutable

Tolerance — Tolerance to use when testing for equality

matlab.unittest.constraints.Tolerance object

Tolerance to use when testing for equality, specified as a matlab.unittest.constraints.Tolerance object.

This property is set by the tol input argument.

Attributes:

GetAccess	public
SetAccess	public

Examples

Create Baseline Test Using Constraint

Create a baseline test using the EqualsBaseline constraint to test a function whose output is not straightforward to verify through automated testing. Run the test to create baseline data in a MAT file from the "known good" function output. Run the test a second time to test the function output against the created baseline data.

First, manually verify that your function behaves as expected. For example, you can inspect the function output in the Command Window. For illustrative purposes, this example uses the magic function. In practice, you work with user-defined code.

M = magic(5)

M =

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

To create a baseline test for your function, you must define a baseline and then associate it with a test using a test class. Create the ExampleTest test class in a file named ExampleTest.m in your current folder. Then, complete the test class code by following these steps:

1. In a properties block with the TestParameter attribute, add the baseline property to define a baseline.

2. Set the baseline property using the matlabtest.parameters.matfileBaseline function. The function creates a scalar baseline parameter that defines the data in the testdata.mat file as baseline data.

3. In a methods block with the Test attribute, add the parameterized baselineTest method that accepts baseline as an input.

4. Implement the baselineTest method by specifying the actual value and then using the EqualsBaseline constraint to test the actual value against the defined baseline data.

classdef ExampleTest < matlab.unittest.TestCase
    properties (TestParameter)        
        baseline = matlabtest.parameters.matfileBaseline("testdata.mat")
    end

    methods (Test)
        function baselineTest(testCase,baseline)
            import matlabtest.constraints.EqualsBaseline
            actual = magic(5);
            testCase.verifyThat(actual,EqualsBaseline(baseline))
        end
    end
end

Run the test. The test fails because the testdata.mat file does not yet exist and there is no baseline data to compare the actual value against. However, the test diagnostic includes a hyperlink that enables you to create baseline data from the actual value that the testing framework records.

result = runtests("ExampleTest");

Running ExampleTest

================================================================================
Verification failed in ExampleTest/baselineTest(baseline=testdata.mat(data)).
    ---------------------
    Framework Diagnostic:
    ---------------------
    EqualsBaseline failed.
    --> An error occurred when loading baseline data: 
    --> MATLAB:MatFile:NoFile
    --> Cannot access 'data' because 'C:\work\testdata.mat' does not exist.
    --> Create baseline from recorded test data
    ------------------
    Stack Information:
    ------------------
    In C:\work\ExampleTest.m (ExampleTest.baselineTest) at 10
================================================================================
.
Done ExampleTest
__________

Failure Summary:

     Name                                                   Failed  Incomplete  Reason(s)
    ====================================================================================================
     ExampleTest/baselineTest(baseline=testdata.mat(data))    X                 Failed by verification.

Because you already inspected the actual value before creating the baseline test, approve it as baseline data by clicking Create baseline from recorded test data. The framework creates the testdata.mat file including the actual value as baseline data and displays a dialog box to confirm the successful operation. Now that baseline data exists for your test, you can verify that your function continues to produce the same output by running the baseline test. If the function output changes, for instance, due to code refactoring, the baseline test signals the change through a qualification failure. The test passes only if the function output remains the same as the baseline data in the MAT file.

Run the test again to test the function output against the baseline data. In this case, the test passes because the function has not changed since baseline data creation.

result = runtests("ExampleTest");

Running ExampleTest
.
Done ExampleTest
__________

Version History

Introduced in R2024b