Main Content

sltest.harness.create

Create test harnesses

Description

sltest.harness.create(harnessOwner) creates one or more test harnesses for a model component or components harnessOwner, using default properties. Active and inactive configuration sets of the model are copied to the created harnesses.

example

sltest.harness.create(harnessOwner,Name=Value) uses additional options specified by one or more name-value arguments. If you create multiple harnesses, all of the harnesses use the specified property values. You can change the properties of an individual harness after it is created.

example

result = sltest.harness.create(harnessOwner,___) creates the harness and returns information about the created harness.

example

Examples

collapse all

Create a harness for the Controller subsystem of the f14 model.

openExample("f14");
sltest.harness.create("f14/Controller");

Create a harness for the f14 model. The harness is called sample_harness and has a Signal Editor block source and a Scope block sink.

openExample("f14");
sltest.harness.create("f14",Name="sample_harness"...
Source="Signal Editor",Sink="Scope")

Create a harness that uses a Stateflow® Chart as the test harness scheduler for the Controller subsystem of the f14 model.

openExample("f14");
sltest.harness.create("f14/Controller",SchedulerBlock="Chart");

Create a harness for the Controller subsystem and a harness for the Aircraft Dynamics Model subsystem of the f14 model. The name of the harness for the Controller subsystem is myf14Harness and the name for the Aircraft Dynamics Model subsystem is myf14Harness1.

openExample("f14")

result = sltest.harness.create(["f14/Controller",...
 "f14/Aircraft Dynamics Model"],...
 TopModel="f14",Name="myf14Harness");

Input Arguments

collapse all

Model or component handle or path, specified as a string or character vector of the full block path or double of the numeric component handle object. When creating harnesses for multiple components, specify the harness owners using one of these formats:

  • A cell array of character vectors or string array of the block paths of the components

  • A double array of the block handles of the components

  • An array of Simulink.BlockPath objects for the block paths of the components

Example: 1.9500e+03

Example: "model_name"

Example: "model_name/Subsystem"

Example: ["model_name/Subsystem1","model_name/Subsystem2"]

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: sltest.harness.create(Name="controller_harness",Source="Signal Editor",Sink="To File") creates a harness named controller_harness, with a Signal Editor block source and a To File block sink for the component under test.

Top model of the components in harnessOwners, specified as a numeric handle for the top model or as a string or character vector of the model name. This name-value argument is required if you create more than one test harness and is ignored if you create only one harness.

Harness name, specified as a character vector or string. If you create multiple harnesses, the function uses the Name argument as a prefix for the created harnesses. For example, if you specify the name as myHarness, the created harnesses are myHarness, myHarness1, and so on.

Harness description, specified as a character vector or string.

Example: Description="A test harness"

The input to the component under test in the harness, specified as "Inport", "Signal Editor", "From Workspace", "From File", "Test Sequence", "Chart", "None", or "Custom".

Example: Source="Signal Editor"

When Source is set to "Custom", the path to the library block to use as the source.

Example: CustomSourcePath="simulink/Sources/Sine Wave"

The output of the component under test in the harness, specified as "Outport", "Scope", "To Workspace", "To File", "Terminator", "None", or "Custom".

If your test harness contains a To Workspace block, the block variable is not saved in the base workspace after the test finishes running. Upon test completion, the base workspace is restored to its original state.

Example: Sink="Scope"

For a custom sink, the path to the library block to use as the sink, specified as a character vector or string.

Example: CustomSinkPath="simulink/Sinks/Display"

Option to add a separate Test Assessment block to the test harness, specified as numeric or logical 1 (true) or 0 (false).

Example: SeparateAssessment=true

Option to specify when the component under test synchronizes the main model and the test harness. Subsystem model test harnesses are always synchronized with their underlying model.

  • "SyncOnOpenAndClose" rebuilds the component under test from the main model when the test harness opens, and pushes changes from the component under test to the main model when the test harness closes.

  • "SyncOnOpen" rebuilds the component under test from the main model when the test harness opens. It does not push changes from the component under test to the main model when the test harness closes.

  • "SyncOnPushRebuildOnly" rebuilds and pushes changes only when you manually initiate rebuild or push for the entire test harness.

For more information, see Synchronize Changes Between Test Harness and Model

Example: SynchronizationMode="SyncOnOpen"

Option to specify harness creation without compiling the main model, specified as specified as numeric or logical 1 (true) or 0 (false). This option is set to true for Subsystem model test harnesses.

false compiles the model and runs other operations to support the harness build. true creates the harness without model compilation.

Example: CreateWithoutCompile = false

Option to specify what type of block to use in the test harness, specified as Normal, SIL, or PIL. SIL and PIL blocks require Simulink® Coder™. This option is set to Normal for Subsystem models.

Example: VerificationMode = "SIL"

Path to main build folder of existing generated code verified using Software-in-the-Loop (SIL) or Processor-in-the-Loop (/PIL), specified as a string or character vector. If you specify a build folder, the function uses the existing code in that folder, which enables faster harness creation time. If you do not specify a build folder, the function regenerates the code. ExistingBuildFolder does not apply if you are create multiple harnesses. You cannot set a default value for this property in an sl_customization file or by using sltest.harness.setHarnessCreateDefaults.

Example: ExistingBuildFolder="C:\TestMdl\SILHarness\Amplifier_ert_rtw"

Option to have the harness rebuild when it opens, specified as numeric or logical 1 (true) or 0 (false).

Example: RebuildOnOpen=true

Option to have the configuration set and model workspace entries updated during test harness rebuild, specified as numeric or logical 1 (true) or 0 (false). This option is set to true for Subsystem model test harnesses.

Example: RebuildModelData=true

Option to have each test harness saved as a separate SLX file, specified as numeric or logical 1 (true) or 0 (false). A model cannot use both external and internal test harness storage. If a model already has test harnesses, a new test harness follows the storage type of the existing harnesses, which this option does not override. See Manage Test Harnesses.

Example: SaveExternally=true

Path to the external test harness SLX file or to the harness folder, specified as a character vector or string. If you do not specify a harness path or set one using the sltest.harness.setHarnessCreateDefaults function or an sl_customization.m file, the function uses the current working directory for the harness path. When you create a harness, the harness file path or folder does not need to be on the MATLAB® path. However, to open a test harness, the harness or its folder must be on the MATLAB path.

For models or components under test without client or server ports, HarnessPath applies for external harnesses and only if you set SaveExternally to true. Specify the path to use for the external harness file or, if you create multiple harnesses, to the harness folder.

For models or components under test with client or server ports, HarnessPath specifies the harness folder and applies to both the internal and external harnesses. For external harnesses, the specified folder contains the test harness and mock architecture models. For internal harnesses, the folder contains only the mock architecture models. The harness is saved with the main model. The mock architecture models contain mock components for implementation of client or server components that communicate with the component under test. For more information, see Service Interfaces Overview (System Composer).

Example: HarnessPath="C:\MATLAB\SafetyTests"

Log all harness output signals for the component under test, specified as numeric or logical 1 (true) or 0 (false). When the value is true, all signals are logged, except for signals incompatible with logging. 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, you can remove its badge manually.

Example: LogOutputs=true

Use one or more post create callback functions to customize a test harness. The post create callback functions execute after the harness is created. To specify more than one callback, separate them with a comma. The callbacks execute in the order in which you list them. For more information, see Customize Test Harnesses.

Example: PostCreateCallback="HarnessCallback"

Example: PostCreateCallback={"HarnessCallback","SecondCallback"}

Example: PostCreateCallback=["HarnessCallback","SecondCallback"]

Use a post rebuild callback function to customize a test harness. The post rebuild callback function executes after the harness rebuild. For more information, see Customize Test Harnesses.

Example: PostRebuildCallback="HarnessCustomization"

Data Types: char

Option to drive model initialize, reset, and terminate ports with the chosen test harness source, specified as numeric or logical 1 (true) or 0 (false). This option only applies to harnesses created for a block diagram. This option is set to false for Subsystem models.

Example: ScheduleInitTermReset=true

Option to include a scheduler block in the test harness, specified as Test Sequence, MATLAB Function, Chart, or None. The block is included if the test harness is created for a model block diagram or a Model block and contains function calls or periodic event ports. To include no scheduler block and connect all ports to harness source blocks, use "None". If you are creating multiple harnesses, the same type of scheduler block is added to each harness.

Example: SchedulerBlock="Test Sequence"

Example: SchedulerBlock="None"

Option to shape scalar and double values to match the dimension of the input signals to the component under test, specified as numeric or logical 1 (true) or 0 (false). This option only applies to harnesses with Inport, Constant, Signal Editor, From Workspace, or From File blocks. This option is set to false for Subsystem models.

Example: AutoShapeInputs=true

Name of reusable library subsystem function interface, specified as a string or character vector. The function creates a test harness for the function interface of the reusable library subsystem. You cannot set a default value for this property in an sl_customization.m file or by using sltest.harness.setHarnessCreateDefaults. If you specify a FunctionInterfaceName when creating multiple harnesses, an error occurs.

Example: FunctionInterfaceName="double_RLS"

Output Arguments

collapse all

Harness information, errors, and warnings for the created harness or harnesses, returned as a structure. The structure has the same dimensions as the harnessOwner input argument. If the function creates a harness for the component successfully, the harnessInfo field is a structure with information about the created harness. If the harness is not created successfully, the error field contains the error as an object. The warning field contains warning messages that occur during harness creation.

The harnessInfo struct fields are: model, name, description, ownerHandle, ownerFullPath, ownerType, verificationMode, rebuildOnOpen, rebuildModelData, postRebuildCallback, graphical, origSrc, origSink, synchronizationMode, existingBuildFolder, and functionInterfaceName.

Version History

Introduced in R2015a

expand all