Create or Import Test Harnesses and Select Properties

Test harnesses are separate workspaces you can use to isolate tests from your design model. You can create test harnesses for your whole model or for one or more components in your model. You can also import a test harness from a standalone test model.

Create a Test Harness For a Top Level Model

To create a test harness for a top-level model (including subsystem and model reference models):

Right-click in the Simulink^® model and click Test Harness > Create for Model to open the Create Test Harness dialog box.
After selecting the desired options, click OK to create the test harness.

For information on the Create Test Harness dialog box properties, see Create Test Harness Dialog Box Properties.

Create Test Harnesses for Model Components

To create a test harness for one or multiple model components:

On the Apps tab, under Model Verification, Validation, and Test, click Simulink Test.
On the Tests tab, click Simulink Test Manager to open the Test Manager.
Create a new test file in the Test Manager.
Click New > Test for Model Component, which opens the Create Test for Model Component workflow wizard.
On the first page of the wizard, specify the model and select the component or components. If you select multiple components, the wizard creates a test harness for each component.
Create the test harness or harnesses by completing the wizard pages.

Note

The Create Test for Model Component workflow wizard exposes a subset of test harness options. If your test harness does not need to use non-default options, use the wizard to create a harness quickly. If you need to change other options, use the Test Manager for the test harness you created with the wizard. For information on using the wizard and the properties it sets, see Generate Tests and Test Harnesses for a Model or Components.

Import a Test Harness

To import a test harness from a standalone test model:

Right-click in the Simulink model or on a model component and click Test Harness > Import for Model or Test Harness > Import for Component, respectively, to open the Import Test Harness dialog box.
After selecting the desired options, click OK to import the test harness.

Note

Importing test harnesses for Software Architecture components that have client-server ports is not supported.

For information on the Import Test Harness dialog box properties, see Import Test Harness Dialog Box Properties.

Preview and Open Test Harnesses

When a model component has a test harness, a badge appears in the lower right of the block. To view the test harnesses, click the badge. To open a test harness, click a tile.

Test harness tiles from component badge

To view test harnesses for a model block diagram, click the pullout icon in the model canvas. To open a test harness, click a tile.

Test harness tiles from canvas pullout

Change Test Harness Properties

To change properties of an open test harness, click the badge in the test harness block diagram and click Test harness properties to open the harness properties dialog box.

To change properties of test harnesses from the main model, click the Harness operations icon from the test harness preview.

Access harness operations from the badge

Considerations for Selecting Test Harness Properties

Before selecting test harness properties, consider the following:

What data source you want to use for your test case input
How you want to view or store test output
Whether you want to copy parameters and workspaces from the main model to the harness
Whether you plan to edit the component under test
How you want to synchronize changes between the test harness and model

Except for sources and sinks, you can change harness properties later using the harness properties dialog box. To change sources and sinks after harness creation, manually remove the blocks from the test harness and replace them with new sources and sinks.

Note

The following sections describe the test harness properties in the Create Test Harness dialog box. For information on the test harness properties in the Create Test for Model Component wizard, see Generate Tests and Test Harnesses for a Model or Components.

Create Test Harness Dialog Box Properties

Harness Name

Test harnesses must use valid MATLAB^® file names.

Save test harnesses externally

Use this check box to select whether the model stores test harnesses internally or externally:

When cleared, the model saves test harnesses internally, as part of the model SLX or MDL file.
When selected, the model saves test harnesses externally, in separate SLX files in the current working folder, and adds a harness information XML file to the model folder. The harness information file can be in any location on the MATLAB path.

If a model already has test harnesses, the dialog box does not display the check box. Instead the dialog box displays the message Harnesses saved internally or Harnesses saved externally, which indicates how previously created test harnesses are stored. All test harnesses for a model are stored either internally or externally so when you create an additional harness, it is stored in the same way as previous harnesses.

See Manage Test Harnesses.

Select Function Interface

Select the function interface to associate with the reusable library subsystem test harness. This option appears only if the component under test is a reusable library subsystem with a function interface.

Sources and Sinks

In the Create Test Harness dialog box, under Sources and Sinks, select the source and sink from the respective menus. The menus provide common sources and sinks.

You can use source and sink blocks from the Simulink Sources or Sinks library. Select Custom source or sink, and enter the path to the block. For example:

simulink/Sources/Sine Wave

simulink/Sinks/Terminator

Custom sources and sinks build the test harness with one block per port.

Create scalar inputs

When you select this property, the test harness creates scalar inputs for multidimensional signals. The individual scalar inputs are reshaped to match the dimension of the input signals to the component under test. Scalar expansion is performed only when the harness owner model can be compiled before harness generation. Libraries, subsystem models, and harnesses created with the Create without compiling the model option set do not compile first so Create scalar inputs does not apply to them. Create scalar inputs applies to test harnesses with Inport, Constant, Signal Editor, From Workspace, or From File source blocks.

Add scheduler for function-calls and rates / Generate function-call signals using

The title of this option depends on whether the component under test is a subsystem or a model. Use a scheduler to control the number of times and the order in which blocks or subsystems are executed. To include a scheduler block in your test harness, select a block from the drop-down list. You can use a Test Sequence block, a MATLAB Function block, or a Stateflow^® chart as the scheduler.

Add scheduler for function-calls and rates: For a model, you can use the block to call functions and set sample times for model inputs and outputs.
Generate function-call signals using: For a subsystem, you can use the block to call functions in the subsystem.

For information on schedulers, see Rate Transitions (Embedded Coder), Rate Transitions and Asynchronous Blocks (Embedded Coder), or Schedule Simulink Functions by Using Stateflow (Stateflow)

Enable Initialize, Reset, and Terminate ports

Selecting this option exposes initialize, terminate, or reset function-call ports in the component under test and connects the scheduler block to the ports.

This option appears when you create a test harness for a top-level model and select a block for the Add scheduler for function-calls and rates option.

When running the test harness, if you encounter an error about executing a function call at an initialize, reset, or terminate port, use these commands to hide and disconnect the ports. Subsystem_name is the system under test in the test harness.

set_param(<Subsystem_name>,'ShowModelInitializePort','off');
set_param(<Subsystem_name>,'ShowModelResetPorts','off');
set_param(<Subsystem_name>,'ShowModelTerminatePort','off');

Add Separate Assessment Block

Select Add separate assessment block to include a separate Test Assessment block in the test harness.

A Test Assessment block is a separate Test Sequence block configured with properties commonly used for verifying the component under test. For more information, see Assess Simulation and Compare Output Data and Verify Model Simulation by Using When Decomposition.

Log Output Signals

Select Log output signals to log all output signals of the component under test. You can use this option only when creating a new harness. Signals are logged during test case execution and return test results. If an output signal does not have a name or a propagated name, it is assigned one in the harness using the format <component under test name>:<output port number>. To remove a signal from being logged, open the harness, right-click the signal, and select Stop Logging Selected Signals.

Open Harness After Creation

Clear Open Harness After Creation to create the test harness without opening it. This can be useful creating multiple test harnesses in succession.

Create without compiling the model

Creating a test harness without compiling the model can be useful if you are prototyping a design that cannot yet compile. When you create a test harness without compiling the main model:

Parameters are not copied to the test harness workspace.
The main model configuration is not copied to the test harness.
The test harness does not contain conversion subsystems.

You may need to add blocks such as signal conversion blocks to the test harness. You can rebuild the harness when you are ready to compile the main model. For more information, see Synchronize Changes Between Test Harness and Model.

Test harnesses for Subsystem models are created without compiling the model.

Verification Modes

The test harness verification mode determines the type of block generated in the test harness.

Normal: A Simulink block diagram.
Software-in-the-Loop (SIL): The component under test references generated code, operating as software-in-the-loop. Requires Embedded Coder^®.
Processor-in-the-Loop (PIL): The component under test references generated code for a specific processor instruction set, operating as processor-in-the-loop. Requires Embedded Coder.

Subsystem model test harnesses do not support SIL or PIL verification.

Note

Keep the SIL or PIL code in the test harness synchronized with the latest component design. If you select SIL or PIL verification mode without selecting Rebuild harness on open, your SIL or PIL block code might not reflect recent updates to the main model design. To regenerate code for the SIL or PIL block in the test harness, select Rebuild Harness > Update Harness Configuration Settings and Model Workspace.

Use generated code to create SIL/PIL block

If generated code for the SIL/PIL block already exists, select this property to use that existing code instead of regenerating the code. This option is available only for subsystem harnesses. It does not apply to Subsystem model test harnesses.

Build folder

Specify the folder that contains the generated code for the SIL/PIL block. This option is available only if you selected Use generated code to create SIL/PIL block.

Post-create callback method

You can customize your test harness using one or more post-create callbacks. A post-create callback is a function that runs after the harness is created. For example, your callback can set up signal logging, add custom blocks, or change the harness simulation times. If you specify more than one callback, separate them using commas. The callbacks run in the order that they are listed. For more information, see Customize Test Harnesses. This option does not apply to Subsystem model test harnesses.

Rebuild harness on open

When you select this property, the test harness rebuilds every time you open it. If you specified to use existing generated code for a SIL/PIL subsystem using sltest.harness.create or sltest.harness.set, the harness rebuild uses that code instead of regenerating it. For details on the rebuild process, see Synchronize Changes Between Test Harness and Model. This option does not apply to Subsystem model test harnesses.

Update Configuration Parameters and Model Workspace data on rebuild

When you select this property, configuration parameters and model workspace data update when you rebuild the harness. For details on the rebuild process, see Synchronize Changes Between Test Harness and Model. This option does not apply to Subsystem model test harnesses.

Post-rebuild callback method

You can customize your test harness using a post-rebuild callback. A post-rebuild callback is a function that runs after the harness is rebuilt. For example, your callback can set up signal logging, add custom blocks, or change the harness simulation times. For more information, see Customize Test Harnesses. This option does not apply to Subsystem model test harnesses.

Synchronization Mode

Synchronization mode controls when changes to the component under test are synced to the main model, and when changes to the harness owner are synced into a test harness. The synchronization mode also affects model and harness locking.

For additional information and limitations, see Synchronize Changes Between Test Harness and Model, Set Synchronization for a New Test Harness, and Model and Test Harness Locking.

Note

Synchronization differs depending on whether one test harness or more than one test harness is open. See the Description column of this table for information.

Synchronization Type	Description	Availability	Model, CUT, and Harness Locking When Harness Is Open
Synchronize on harness open and close	When you open only one test harness, the harness components and parameters synchronize from the model to the test harness. When you close the only open test harness, the same elements synchronize from the harness to the model. When you open multiple harnesses, synchronization occurs from the model to the harness, but if any harnesses remain open, synchronization does not occur when you close a harness.	Available for: Subsystems, including Stateflow charts and MATLAB Function blocks For Subsystem Reference blocks, only the block parameters are synchronized Model blocks S-function blocks Not available for: Block diagrams SIL/PIL harnesses Subsystem model harnesses	When only one harness is open, CUTs in the main model are unlocked, but CUTs in subsystems are locked.. Subsystem CUTs in the harness are unlocked. When more than one harness is open, the CUTs in model harnesses, subsystem harnesses, library harnesses, and MATLAB functions are locked.
Synchronize on harness open	When you open one or more test harnesses, the harness components and parameters synchronize from the model to the test harness.	Available for: Block diagrams Subsystems, including Stateflow charts and MATLAB Function blocks For Subsystem Reference blocks, only the block parameters are synchronized Model reference blocks S-function blocks Not available for: SIL/PIL harnesses Subsystem model harnesses	When only one harness is open, CUTs in the main model and harness are unlocked, but CUTs in subsystems in the main model and harness are locked. When more than one harness is open, the CUTs in model harnesses, subsystem harnesses, library harnesses, and MATLAB functions are locked.
Synchronize only during push and rebuild	When only one harness is open, synchronization occurs when you click Push Changes or Rebuild Harness. Clicking Push synchronizes the changes from the test harness to the model. Clicking Rebuild synchronizes changes the from the model to the test harness. When more than one harness is open, synchronization occurs only when you rebuild the model. Push synchronization is not supported.	Available for: Subsystems, including Stateflow charts and MATLAB Function blocks Model reference blocks S-function blocks Subsystem models, which always synchronize on the push and rebuild only. Not available for: Block diagrams SIL/PIL harnesses Components in libraries	When one or more harnesses are open, the main model, harness, and all types of CUTs in the model and harness, including subsystems, are unlocked.
Synchronize only during rebuild	When one or more harnesses are open, synchronization occurs only when you click Rebuild Harness. Changes synchronize from the model to the test harness.	Available for: Block diagrams Model reference blocks SIL/PIL verification mode components Not available for: Subsystems, including Stateflow charts and MATLAB Function blocks S-function blocks Components in libraries	The main model, harness, and all types of CUTs in the model are unlocked. All types of CUTs in the harness are unlocked, except SIL/PIL verification mode components, which are locked and masked.

Import Test Harness Dialog Box Properties

Name

Name to use for the imported test harness. Test harnesses must use valid MATLAB file names.

Save Test Harnesses Externally

This option controls how the model stores test harnesses. A model stores all its test harnesses either internally or externally.

If a model already has test harnesses, the dialog box does not display the check box. The dialog box displays either Harnesses saved internally or Harnesses saved externally, which indicates how previously created test harnesses are stored. Since all test harnesses for a model are stored either internally or externally, when you create an additional harness, it is stored in the same way as previous harnesses.

When cleared, the model saves test harnesses as part of the model SLX file.
When selected, the model saves test harnesses in separate SLX files in the current working folder, and adds a harness information XML file to the model folder. The harness information file can be in any location that is on the MATLAB path.

See Manage Test Harnesses.

Simulink model to import

Name of or full path to the Simulink standalone test model to import.

Component under Test in imported model

Path to the component under test in the imported Simulink standalone test model.

Rebuild harness on open

Update Configuration Parameters and Model Workspace data on rebuild

Customize Test Harness Creation Default Property Values

To set default property values for the creation of new test harnesses, use an sl_customization file or the setHarnessCreateDefaults function. All newly created test harnesses use the new default values.

To see the current default test harness property values, use sltest.harness.getHarnessCreateDefaults.

For an individual test harness, you can change the property values from the default values by using the Create Test Harness dialog box or the sltest.harness.create function. Using either of these options does not change the default values used when creating a new test harness. See also Create Test Harness Dialog Box Properties and Change Test Harness Properties.

Set Defaults by Using an `sl_customization.m` File

To change the default property values used when creating new test harnesses, you can create an sl_customization.m file.

Create an sl_customization.m file and specify the new default property values.
You can set all name-value arguments of sltest.harness.create, except where noted.
This sample sl_customization.m file sets the harness name to myTestHarness, sets a post-create callback to use the addHarnessAnnotation function, saves the harness internally, and logs outputs:
```
function sl_customization(cm)
   % Create the struct with the harness options
   myStruct.Name="myTestHarness"
   myStruct.PostCreateCallback = "addHarnessAnnotation";
   myStruct.SaveExternally = false;
   myStruct.LogOutputs = true;

   % Invoke harness customization
   cObj = cm.SimulinkTestCustomizer;
   cObj.setHarnessCreateDefaults(myStruct);
end
```
Save the sl_customization.m file.
Add the file to the MATLAB path.
Register the new customizations by reloading Simulink or by using sl_refresh_customizations. For more information, see Register Customizations with Simulink.

Note
When you register a file, its values become the default property values. All new test harnesses use the default property values and all previously registered values are cleared.

To view the customized default values, use sltest.harness.getHarnessCreateDefaults.

Set Defaults by Using the `setHarnessCreateDefaults` Function

You can also use sltest.harness.setHarnessCreateDefaults to set the default property values. You can set any of the name-value pair properties described in sltest.harness.create, except where noted. Using sltest.harness.setHarnessCreateDefaults saves and registers the default property values. However, if you already set and registered values using an sl_customization.m file, using sltest.harness.setHarnessCreateDefaults overwrites the values specified in the file.