matlabtest.parameters.matfileBaseline

Define data in MAT file as baseline data

Since R2024b

Syntax

p = matlabtest.parameters.matfileBaseline(filename)

p = matlabtest.parameters.matfileBaseline(filename,VariableName=varname)

Description

p = matlabtest.parameters.matfileBaseline(filename) creates a baseline parameter that defines the data in the specified MAT file as baseline data. The testing framework uses the baseline parameter when creating a test suite and running the tests.

To create baseline tests in your test class, use the matlabtest.parameters.matfileBaseline function to set a property defined in a properties block with the TestParameter, MethodSetupParameter, or ClassSetupParameter attribute. Then, specify the property as an input to the methods that test against the baseline data. For more information about baseline tests, see Create Baseline Tests for MATLAB Code.

p = matlabtest.parameters.matfileBaseline(filename,VariableName=varname) defines the data stored in the specified variable of the MAT file as baseline data.

Examples

Create Simple Baseline Test

Create a baseline test 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 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 verifyEqualsBaseline method to test the actual value against the baseline data.

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

    methods (Test)
        function baselineTest(testCase,baseline)
            actual = magic(5);
            testCase.verifyEqualsBaseline(actual,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:
    ---------------------
    verifyEqualsBaseline 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 9
================================================================================
.
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
__________

Input Arguments

filename — Name of MAT file for baseline data

string scalar | character vector

Name of the MAT file for baseline data, specified as a string scalar or character vector. If filename does not include an extension, the framework appends .mat to it.

filename can be the name of a MAT file on the MATLAB^® search path, a path relative to the current folder, or an absolute path. If filename does not exist, the baseline test fails and the framework prompts you to create the MAT file before rerunning the test. For an example, see Create Simple Baseline Test.

Note

If you specify a path in filename, then the framework searches for the MAT file at the specified location. If you specify only a filename, such as "myFile.mat", then the framework searches for the file along the MATLAB search path.

Example: "myFile.mat"

Example: "C:\work\myFile.mat"

varname — Name of variable to store baseline data

string scalar | character vector

Name of the variable to store the baseline data in filename, specified as a string scalar or character vector. The value must be a valid variable name. In other words, isvarname(varname) must return true.

If you do not specify this input, the framework uses:

• "data" as the variable name if filename does not exist when creating the baseline parameter or if filename exists and contains more than one variable

• The existing variable name if filename exists and contains a single variable

Example: "myVar"

Output Arguments

p — Baseline parameter

matlabtest.parameters.BaselineParameter object

Baseline parameter used to create and run baseline tests, returned as a matlabtest.parameters.BaselineParameter object. Use this argument to set a property defined in a properties block with the TestParameter, MethodSetupParameter, or ClassSetupParameter attribute. You do not need to interact with the returned BaselineParameter object directly.

Version History

Introduced in R2024b