Documentation

Manage Test Harnesses

Internal and External Test Harnesses

You can save test harnesses internally as part of your model SLX file, or externally in separate SLX files. A model stores all test harnesses either internally or externally; it is not possible to use both types of harness storage in one model. You select internal or external test harness storage when you create the first test harness. If your model already has test harnesses, you can convert between the harness storage types.

If you store your model in a change control system, consider using external test harnesses. External test harnesses enable you to create or change a harness without changing the model file. If you plan to share your model often, consider using internal test harnesses to simplify file management. Creating or changing an internal test harness changes your model SLX file. Both internal and external test harnesses offer the same synchronization, push, rebuild, and badge interface functionality.

See Select Test Harness Properties.

Manage External Test Harnesses

Harnesses stored externally use a separate SLX file for each harness, and a <modelName>_harnessInfo.xml file containing metadata linking the model and the harnesses. Changing test harnesses can change the harnessInfo.xml file.

Follow these guidelines for external test harnesses:

Warning

Do not delete the harnessInfo.xml file. Deleting the harnessInfo.xml file terminates the relationship between the model and harnesses, which cannot be regenerated from the model.

  • Keep the harnessInfo.xml file in the same folder as the main model. If the harnessInfo.xml file and the model are in separate folders, the main model opens but does not present the test harnesses.

  • Directories containing test harness SLX files must be on the MATLAB® path.

  • If you convert internal test harnesses to external test harnesses, the new SLX files save to the current working folder.

  • If you convert external test harnesses to internal test harnesses, the external SLX files can be anywhere on the MATLAB path.

  • If your model uses external test harnesses, only create a copy of your model using File > Save As from the model menu. Using File > Save As copies external test harnesses to the destination folder of the new model and keeps the harness information current.

    Copying the model file on disk will not copy external harnesses associated with the model.

  • Only change or delete test harnesses using the Simulink® UI or commands:

    • To delete test harnesses, use the thumbnail UI or the sltest.harness.delete command.

    • To rename test harnesses, use the harness properties UI or the sltest.harness.set command.

    • To make a copy of an externally saved test harness, use the sltest.harness.clone command or save the test harness to a new name using File > Save As.

    Deleting or renaming harness files outside of Simulink causes an inaccurate harnessInfo.xml file and problems loading test harnesses.

Convert Between Internal and External Test Harnesses

You can change how your model stores test harnesses at different phases of your model lifecycle. For example:

  • Develop your model using internal test harnesses so that you can more easily share the model for review. When you complete your design and place the model under change control, convert to external harnesses.

  • Use the change-controlled model as the starting point for a new design. Test the existing model with external harnesses to avoid modifying it. Then, create a copy of the existing model. Convert to internal harnesses for the new development phase.

To change the test harness storage to external (or internal):

  1. Navigate to the top of the main model.

  2. Select Analysis > Test Harness > Convert To External (Internal) Harnesses.

  3. A dialog box provides information on the conversion procedure and the affected test harnesses. Click Yes to continue.

    The harnesses are converted.

  4. The conversion to external test harnesses creates an SLX file for each test harness and a harness information XML file <modelName>_harnessInfo.xml.

    Inversely, conversion to internal test harnesses moves the test harness SLX files and the harnessInfo.xml file.

Preview and Open a Test Harness

When a model component has a test harness, a badge appears in the lower right of the block. Click the badge to preview test harnesses, and click a thumbnail image to open the harness.

When a model block diagram has a test harness, click the pullout icon in the model canvas to preview the test harnesses. To open the harness, click a thumbnail.

Find Test Cases Associated with a Test Harness

To list open test cases that refer to the test harness, click the badge in the test harness canvas. You can click a test case name and navigate to the test case in the Test Manager.

Export Test Harnesses to Separate Models

You can export test harnesses to separate models, which is useful for archiving test harnesses or sharing a test harness design without sharing the model.

  • To export an individual test harness:

    1. From the test harness menu, select Analysis > Test Harness > Detach and Export Harness.

    2. A dialog box confirms the harness export. Click OK.

    3. Enter a file name for the separate model.

      The harness converts to a separate model. Converting removes the harness from the main model and breaks the relationship to the main model.

  • To export all harnesses in a model:

    1. Navigate to the top level of the test harness.

    2. Select no blocks.

    3. From the model menu, select Analysis > Test Harness > Detach and Export Harnesses.

    4. A dialog box confirms the harness export. Click OK.

      The harnesses convert to separate models. Converting removes the harnesses from the main model and breaks the relationships to the main model.

See sltest.harness.export.

Clone and Export a Test Harness to a Separate Model

This example demonstrates cloning an existing test harness and exporting the cloned harness to a separate model. This can be useful if you want to create a copy of a test harness as a separate model, but leave the test harness associated with the model component.

High-level Workflow

  1. If you don't know the exact properties of the test harness you want to clone, get them using sltest.harness.find. You need the harness owner ID and the harness name.

  2. Clone the test harness using sltest.harness.clone.

  3. Export the test harness to a separate model using sltest.harness.export. Note that there is no association between the exported model and the original model. The exported model stands alone.

Open the Model and Save a Local Copy

model = 'sltestTestSequenceExample';
open_system(model)

Save the local copy in a writable location on the MATLAB path.

Get the Properties of the Source Test Harness

properties = sltest.harness.find([model '/shift_controller'])
properties = 

  struct with fields:

                  model: 'sltestTestSequenceExample'
                   name: 'controller_harness'
            description: ''
                   type: 'Testing'
            ownerHandle: 13.0010
          ownerFullPath: 'sltestTestSequenceExample/shift_controller'
              ownerType: 'Simulink.SubSystem'
                 isOpen: 0
            canBeOpened: 1
               lockMode: 0
       verificationMode: 0
         saveExternally: 0
          rebuildOnOpen: 0
       rebuildModelData: 0
    postRebuildCallback: ''
              graphical: 0
                origSrc: 'Test Sequence'
               origSink: 'Test Assessment'
    synchronizationMode: 0

Clone the Test Harness

Clone the test harness using sltest.harness.clone, the ownerFullPath and the name fields of the harness properties structure.

sltest.harness.clone(properties.ownerFullPath,properties.name,'ControllerHarness2')

Save the Model

Before exporting the harness, save changes to the model.

save_system(model)

Export the Test Harness to a Separate Model

Export the test harness using sltest.harness.export. The exported model name is ControllerTestModel.

sltest.harness.export([model '/shift_controller'],'ControllerHarness2',...
    'Name','ControllerTestModel')
clear('model')
clear('properties')
close_system('sltestTestSequenceExample',0)

Delete Test Harnesses Programmatically

This example shows how to delete test harnesses programmatically. Deleting with % the programmatic interface can be useful when your model has multiple test harnesses at different hierarchy levels. This example demonstrates creating four test harnesses, then deleting them.

1. Open the model

open_system('sltestCar');

2. Create two harnesses for the transmission subsystem, and two harnesses for the transmission ratio subsystem.

sltest.harness.create('sltestCar/transmission');
sltest.harness.create('sltestCar/transmission');
sltest.harness.create('sltestCar/transmission/transmission ratio');
sltest.harness.create('sltestCar/transmission/transmission ratio');

3. Find the harnesses in the model.

test_harness_list = sltest.harness.find('sltestCar')
test_harness_list = 

  1x5 struct array with fields:

    model
    name
    description
    type
    ownerHandle
    ownerFullPath
    ownerType
    isOpen
    canBeOpened
    lockMode
    verificationMode
    saveExternally
    rebuildOnOpen
    rebuildModelData
    postRebuildCallback
    graphical
    origSrc
    origSink
    synchronizationMode

4. Delete the harnesses.

for k = 1:length(test_harness_list)
     sltest.harness.delete(test_harness_list(k).ownerFullPath,...
     test_harness_list(k).name)
end
close_system('sltestCar',0);

Move and Clone Test Harnesses

Simulink Test™ gives you the ability to move/clone test harnesses from a source owner to a destination owner without having to compile the model. You can move or clone:

  • Subsystem harnesses across subsystems. The destination subsystem could also be in a different model.

  • Harnesses for library components across libraries.

To move or clone harnesses, right-click the Simulink canvas and select Test Harness > Manage Test Harnesses. The Manage Test Harness dialog box opens and lists the test harnesses associated with the subsystem/block specified in Filter by harness owner. Click Actions to access the Move and Clone options.

Select the destination path and name your test harness.

See Also

Functions

Was this topic helpful?