Main Content

sltest.testmanager.createTestForComponent

Create test cases and test harnesses for model or model components

Since R2020b

collapse all in page

Syntax

[tc,status] = sltest.testmanager.createTestForComponent('TestFile',tf,'Component',component)
[tc,status] = sltest.testmanager.createTestForComponent('TestFile',tf,'TopModel',topModel, 'Component',component)
[tc,status] = sltest.testmanager.createTestForComponent(___,Name,Value)

Description

[tc,status] = sltest.testmanager.createTestForComponent('TestFile',tf,'Component',component) creates a test case and a test harness for the specified component in the test file or test suite, tf. The component must be a single component and the test file tf must already exist. If the test file does not exist, you can include the CreateTestFile, true Name-Value argument to create one. The returned status indicates whether the test case tc was created successfully.

example

[tc,status] = sltest.testmanager.createTestForComponent('TestFile',tf,'TopModel',topModel, 'Component',component) creates a test case and test harness for each component specified in the component array. If a test case was not created successfully, the tc array contains an MException object for that test case. Use this syntax to create more than one test case and harness.

example

[tc,status] = sltest.testmanager.createTestForComponent(___,Name,Value) creates a test case or test harness for each component, with additional options specified by one or more Name,Value pair arguments. Specify name-value pair arguments after the test file, component, and top model input arguments.

example

Examples

collapse all

Open Live Script

This example shows how to create a baseline test case for the vdp model and save the inputs in an Excel file. A test harness is created automatically.

Note that this code uses the current folder as the ExcelFileLocation. To save the Excel file to another location, change the ExcelFileLocation value to a different writable folder.

vdp

tf = sltest.testmanager.TestFile('MyBaselineTestFile');

sltest.testmanager.createTestForComponent('TestFile',tf,...
   'Component','vdp',...
   'TestType','baseline',...
   'ExcelFileLocation','mybaseline_inputdata.xlsx');
Open Live Script

Create an equivalence (back-to-back) test case for the Controller component of the sltestNormalSILEquivalenceExample model.

load_system('sltestNormalSILEquivalenceExample'); 

tf = sltest.testmanager.TestFile('MyB2BTestFile');

sltest.testmanager.createTestForComponent("TestFile",tf,...
   "Component","sltestNormalSILEquivalenceExample/Controller",...
   "TestType","equivalence",...
   "Simulation1Mode","Normal",...
   "Simulation2Mode","Software-in-the-Loop (SIL)");
### Starting build procedure for: Controller
### Successful completion of build procedure for: Controller
### Creating SIL block ...
Building with 'gcc'.
MEX completed successfully.

Build Summary

Top model targets:

Model       Build Reason                                         Status                        Build Duration
=============================================================================================================
Controller  Information cache folder or artifacts were missing.  Code generated and compiled.  0h 0m 20.286s 

1 of 1 models built (0 models already up to date)
Build duration: 0h 0m 33.161s
Open Live Script

This example shows how to create a test case and test harness for a model component. It also shows how to use the HarnessOptions property. The test case uses only a component harness and is set up with no inputs or baseline strategy. To use this test case creation strategy, the UseComponentInputs property of createTestForComponent function must be false, and the SLDVTestGeneration property must be off. The HarnessSource property is ignored and the FunctionInterfaceName is deduced from the argument passed to createTestForComponent.

Once the test case is set up, you can specify the verification strategy for the component, such as importing test input data for the component into the created test case.

This code creates a test file and harness for the Contoller component of the f14 model. The HarnessOptions specify that the harness name is myHarness, a Signal Editor is used as the harness source, and the harness syncs with the model when the harness is opened.

f14

tcObj = sltest.testmanager.createTestForComponent(...
    'CreateTestFile',true,'TestFile','MyHarnessTest', ...
    'Component','f14/Controller','UseComponentInputs', ...
    false,'HarnessOptions',{'Name','myHarness', ...
    'Source','Signal Editor','SynchronizationMode', ...
    'SyncOnOpen'});
Open Live Script
load_system("sltestCruiseControl");
   
[result,status] = sltest.testmanager.createTestForComponent(...
    "CreateTestFile",true,...
    "TestFile","myTests.mldatx",...
    "TopModel","sltestCruiseControl",...
    "Component",[...
        "sltestCruiseControl/TargetSpeedThrottle",...
        "sltestCruiseControlMode/disableCaseDetection",...
        "sltestCruiseControl/DriverSwRequest",...
        "sltestCruiseControl"],...
    "CreateExcelFile",true);
Open Live Script

Create only test harnesses, not test cases, for multiple components of a model.

load_system('sltestCruiseControl');

[result, status] = sltest.testmanager.createTestForComponent(...
    'CreateTestFile',true,...
    'TestFile','myTests.mldatx',...
    'TopModel','sltestCruiseControl',...
    'Component',{...
        'sltestCruiseControl/TargetSpeedThrottle',...
        'sltestCruiseControlMode/disableCaseDetection',...
        'sltestCruiseControl/DriverSwRequest',...
        'sltestCruiseControl'},...
    'UseComponentInputs',false,...
    'HarnessOptions',{'SynchronizationMode','SyncOnOpen'});

Input Arguments

collapse all

Test file or test suite to which to add the test cases, specified as an sltest.testmanager.TestFile or sltest.testmanager.TestSuite object, string, or character vector. If CreateTestFile is false, the test file object must exist. If CreateTestFile is true, TestFile is the path of a new test file, specified as a string or character vector.

Example: 'TestFile','myTestFile'

Component or components for which to create test cases and harnesses. To specify a single component, use a Simulink.BlockPath object or a string scalar or character vector of the path to the component,. To specify more than one component, use an array of Simulink.BlockPath objects or a cell array of character vectors or an array of strings where each element is the path to the component. The components can be any block or block diagram in the hierarchy of the top model. You can specify a component multiple times to create multiple test cases and harnesses for that component. This input argument can be any model or block that is supported for test harness generation. See Test Harness and Model Relationship for a list of components for which you can build test harnesses.

Example: 'Component','sf_car/shift_logic'

Example: 'Component',{'sldvdemo/Controller','sldvdemo/Pi Controller'};

Model name at the top of the hierarchy, specified as a string or character vector. The top model is the name of the model whose hierarchy contains the components specified in the component input. You must specify the top model if your component input is an array with multiple components. Specifying the top model is optional if the component input is a single component. If the component input is a top model, do not use specify the TopModel.

Example: 'TopModel','Plant'

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'CreateTestFile',true

Whether to create a new test file, specified as the comma-separated pair consisting of 'CreateTestFile' and true or false.

Example: 'CreateTestFile',true

Test case type, specified as the comma-separated pair consisting of 'TestType' and 'baseline', 'equivalence', or 'simulation'.

Example: 'TestType','equivalence'

Whether to create a test harness for a model, specified as the comma-separated pair consisting of 'CreateHarness' and true or false. When component is not a top-level model or when you create multiple test cases and harnesses, this option is set to true automatically. When component is an export-function model and CreateHarness is true, the function creates a Test Sequence block in the generated test harness.

To generate only a test harness, set SLDVTestGeneration to off and UseComponentInputs to false. Optionally specify any desired HarnessOptions.

Example: 'CreateHarness',false

Option to simulate the model to obtain component inputs for the created test harness, specified as the comma-separated pair consisting of 'UseComponentInputs' and true or false. If this property is true, the test harness uses the inputs from the model simulation. If this property is false, the test harness does not use the component inputs from the simulation, and no input signal files or baseline criteria files are created.

Example: 'UseComponentInputs',false

Function interface, specified as the comma-separated pair consisting of 'FunctionInterface' and a string or character vector. Specify FunctionInterface to create tests for a reusable library subsystem. The subsystem must be at the top level of the subsystem library and must have a function interface. This property is not supported if component is an array or cell array.

Example: 'FunctionInterface','single'

Simulation mode for simulation 1 of an equivalence test, specified as the comma-separated pair consisting of 'Simulation1Mode' and either 'Normal' or 'Accelerator'. If you do not specify a simulation mode, the mode of the system under test is used. The required test harness is created automatically for the simulation mode.

Example: 'Simulation1Mode','Normal'

Simulation mode for simulation 2 of an equivalence test, specified as the comma-separated pair consisting of 'Simulation2Mode' and 'Normal', 'Accelerator', 'Rapid Accelerator', 'Software-in-the-Loop (SIL)', or 'Processor-in-the-Loop (PIL)'.. If you do not specify a simulation mode, the mode of the system under test is used. If TestType is 'equivalence' and Simulation2Mode is 'Software-in-the-Loop (SIL)', an extra test harness is created in addition to the test case and test harness, unless the component under test is an atomic subsystem. When equivalence testing an atomic subsystem using normal and SIL or PIL modes, a single test harness is created and used for both modes.

Example: 'Simulation2Mode','Software-in-the-Loop (SIL)'

File or directory path for storing logged inputs in a MAT-file, specified as the comma-separated pair consisting of 'InputsLocation' and a character vector or string. Include the file extension .mat. If component is an array or cell array, InputsLocation must be an existing directory path. If you do not specify InputsLocation, the function creates a folder in the current directory.

Example: 'InputsLocation','C:\MATLAB\inputs_data.mat'

File or directory path for storing baseline logged output data in a MAT-file, specified as the comma-separated pair consisting of 'BaselineLocation' and a character vector or string. Include the file extension .mat. If component is an array or cell array, BaselineLocation must be an existing directory path. If you do not specify BaselineLocation, the function creates a folder in the current directory.

Example: 'BaselineLocation','C:\MATLAB\baseline_data.mat'

Whether to use Excel® format for inputs and, for baseline tests only, outputs, specified as the comma-separated pair consisting of 'CreateExcelFile' and either true or false. If you use the 'ExcelFileLocation' argument to specify the filename and location, you do not need to also use 'CreateExcelFile'.

Example: 'CreateExcelFile',true

File path for the Excel file, specified as the comma-separated pair consisting of 'ExcelFileLocation' and a character vector or string. Include the file extension .xlsx in the filename. If component is an array or cell array, ExcelFileLocation must be an existing directory path. If you specify a location, you do not need to also use the 'CreateExcelFile' option. If you do not specify an ExcelFileLocation, the function creates a folder in the current directory.

Note

If SLDVTestGeneration is true and HarnessSource is 'Signal Editor', you cannot save data to an Excel file.

Example: 'ExcelFileLocation','C:\MATLAB\baseline_data.xlsx'

Name of Excel sheet in which to save data, specified as the comma-separated pair consisting of 'Sheet' and a character vector or string. If you are creating a single test case and harness and do not specify a Sheet, the default sheet is used. When creating multiple test cases and harnesses, if you do not specify a Sheet, a default Excel sheet name is used.

Example: 'Sheet','MySubsysTest'

Whether to generate tests using Simulink Design Verifier, specified as:

  • 'off' or false— Do not use Simulink Design Verifier to generate tests.

  • 'on' or true — Use Simulink Design Verifier to generate tests and use the Simulink Design Verifier options from the model configuration.

    'EnhancedMCDC' — Use Simulink Design Verifier to generate tests with the model coverage objectives as enhanced MCDC. The EnhancedMCDC option is valid only if TestType is 'equivalence' and Simulation2Mode is 'Software-in-the-Loop (SIL)' or 'Processor-in-the-Loop (PIL)'.

Note

To generate tests from Simulink Design Verifier, the system under test must be an atomic subsystem.

Example: 'SLDVTestGeneration','on'

Whether to simulate the top model during Simulink Design Verifier test generation, specified as a logical value. When the returned tests have model coverage lower than expected, after you analyze the possible causes and reconfigure the default simulation, set this property to true. Then, rerun Simulink Design Verifier test generation. If the coverage results are still lower than expected, you can iterate the analysis, simulation reconfiguration, and test generation.

Example: 'SimulateModelForSLDVTestGeneration','true'

Input source block for the test harness, specified as the comma-separated pair consisting of 'HarnessSource' and either 'Inport' or 'Signal Editor'. If you are not generating any test input data (UseComponentInputs is false), this property is not supported. Instead, specify the value inside the HarnessOptions cell as {'Source','Test Sequence'}.

Example: 'HarnessSource','Signal Editor'

Test harness creation options, specified as a cell array of comma-separated name-value pairs. See sltest.harness.create for valid options. Do not include the harnessOwner handle as the first argument in the cell array. The first argument is set automatically to the Component value.

Only specify HarnessOptions for either of these settings:

  • UseComponentInputs is false

  • SLDVTestGeneration is on or EnhancedMCDC)

If you are using Simulink Design Verifier and need to use an external harness, use HarnessOptions to set only SaveExternally to true. For this case, you cannot set other options at the same time.

Example: 'UseComponentInputs',false,'HarnessOptions',{'SynchronizationMode','SyncOnOpen','Source','Test Sequence','SeparateAssessment',true}

Example: 'SLDVTestGeneration','on','HarnessOptions',{'SaveExternally',true}

Output Arguments

collapse all

Test case, returned as an sltest.testmanager.TestCase object or a cell array of test case objects. If a test or harness creation fails when creating multiple test cases and harnesses, the cell array contains an MException or MSLException object with failure diagnostics. If component is an array or cell array and one test or harness creation fails, the function creates test cases and harnesses for other components even if one component.

Test case creation status, returned as an array of true and false values. true indicates that the test case was successfully created and false indicates that it failed.

Version History

Introduced in R2020b

expand all

See Also

| |

Topics