Customize Test Harnesses

You can customize a test harness by using one or more functions that run as callbacks after creating the test harness. You can use one function to run as a callback for rebuilding the test harness. In the function, write the commands to customize your test harness. For example, you can create functions to:

Connect custom source or sink blocks.
Add a plant subsystem for closed-loop testing.
Change the configuration set.
Enable signal logging.
Change the simulation stop time.

To customize a test harness using callback functions:

Create the callback function.
In the function, use the Simulink^® programmatic interface to script the commands to customize the test harness. For more information, see the functions listed in Programmatic Model Editing.
Specify the function or functions as the post-create or a single function as a post-rebuild callback:
- For a new test harness,
  - If you are using the UI, enter the function names in the Post-create callback method, separated by commas, or a single function name in the Post-rebuild callback method in the Create Test Harness dialog box.
  - If you are using sltest.harness.create, specify the function as the PostCreateCallback or PostRebuildCallback value. For the PostCreateCallback, you can specify more than one function.
- For an existing test harness,
  - If you are using the UI, enter the function name in Post-rebuild callback method in the harness properties dialog box.
  - If you are using sltest.harness.set, specify the function as the PostRebuildCallback value.

Another way to customize test harnesses is by setting your own defaults for creating harnesses. For more information, see Create or Import Test Harnesses and Select Properties.

Callback Function Definition and Harness Information

The callback function declaration is

function myfun(x)

where myfun is the function name and myfun accepts input x. The x input is a struct of information about the test harness automatically created when the test harness uses the callback. You can choose the function and argument names.

For example, define a harness callback function harnessCustomization.m:

function harnessCustomization(harnessInfo)

% Script commands here to customize your test harness.

end

In this example, harnessInfo is the struct name and harnessCustomization is the function name. When the create or rebuild operation calls harnessCustomization, harnessInfo is populated with information about the test harness, including handles to the test harness model, main model, and blocks in the test harness.

For example, using harnessCustomization as a callback for the following test harness:

Test harness for the Roll Reference subsystem

populates harnessInfo with handles to three sources, one sink, the main model, harness model, harness owner, component under test, and conversion subsystems:

harnessInfo = 

  struct with fields:

                    MainModel: 2.0001
                 HarnessModel: 1.1290e+03
                        Owner: 17.0001
                   HarnessCUT: 201.0110
              DataStoreMemory: []
                DataStoreRead: []
               DataStoreWrite: []
                         Goto: []
                         From: []
                      GotoTag: []
       SimulinkFunctionCaller: []
         SimulinkFunctionStub: []
                      Sources: [1.1530e+03 1.1540e+03 1.1550e+03]
                        Sinks: 1.1630e+03
              AssessmentBlock: []
     InputConversionSubsystem: 1.1360e+03
    OutputConversionSubsystem: 1.1560e+03
                   CanvasArea: [215 140 770 260]

Use the struct fields to customize the test harness. For example:

To add a Constant block named ConstInput to the test harness, get the name of the test harness model, then use the add_block function.

harnessName = get_param(harnessInfo.HarnessModel,'Name');
block = add_block('simulink/Sources/Constant',...
   [harnessName '/ConstInput']);

To get the port handles for the component under test, get the 'PortHandles' parameter for harnessInfo.HarnessCUT.
```
CUTPorts = get_param(harnessInfo.HarnessCUT,'PortHandles');
```
To get the simulation stop time for the test harness, get the 'StopTime' parameter for harnessInfo.HarnessModel.
```
st = get_param(harnessInfo.HarnessModel,'StopTime');
```
To set a 16 second simulation stop time for the test harness, set the 'StopTime' parameter for harnessInfo.HarnessModel.
```
set_param(harnessInfo.HarnessModel,'StopTime','16');
```

Display Harness Information struct Contents

To list the harness information for your test harness:

In the callback function, add the line
```
disp(harnessInfo)
```
Create or rebuild a test harness using the callback function.
When you create or rebuild the test harness, the harness information structure contents are displayed on the command line.

Share Data Between Callbacks

Callback scripts are evaluated in the MATLAB^® base workspace. To share data between callback scripts, use assignin and evalin to store and retrieve data from the base workspace. For example,

assignin('base','a',2);
a = evalin('base','a');

For parallel execution, post-load and cleanup callbacks are evaluated on the parallel MATLAB worker, where the callbacks have their own base workspaces. Variables created in a test case pre-load callback and test file and test suite setup callbacks are also available in the parallel MATLAB worker base workspace. Prior to execution, the base workspace variables are transferred from the client MATLAB to the parallel MATLAB workers.

Customize a Test Harness to Create Mixed Source Types

This example harness callback function connects a Constant block to the third component input of this example test harness.

The function follows the procedure:

Get the harness model name.
Add a Constant block.
Get the port handles for the Constant block.
Get the port handles for the input conversion subsystem.
Get the handles for lines connected to the input conversion subsystem.
Delete the existing Inport block.
Delete the remaining line.
Connect a new line from the Constant block to input 3 of the input conversion subsystem.

function harnessCustomization(harnessInfo)

% Get harness model name:
harnessName = get_param(harnessInfo.HarnessModel,'Name');

% Add Constant block:
constBlock = add_block('simulink/Sources/Constant',...
   [harnessName '/ConstInput']);

% Get handles for relevant ports and lines:
constPorts = get_param(constBlock,'PortHandles');
icsPorts = get_param(harnessInfo.InputConversionSubsystem,...
   'PortHandles');
icsLineHandles = get_param...
   (harnessInfo.InputConversionSubsystem,'LineHandles');

% Delete the existing Inport block and the adjacent line:
delete_block(harnessInfo.Sources(3));
delete_line(icsLineHandles.Inport(3));

% Connect the Constant block to the input 
% conversion subsystem:
add_line(harnessInfo.HarnessModel,constPorts.Outport,...
   icsPorts.Inport(3),'autorouting','on');

end

Test harness with callback updates

Test Harness Callback Example

Open Script

This example shows how to use a post-create callback to customize a test harness. The callback changes one harness source from an Inport block to Constant block and enables signal logging in the test harness.

The Model

In this example, you create a test harness for the Roll Reference subsystem.

open_system('RollAutopilotMdlRef')

Get Path to the Harness Customization Function

cbFile = 'harnessSourceLogCustomization.m';

The Customization Function and Test Harness Information

The function harnessSourceLogCustomization changes the third source block, and enables signal logging on the component under test inputs and outputs. You can read the function by entering:

  type(cbFile)

As an alternative to including output logging code in the callback, you can use Log Output Signals in the Create New Harness dialog box, or use 'LogOutputs',true as an input to sltest.harness.create. These options log all component under test output signals in the test harness and return test results for those signals.

The function harnessSourceLogCustomization uses an argument. The argument is a struct listing test harness information. The information includes handles to blocks in the test harness, including:

Component under test
Input subsystems
Sources and sinks
The harness owner in the main model

For example, harnessInfo.Sources lists the handles to the test harness source blocks.

Create the Customized Test Harness

1. In the RollAutopilotMdlRef model, right-click the Roll Reference subsystem and select Test Harness > Create for Roll Reference.

2. In the harness creation dialog box, for Post-create callback method, enter harnessSourceLogCustomization.

3. Click OK to create the test harness. The harness shows the signal logging and simulation stop time specified in the callback function.

You can also use the sltest.harness.create function to create the test harness, specifying the callback function with the 'PostCreateCallback' name-value pair.

sltest.harness.create('RollAutopilotMdlRef/Roll Reference',...
    'Name','LoggingHarness',...
    'PostCreateCallback','harnessSourceLogCustomization');

sltest.harness.open('RollAutopilotMdlRef/Roll Reference','LoggingHarness');

close_system('RollAutopilotMdlRef',0);