Customize Test Harnesses

You can customize a test harness by using a function that runs after creating or rebuilding the test harness. In the function, script the commands to customize your test harness. For example, the function can:

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.

The test harness customization function runs as a test harness post-create callback or post-rebuild callback. To customize a test harness using a callback function:

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 (Simulink).
Specify the function as the post-create or post-rebuild callback:
- For a new test harness,
  - If you are using the UI, enter the function name in the Post-create callback method or Post-rebuild callback method in the Advanced Properties of the harness creation dialog box.
  - If you are using sltest.harness.create, specify the function as the PostCreateCallback or PostRebuildCallback value.
- 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.
For more information on test harness properties, see Create 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. x 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:

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');
```

How to 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.

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 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 = fullfile(matlabroot,'examples','simulinktest','main',...
    '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)

The function 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. Copy the harness customization function to the temporary working directory.

copyfile(cbFile,tempdir);
cd(tempdir);

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

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

4. 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);