Test Models Using MATLAB-Based Simulink Tests

A MATLAB^®-based Simulink^® test is defined in a MATLAB code (.m) file that you create in MATLAB, and then open, run, and view results in the Test Manager. The test file is a class definition file that inherits from sltest.TestCase. The inheritance enables you to open the test file in the Test Manager. When you open a MATLAB test file in the Test Manager, it appears and behaves the same as a test created in the Test Manager, although with some limited functionality (see Limitations of MATLAB- Based Tests). In addition to using a MATLAB test in the Test Manager, you can use the MATLAB test at the command line like any other unit test file.

Because these test files are text (.m) files, you can edit, compare to and merge with other .m test files, and link from the file to requirements. In contrast, test files created in the Test Manager or by using the Simulink Test™ API are saved as binary MLDATX files.

Classes and Methods

TestCase Class and Methods

The sltest.TestCase class and its methods work specifically with MATLAB tests. You can use these methods in test files and at the command line, except for sltest.TestCase.forInteractiveUse, which can only be used at the command line. In addition to these methods, you can use the matlab.unittest.TestCase methods with MATLAB tests.

`sltest.TestCase`	Class from which to inherit
`loadSystem`	Loads model
`simulate`	Simulate model
`assumeSignalsMatch`	Assume two sets of data are equivalent
`assertSignalsMatch`	Assert two sets of data are equivalent
`fatalAssertSignalsMatch`	Fatal assert two sets of data are equivalent
`verifySignalsMatch`	Verify two sets of data are equivalent
`sltest.TestCase.forInteractiveUse`	Create test case for use at command line
`createTemporaryFolder`	Create temporary folder that is deleted when test case goes out of scope
`createSimulationInput`	Creates `Simulink.SimulationInput` or `sltest.harness.SimulationInput` object.

Test Harness Class

sltest.harness.SimulationInput creates an object that you can use to specify changes applied to a test harness during simulation. In addition to using this class for MATLAB-based Simulink tests, you can use it in other MATLAB code.

Test Runner Methods

These methods of matlab.unittest.TestRunner apply specifically to MATLAB-based Simulink tests.

addModelCoverage — enables model coverage collection using the test runner. Instead of using this method, if you open your MATLAB-based Simulink test file in the Test Manager, you can enable coverage collection there.
addSimulinkTestResults — pushes test results to the Simulink Test Manager.

Plugin Classes

These sltest.plugins classes enable functionality for MATLAB-based tests. In addition to these methods, you can use other sltest.plugins classes with these tests. The plugins can be attached to a matlab.unittest.TestRunner to enable functionality while running an sltest.TestCase test.

`sltest.plugins.MATLABTestCaseIntegrationPlugin`	Enable integrating MATLAB test simulation and test results with the Test Manager
`sltest.plugins.ToTestManagerLog`	Enable writing text output to Test Manager results Logged Signals pane of the Test Manager
`sltest.plugins.ModelCoveragePlugin`	Enable collecting model coverage

Creating a Baseline MATLAB-Based Simulink Test

To create a baseline MATLAB test:

Create a MATLAB code (.m) file that defines the test cases. You can launch the MATLAB Editor from the command line, or from the Test Manager by using New > Test Case > MATLAB-Based Simulink Test.
See Class-Based Unit Tests. The only difference for MATLAB tests is that the class must inherit from sltest.TestCase, instead of from matlab.unittest.TestCase.
This sample MATLAB test file includes one test, which is defined in the testOne function. When you run the test in the Test Manager, the test loads the model named sltestMATLABBasedTestExample. It then sets the value of the gain2_var variable, and simulates the model. Finally, the test compares model simulation output to the baseline data MAT file.
```
classdef myTest < sltest.TestCase
   methods (Test)
      function testOne(testCase)
         testCase.loadSystem...
           ('sltestMATLABBasedTestExample');
         evalin('base','gain2_var = 2.01;');
         simOut = testCase.simulate...
           ('sltestMATLABBasedTestExample');
         testCase.verifySignalsMatch(simOut,'baselineOne.mat',...
           'AbsTol',0.015);
      end
   end
end
```

If you are using a test harness, replace the simOut line in the above MATLAB test file with

simOut = testCase.simulate('sltestMATLABBasedTestExample',...
  'WithHarness','sltestMATLABBasedTestExample_harness1');

or, to specify the stop the simulation time, replace simOut with

in = testCase.createSimulationInput('sltestMATLABBasedTestExample',...
  'WithHarness','sltestMATLABBasedTestExample_harness1');
in = in.setModelParameter("StopTime","10")
simOut = testCase.simulate(in);

If a baseline data MAT-file does not already exist or if you need to update it, at the MATLAB command line, use:
```
runtests(<test>,'GenerateBaselines',true)
```
For the sample file, <test> is ''myTest/testOne'.
When you generate baselines, the test begins running. It pauses to open a Simulation Data Inspector report, and you are prompted at the MATLAB command line to review the baseline data. When you approve the data, it saves the baseline data to a new MAT file or updates the existing MAT-file. Then, the test continues to run, but fails because the new or updated baseline data is not included in the current run. Rerun the test using the runtests command to use the new or updated baseline and produce a passing result. You can also rerun the test by using the yellow rerun hyperlink at the command line.
Optionally, if you have a Simulink Coverage™ license, you can include coverage collection in your test by using the sltest.plugins.ModelCoveragePlugin. See Collect Coverage Using MATLAB-Based Simulink Tests for an example and information on coverage collection.
Alternatively, you can collect coverage by using the Test Manager. After you open the test file in the Test Manager, select the test file, select a Coverage Settings option, and select the coverage metrics. The test suites and test cases in the file inherit the coverage settings from the test file. If you set the coverage collection and metrics in the Test Manager, you do not need to import or add the coverage plugins to the runner.
If you set the coverage metrics in the Test Manager and then close the Test Manager, the coverage settings are not saved to the MATLAB-based Simulink test code (.m) file.
Optionally, if you have a Requirements Toolbox™ license, you can add requirements. Open the Test Manager and update the test file.
1. Click Open > Open MATLAB-Based Simulink Test (.m) and select the test file. The test file loads and its test hierarchy displays in the Test Browser pane. If you select the test file, the Requirements and Test File Content panes appear in the Test Manager.
2. Add requirements by expanding the Requirements section by clicking Add to open the Outgoing Links Editor. See Link to Requirements for information on adding requirements.
To update the MATLAB code (.m) test file from the Test Manager, click the Open test in the MATLAB Editor link.
After you edit the code file and save your changes, or after adding coverage or requirements, return to the Test Manager and click the synchronization button next to the test file in the Test Browser pane.
Run the test, view the results, and create a test results report.
1. Click Run to run the test.
2. To view the results, expand the rows in the Results and Artifacts pane.
3. To view coverage results, in the Results and Artifacts pane, select the Results item and expand the Aggregated Coverage section. See Collect Coverage in Tests for information.
4. Optionally, create a test results report. See Create, Set Options, and Use Templates for Test Result Reports.

Alternatively, instead of adding coverage (Step 4) and running the test (Step 8) in the Test Manager, you can use these commands at the MATLAB command line to add coverage, run the test, and push the results to the Test Manager. To collect coverage, you must add the MATLABTestCaseIntegrationPlugin and the ModelCoveragePlugin to the testrunner. The addModelCoverage function adds the ModelCoveragePlugin.

suite = testsuite('myTests');
runner = testrunner('textoutput');
runner.addModelCoverage(...
   "CollectMetrics",["MCDC","Condition"]);
runner.addPlugin(sltest.plugins.MATLABTestCaseIntegrationPlugin);
runner.run(suite);

Linking to Requirements from a MATLAB-Based Simulink Test File

Note

You must have Requirements Toolbox to include requirements links.

To add links to requirements from a file being edited in the MATLAB Editor, see Link MATLAB Code to Requirements (Requirements Toolbox). For MATLAB test files, you add links using the same process. However, the text you select in the MATLAB code (.m) file determines the type of link and the test to which it is added. If you select:

Class definition line (e.g., classdef myClass < sltest.TestCase) — Adds a Verified By link for the whole test file
Text inside a test function — Adds a Verified By link for that function
Text across multiple test functions — Adds a Verified By link for the first function in the selection
Any other text selected — Adds a Related To link for the selection

After you add requirements links, you can view the verification status in the Requirements Editor by clicking Display > Verification Status. To update the status of a Verified By requirement, right-click on the requirement and select Run Tests. See Review Requirements Verification Status (Requirements Toolbox).

Links that you create in the MATLAB code (.m) file appear in the Requirements section of the Test Manager. Linking to requirements from in the Test Manager works the same as described in Link to Requirements.

When you have the Requirements Editor open and you click on an incoming link that is for a MATLAB test, if you have a Simulink Test license, the Test Manager opens and goes to the associated test. If a license is not available, the MATLAB Editor opens and goes to the line of code associated with that requirement.

For a parameterized test, Requirements Toolbox does not support linking to individual parameterized versions of the test. In your .m file, if you create a link from parameterized test to a requirement, the link is associated with all versions of that test. In the Test Manager, if you create a link from a version of a parameterized test to a requirement, the link is associated with all versions of that test.

Limitations of MATLAB- Based Tests

MATLAB-based Simulink tests do not support:

Test types other than baseline tests.
Running tests in parallel.
Running tests in multiple releases.
Test tags and descriptions.
Callbacks. (However, while callbacks are not supported in the Test Manager for MATLAB-based tests, you can use TestClassSetup and TestMethodSetup, or fixtures in your .m file to achieve similar functionality. See Write Setup and Teardown Code Using Classes.)
Logical and temporal assessments.
Enabling coverage collection or changing coverage metrics at the test suite or test file level in the Test Manager.
Saving coverage settings to the MATLAB-based Simulink test MATLAB code (.m) file from the Test Manager.