Main Content

Manage Test Harnesses

You can export, clone, move, and delete the test harnesses associated with your model, or change where the model stores the test harnesses. You can save test harnesses internally as part of the model SLX or MDL file or externally in separate SLX files. Because all test harnesses must be either internal or external, you cannot use both types of harness storage in one model.

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

Manage External Test Harnesses

Models with external test harnesses use a separate SLX file for each harness, and an XML file with the name <modelName>_harnessInfo.xml to store the metadata that links the model and the harnesses. Changing test harnesses can change the harnessInfo.xml file. The metadata and the model are linked using a unique ID for the model. By default, the metadata XML file is created in the same folder as the model.

Follow these guidelines for external test harnesses:

Warning

Do not delete or make any manual changes to the harnessInfo.xml file. Deleting the harnessInfo.xml file might sever the relationship between the model and harnesses, which cannot be regenerated from the model.

  • The harnessInfo.xml file must be writable to save changes to the test harness or the main model.

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

  • If the test harness harnessInfo.xml file is not in the same folder as the model, the XML file or its folder must be on the MATLAB path.

  • If you convert internal test harnesses to external test harnesses, the new SLX files are saved in 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 Save > Save as. Using Save as copies external test harnesses to the destination folder of the new model, renames the harnesses, 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 Save > 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 configuration management 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. On the Apps tab, under Model Verification, Validation, and Test, click Simulink Test. Then, on the Tests tab, click Manage Test Harnesses > Convert to External Harnesses or Convert to 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.

    External test harness and files list

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

    Internal harness and main model list

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

Model and Test Harness Locking

Model and test harness locking is specific to each type of synchronization. For information, see Synchronization Mode.

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.

Test cases of a test harness

Export Test Harnesses to Standalone Models

You can export test harnesses to standalone 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 individual harness model, on the Apps tab, under Model Verification, Validation, and Test, click Simulink Test.

    2. In the Harness tab, click Detach and Export.

    3. In the Export Test Harness to Independent Model dialog box, click OK.

    4. In the Save As dialog box, enter a filename for the standalone harness model and click OK.

    5. The harness converts to a standalone model.

      Converting removes the harness from the main model and breaks the relationship to the main model. If a model has only one harness, its harnessInfo.xml file is deleted. If a model has more than one harness and you delete one of them, the harnessInfo.xml file is updated.

  • To export all harnesses in a model:

    1. Navigate to the top level of the model. Do not select any blocks.

    2. On the Apps tab, under Model Verification, Validation, and Test, click Simulink Test.

    3. In the Harness tab, click Detach and Export.

    4. In the Export Test Harness to Independent Model dialog box, click OK.

    5. In the Save As dialog box, enter a filename for the separate model and click OK.

    6. All test harnesses are exported and converted into standalone models.

      Exporting removes the harnesses from the main model, deletes the harnessInfo.xml file, and breaks the relationships to the main model.

See sltest.harness.export.

Move and Clone Test Harnesses

Simulink Test™ gives you the ability to move or 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.

  • Subsystem Reference block harnesses to other Subsystem Reference block harnesses.

  • Subsystem Reference block harnesses to and from Subsystem model harnesses.

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 or block specified in Filter by harness owner. Click Actions to access the Move and Clone options.

Manage Test Harnesses dialog box Actions menu

Move Harness dialog box

Select the destination path and name your test harness.

Test Harness Transfer When Converting Subsystems to Model References

When you convert a Subsystem or Subsystem Reference block to a Model block, the test harnesses are transferred to the model being referenced. Harnesses on the Subsystem block are converted to block diagram harnesses. Nested harnesses in subsystems are copied to identical blocks in the Model block. 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.

Clone and Export a Test Harness to a Separate Model

Open Script

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

open_system("sf_car")

Get the Properties of the Source Test Harness

properties = sltest.harness.find("sf_car/shift_logic")

properties = 

  struct with fields:

                    model: 'sf_car'
                     name: 'TestDownshiftPointsHarness'
              description: ''
                     type: 'Testing'
              ownerHandle: 415.0006
            ownerFullPath: 'sf_car/shift_logic'
                ownerType: 'Simulink.SubSystem'
                   isOpen: 0
              canBeOpened: 1
         verificationMode: 0
           saveExternally: 0
            rebuildOnOpen: 0
         rebuildModelData: 0
      postRebuildCallback: ''
                graphical: 0
                  origSrc: 'Test Sequence'
                 origSink: 'Test Assessment'
      synchronizationMode: 2
      existingBuildFolder: ''
    functionInterfaceName: ''

Clone the Test Harness

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

newHarness = "ControllerHarness";
sltest.harness.clone(properties.ownerFullPath,properties.name,newHarness)

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("sf_car/shift_logic",newHarness,...
      Name="ControllerTestModel")

Close the model without saving it.

close_system("sf_car",0)

Delete Test Harnesses Programmatically

This example uses:

Open Script

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

1. Open the model.

model = "sf_car";
open_system(model);

2. Display the name and owner of the original harness in the model.

testHarnesses = sltest.harness.find(model);
originalHarness = testHarnesses.name;
disp(table({testHarnesses.name}', ...
    {testHarnesses.ownerFullPath}', ...
    VariableNames=["Name","Owner"]))

                 Name                         Owner         
    ______________________________    ______________________

    {'TestDownshiftPointsHarness'}    {'sf_car/shift_logic'}

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

subsystem1 = "sf_car/transmission";
subsystem2 = "sf_car/transmission/transmission ratio";

sltest.harness.create(subsystem1);
sltest.harness.create(subsystem1);
sltest.harness.create(subsystem2);
sltest.harness.create(subsystem2);

4. Display the names and owners of the harnesses in the model.

testHarnesses = sltest.harness.find(model);
disp(table({testHarnesses.name}', ...
    {testHarnesses.ownerFullPath}', ...
    VariableNames=["Name","Owner"]))

                 Name                                  Owner                 
    ______________________________    _______________________________________

    {'TestDownshiftPointsHarness'}    {'sf_car/shift_logic'                 }
    {'sf_car_Harness1'           }    {'sf_car/transmission'                }
    {'sf_car_Harness2'           }    {'sf_car/transmission'                }
    {'sf_car_Harness3'           }    {'sf_car/transmission/transmission...'}
    {'sf_car_Harness4'           }    {'sf_car/transmission/transmission...'}

5. Delete the new harnesses.

for k = 1:length(testHarnesses)
    if ~strcmp(testHarnesses(k).name,originalHarness)
        sltest.harness.delete(testHarnesses(k).ownerFullPath,...
            testHarnesses(k).name)
    end
end

6. Display the name and owner of the harness in the model.

testHarnesses = sltest.harness.find(model);
disp(table({testHarnesses.name}', ...
    {testHarnesses.ownerFullPath}', ...
    VariableNames=["Name","Owner"]))

                 Name                         Owner         
    ______________________________    ______________________

    {'TestDownshiftPointsHarness'}    {'sf_car/shift_logic'}

7. Close the model without saving it.

close_system(model,0);

Export Test Harness to Previous Version

When you export a Simulink model that has one or more test harnesses to a previous MATLAB version, the impact on the harnesses depends on whether they are internal or external.

  • For models with internal harnesses, the harnesses stay internal and are exported with the model.

  • For models with external harnesses, the harnesses in the exported model are converted to internal harnesses. To change the internal harnesses back to external, see Convert Between Internal and External Test Harnesses.

You cannot export internal or external harnesses without also exporting their parent model to a previous version. To work around this restriction, export the harness to a standalone model, export the harness model to the previous version, and then import it into the main model. After importing the harness, check the harness settings. You might need to reset some properties, such as the synchronization mode and rebuild. See Export Test Harnesses to Standalone Models and Change Test Harness Properties.

See Also

| | | | | | | |

Related Topics