Test Harness and Model Relationship

A test harness is a model block diagram that you can use to test, edit, or debug a Simulink^® model. In the main model, you associate a harness with a model component or the top-level model. The test harness contains a separate model workspace and configuration set. The test harness is associated with the main model and can be accessed through the model canvas.

When you create an external harness, a metadata XML file is also created. The XML file contains the unique ID of the design model, which maintains the association between the model and its harness. The metadata file does not need to be in the same folder as the model, as long as they are both on the MATLAB^® path.

You build the test harness model around the component under test, which links the harness to the main model. If you edit the component under test in the harness, the main model updates when you close the harness. You can generate a test harness for:

A model component, such as a subsystem, library block, Subsystem Reference block, Model block, or System Composer™ component. The test harness isolates the component in a separate simulation environment. If you convert a Subsystem or Subsystem Reference block to a Model block, the test harnesses are transferred to the model reference (see Test Harness Considerations).
A top-level model. The component under test is a Model block referencing the main model. You can also build a test harness in a subsystem model.

Test harnesses for top-level model and model component

Harness-Model Relationship for a Model Component

When you associate a test harness with a model component, the harness model workspace contains copies of the parameters associated with the component. For example, suppose that you create a test harness for a component that contains a Gain block and then add a second Gain block to the harness.

The parameter g defines part of the component under test, so the harness model workspace contains a copy of g.
The parameter a defines part of the main model outside of the component under test, so the harness model workspace does not contain a copy of a.
The parameter h is the gain of the Gain block that you added to the harness. Because this block is outside the component under test, h exists only in the harness model workspace.

Model component and test harness relationship

Harness-Model Relationship for a Top-Level Model

When you associate a harness with the top level of the main model, the harness model workspace does not contain copies of parameters relevant to the component. The component under test is a Model block that references the main model, so the parameters remain in the main model workspace. For example, suppose that you create a test harness for a top-level model that contains a Gain block and then add a second Gain block to the harness.

The component under test references the main model, and the parameter g exists in the main model workspace. The harness model workspace does not contain a copy of g.
The parameter h is the gain of the Gain block that you added to the harness. Because this block is outside the component under test, h exists only in the harness model workspace.

Top level model and test harness relationship

Resolving Parameters

Parameters in the test harness resolve to the most local workspace. Parameters resolve to the harness model workspace, then the system model workspace, then the base MATLAB workspace.

Test Harness Considerations

You can build a test harness for these types of model components:
- Model blocks
- Subsystem Reference blocks
- Subsystem blocks
- Subsystem and Subsystem Reference block components
- Reusable library subsystems that have function interfaces and are at the top-level of the library
- Stateflow^® blocks, including Stateflow charts, Truth Table blocks, State Transition Table blocks, and Test Sequence blocks
- System Composer components
- C Caller blocks
- MATLAB Function blocks
- User-defined function blocks
Test harnesses are not supported for these types of Stateflow objects:
- Atomic subcharts
- Simulink based states
- Simulink functions
- MATLAB functions
The presence of test harnesses, whether saved internally or externally, has no impact on simulation or code generation for a model.
Multiple harnesses owned by a Simulink model can be open at the same time. When multiple harnesses are open, you cannot synchronize changes from the harness to the model using push synchronization.
You cannot delete a test harness unless all test harnesses are closed.
Do not comment out the component under test in the test harness. Commenting out the component under test might cause unexpected behavior.
Model and test harness locking is specific to each type of synchronization. For information on synchronization, see Synchronization Mode.
The signal names used in the component under test propagate from the model to the test harness. For subsystem harnesses, some propagated signal names might be visible only after you compile the harness. For block diagram harnesses, signal names are propagated even if you do not select Show propagated signals in the Signal Properties dialog box.
Subsystem and Subsystem Reference blocks and components within those blocks
- Test harnesses attached to Subsystem models:
  - Always synchronize with the underlying model
  - Are created without compiling
  - Do not support post-build callbacks
  - Do not auto shape inputs
- If a subsystem has a test harness, you cannot expand the subsystem contents into the model that contains the subsystem. Delete the test harness before expanding the subsystem. For more information, see Expand Subsystem Contents.
- When you convert a Subsystem or Subsystem Reference block to a Model block, the test harnesses are transferred to the model reference. Harnesses on the Subsystem block are converted to block diagram harnesses. Nested harnesses within the subsystem are copied to identical blocks in the model reference. All transferred harnesses are internal harnesses in the model reference. Test harnesses might be renamed when they are transferred. You can see feedback about the harness transfer in the Complete Conversion pane of the Conversion Advisor or at the MATLAB Command line.
  These limitations apply to converting a Subsystem or Subsystem Reference block to a Model block:
  - SIL and PIL harnesses are not transferred.
  - Requirements in a test harness for a subsystem are not transferred. You must copy them manually.
If your test harness contains a To Workspace block, the block variable is not saved in the base workspace after the test finishes running. Upon test completion, the base workspace is restored to its original state.
The Upgrade Advisor and XML differencing are not supported for test harness models.
A test harness with a Signal Editor block source does not support:
- Frame-based signals
- Variable-dimension signals
For a test harness with a Test Sequence block or Stateflow chart as the source, all inputs to the component under test must operate with the same sample time.
These considerations apply to collecting coverage in a test harness:
- Loading coverage results to a model, or aggregating coverage results across models, requires a model consistent with the coverage results. Therefore, to perform aggregated coverage collection, use test harnesses configured to automatically synchronize the component under test. Set Synchronization Mode to Synchronize on harness open and close. For more information, see Synchronize Changes Between Test Harness and Model.
- If the test harness is configured to synchronize the component under test when you open or close the harness, coverage results from the test harness are associated with the main model. When you close the test harness, the coverage results remain active in memory. You can aggregate coverage with additional results collected from the main model or another synchronized test harness.
- If the test harness is configured to only synchronize the component under test when you manually push or rebuild, the coverage results are associated with the test harness.
  - When you close the test harness, the coverage results are removed from memory.
  - If the component under test design differs between test harness and main model, you cannot aggregate coverage results.
  - You can aggregate coverage results with the main model if the component under test design does not differ, but you must manually load the coverage results into the main model. See the function cvload (Simulink Coverage).
For information on coverage, see Collect Coverage in Tests