Basic Elements :: Working with the Basic Elements (SystemTest™)

Learn more about SystemTest

Basic Elements

On this page…
Introduction MATLAB Element Limit Check Element — General Check Limit Check Element — Tolerance Check IF Element General Plot Element Vector Plot Element Scalar Plot Element Stop Element Subsection Element

On this page…

Introduction

MATLAB Element

Limit Check Element — General Check

Limit Check Element — Tolerance Check

Introduction

The sections listed above describe how to work with the basic elements.

The Simulink element is covered in detail in Using the Simulink Element. The hardware elements are covered in detail in Introduction in Using the Image Acquisition Toolbox Element, Introduction in Using the Data Acquisition Toolbox Elements, and Introduction in Using the Instrument Control Toolbox Elements.

To see the MATLAB, Limit Check, and General Plot elements used in an example, see Adding Elements.

Tip You can rename any element or subsection by double-clicking its name in the Test Browser.

Invalid Characters in Element Names

The following characters are invalid to include within element names:

You cannot use these three characters in element names. If you create a new test element with one or more of these characters in the element name, then the SystemTest software throws an error dialog and the element name is reset to the default value, which is the name of the element type.

If you try to load an existing test with an invalid element name (containing one or more of the three characters listed above), the SystemTest software displays an error dialog indicating that the element name is invalid. The test will load successfully, but the element with an invalid name is reset to use the default name for the element. If this occurs, simply rename the element to a name that does not contain any of the invalid characters.

MATLAB Element

The MATLAB element lets you run MATLAB scripts from within a test. In addition to specifying any valid MATLAB script to execute, you can incorporate any test variable into your code, as well as access any variables residing in the MATLAB workspace.

Allowed Test Sections

The MATLAB element can be used in the following test sections:

Pre Test
Main Test
Post Test

Properties Pane

In the MATLAB Script edit field, enter any valid MATLAB script.

Limit Check Element — General Check

The General Check tab of the Limit Check element determines test conditions are met by using scalar, vector, or matrix comparisons. It can be used to:

Compare measured data to expected data.
Stop an iteration or an entire test if a test constraint is violated.
Assign a test variable the logical value derived from the comparison(s) for use by other elements.

You can do the following types of comparisons with the General Check tab of the Limit Check element:

Scalar versus scalar
Scalar versus vector
Vector versus vector
Matrix versus matrix

Note Use the Tolerance Check tab of the Limit Check element to test absolute and relative tolerance.

Allowed Test Sections

The Limit Check element can be used in the following test section:

Main Test

How to Use

Click the New button on the General Check tab to add a general limit check.
- Select an existing test variable or create a new one in the Test Variable column.
- Select an operator in the Operator column.
- Select an existing test variable or test vector or create a new one in the Limit column.
Set your test's passing conditions.
- The element can pass if all comparisons complete successfully (a logical AND).
- The element can pass if one or more of the comparisons complete successfully (a logical OR).
Set your fallback procedure if the element fails. You can:
- Allow the current iteration to continue executing.
- Stop the current iteration and proceed to the next iteration.
- Stop the test and proceed to Post Test.
Identify the SystemTest test variable you want to assign the logical value derived from the comparison(s) in the Assign data to field.

Note Aside from setting limit checks on individual elements, you can set these properties for the entire test, reachable by clicking the test name in the Test Browser, to determine pass/fail criteria for the test as a whole.

Properties Pane — General Check

You can set the following properties for the Limit Check element:

Test Variable — Value to compare to limit using operator.
Operator — Boolean operator used to compare test variable to limit.
Limit — Value to compare to test variable using operator.
For this element to pass — Choose between a logical AND (all comparisons must pass) or a logical OR (at least one comparison needs to pass) for the element to pass.
If this element fails — Choose between continuing the test, stopping the current iteration, or stopping the entire test.
Assign data to — Test variable assigned the logical value of this evaluation. The logical value will be 1 if the element passes or 0 if the element fails.

Limit Check Element — Tolerance Check

The Tolerance Check tab of the Limit Check element verifies test conditions are met by using absolute and relative tolerance comparisons. It can be used to:

Compare measured data to expected data.
Stop an iteration or an entire test if a test constraint is violated.
Assign a test variable the logical value derived from the comparison(s) for use by other elements.
Define pass/fail criteria for an iteration.

You can do the following types of comparisons with the Tolerance Check tab of the Limit Check element:

Absolute tolerance
Relative tolerance

For a definition of these tolerance types, see the Properties Pane section.

Note Use the General Check tab of the Limit Check element to test scalar, vector, and matrix comparisons.

Allowed Test Sections

The Limit Check element can be used in the following test section:

Main Test

How to Use

Click the New button on the Tolerance Check tab to add a tolerance limit check.
- Select an existing test variable or create a new one in the Test Variable column.
- Select an existing test variable or test vector or create a new one in the Expected Value column.
- Select Absolute or Relative in the Tolerance Type column.
- Select an existing test variable or test vector or create a new one in the Tolerance Limit column.
Set your test's passing conditions.
- The element can pass if all comparisons complete successfully (a logical AND).
- The element can pass if one or more of the comparisons complete successfully (a logical OR).
Set your fallback procedure if the element fails. You can:
- Allow the current iteration to continue executing.
- Stop the current iteration and proceed to the next iteration.
- Stop the test and proceed to Post Test.
Identify the SystemTest test variable you want to assign the logical value derived from the comparison(s) in the Assign data to field.

Properties Pane — Tolerance Check

You can set the following properties for the Limit Check element.

Test Variable — Variable to compare with expected value using a tolerance limit.
Expected Value — Expected value to compare variable to using a tolerance limit.
Tolerance Type — Tolerance type used to compare test variable to the expected value. Select Absolute or Relative. Absolute tolerance is calculated using this formula: abs(test variable - expected value) <= tolerance limit. Relative tolerance is calculated using this formula: abs(test variable - expected value) <= tolerance limit.* abs(expected value).
Tolerance Limit — Value used as the tolerance constraint to compare variable and expected value.
For this element to pass — Choose between a logical AND (all comparisons must pass) or a logical OR (at least one comparison needs to pass) for the element to pass.
If this element fails — Choose between continuing the test, stopping the current iteration, or stopping the entire test.
Assign data to: — Test variable assigned the logical value of this evaluation. The logical value will be 1 if the element passes or 0 if the element fails.

IF Element

The IF element provides logical control of a test by evaluating a condition.

The IF element allows sub-elements to run only when the IF element's condition evaluates to true. After adding an IF element, you should add one or more elements to perform a specific task.

Allowed Test Sections

The IF element can be used in the following test sections:

Pre Test
Main Test
Post Test

Properties Pane

You can set the following property for the IF element.

Condition — Enter a valid MATLAB expression that will evaluate to true or false.

General Plot Element

The General Plot element is used to plot any type of data over multiple iterations.

Use this element during the Main Test to generate plots of any test vectors or test variables containing any type of data.

Allowed Test Sections

The General Plot element can be used in the following test section:

Main Test

General Tab

To add a plot:

Click the Add Plot button to create a plot.
From the drop-down list, select one of the following:
- plot — A standard line plot that uses a 2-D line graph with linear axes.
- Simulink data — Lets you plot data produced from a Simulink model. The supported data types are such [time signal] array, a structure, a structure with time, or a time series. Note that the element creates a line for each signal in the Simulink data. If time is not present, the signals are plotted against their indices.
  You can also plot Simulink data provided by test vectors, such as the Signal Builder Block test vector, the Simulink Design Verifier Data File test vector, or the Spreadsheet Data test vector.
- bar — A standard bar plot that creates a bar graph.
- scatter — A standard scatter plot that creates a 2-D scatter graph displaying markers at x- and y-coordinates.
- contour — A standard line plot that creates a 3-D contour graph displaying isolines of a surface in a 3-D view.
- imagesc — An image plot with colormap scaling, which displays an image and scales it to use the full colormap.
- surf — A standard surface plot that creates a 3-D surface plot that displays a matrix as a surface.
- mesh — A standard surface plot that creates a 3-D mesh plot displaying a matrix as a wireframe surface.
- More plots — Opens the Choose Plot Type dialog box, which lets you choose any MATLAB plot. Select a plot type category in the Categories list to display the plot types from the Plot Types list. Select an individual plot type to read the Description.

Add Axes Button

You can have multiple axes in a plot figure. To add an axes, click the Add Axes button. Then click the Add Plot button to create the plot for that axes. Each axes is added as a subplot to the parent figure.

You can set properties for each axes individually by selecting the axes and then configuring properties in the Properties area. With the axes selected, you can configure the X and Y labels and add a title and legend. With the plot under the axes selected, you can configure the plot.

Properties

When the Figure node is selected or you have not yet added a plot, the Figure name field is displayed. Optionally use this text field to name the plot.

When you select a plot type and it is added to the tree, the Properties section displays the properties of that plot type. Fill in any parameters you want to set. For more information on the parameters, see the help in the Choose Plot Type dialog box when you select More Plots.

When you select an axes the axes properties are displayed. Use the X label and Y label fields to enter names for the X and Y axes. Use the Title field to enter a title for the plot. If you select the Include legend option, a legend is added to the plot. The legend is located in the least used space outside of the plot.

You can set other options for the General Plot element by clicking the Options tab.

Plotting Simulink Data

You can plot data produced from a Simulink model. The supported data types are such [time signal] array, a structure, a structure with time, or a time series. Note that the element creates a line for each signal in the Simulink data. If time is not present, the signals are plotted against their indices.

You can also plot Simulink data provided by test vectors, such as the Signal Builder Block test vector, the Simulink Design Verifier Data File test vector, or the Spreadsheet Data test vector.

The Simulink data types are plotted as follows:

For an array, it is plotted against its indices.
For a structure in the format generated by a Simulink Outport, its signal values are plotted against its indices.
For a structure with time in the format generated by a Simulink Outport, its signal values are plotted against its time.
For a structure with time in the format generated by the Signal Builder Block test vector, its signal values are plotted against its time.
For a Simulink.Timeseries object, the plot is determined by the plot() function of the Simulink.Timeseries object.

Options Tab

These options control the test behavior pertaining to plots.

The Each time the element executes option determines run-time behavior of the element.

Clear the figure of any previous iteration's data – Every time the element executes, the figure is cleared before plotting new data. This is the default.
Keep any existing data on the figure – Previous plots are not removed from the figure. New data is added to the same figure.

The If this test is generating a report option determines what happens to the snapshots of the plots that are created when each iteration runs.

Put a snapshot of the figure into the report each iteration – A snapshot of the plot is generated in each iteration and is displayed in its respective section of the report. This is the default.
Put a snapshot of the figure into the report at the end of the test – Only one snapshot of the plot is taken, at the end of the completed test run. It is displayed in the report section for Post Test.
Do not put any snapshots into the report – No snapshots of plots are added to the report.

Vector Plot Element

Note: The Vector Plot and Scalar Plot elements are being replaced by the General Plot element that was introduced in R2008b. The General Plot element supports all MATLAB plot types as well as Simulink data. Customers should no longer create new Vector Plot or Scalar Plot elements. For more information, see the R2009b section of the SystemTest Release Notes.

The Vector Plot element is used to plot array or vector data over multiple iterations.

Use this element during the Main Test to generate plots of any test variables containing array or vector data. You can change the number of iterations displayed to as many as 16 (in a 4-by-4 matrix) using the Subplot Dimensions fields. The default is one iteration.

Allowed Test Sections

The Vector Plot element can be used in the following test section:

Main Test

Plot Type

Choose one of the following plot types:

plot — Standard plot of X and Y.
semilogx — Semilogarithmic plot with logarithmic X-axis.
semilogy — Semilogarithmic plot with logarithmic Y-axis.
loglog — Log-log scale plot.
stem — Lines extending from a baseline along the X-axis.

Properties Pane

You can set the following properties for the Vector Plot element.

X Axis — Choose a test variable to use for an X-axis value.
Y Axis — Choose a test variable to use for a Y-axis value.
Line Color — Select a color to use for the line between each data point.
Line Style — Set the type of line to be drawn between each data point.
Line Marker — Choose a symbol to represent each data point.

Subplot Dimensions

Rows — The number of rows you want displayed in the Subplots window.
Columns — The number of columns you want displayed in the Subplots window.
Clear axes between iterations — Applies only when you have one row and one column to display. Selecting this option (default) rewrites the plot with new data during each iteration. Clearing this option adds new data to the plot during each iteration.

Scalar Plot Element

Note: The Scalar Plot and Vector Plot elements are being replaced by the General Plot element that was introduced in R2008b. The General Plot element supports all MATLAB plot types as well as Simulink data. Customers should no longer create new Scalar Plot or Vector Plot elements. For more information, see the R2009b section of the SystemTest Release Notes.

The Scalar Plot element is used to plot scalar data for each iteration.

Use this element during the Main Test to generate a plot of one or more scalar test variables.

Allowed Test Sections

The Scalar Plot element can be used in the following test section:

Main Test

Plot Type

Choose one of the following plot types:

plot — Standard plot of X and Y.
semilogx — Semilogarithmic plot with logarithmic X-axis.
semilogy — Semilogarithmic plot with logarithmic Y-axis.
loglog — Log-log scale plot.
stem — Lines extending from a baseline along the X-axis.

Properties Pane

You can set the following properties for the Scalar Plot element.

Maximum Number of Points to Display at Once — Determine how many points to show simultaneously. By default this is infinite such that all points will be plotted. Use a MATLAB numeric that evaluates to a positive, nonzero integer to set this field's value.
X Axis — Choose a test variable to use for an X-axis value.
Y Axis — Choose a test variable to use for a Y-axis value.
Line Color — Select a color to use for the line between each data point.
Line Style — Set the type of line to be drawn between each data point.
Line Marker — Choose a symbol to represent each data point.

Stop Element

The Stop element stops an iteration or an entire test unconditionally.

You can use the Stop element with conditional logic elements, such as the IF element, to control the test's execution.

Allowed Test Sections

The Stop element can be used in the following test sections:

Pre Test
Main Test

Properties Pane

You can set the following properties for the Stop element.

When this element runs — Select a stop action for use in Main Test. The Current iteration stops option stops the current Main Test iteration. The All testing stops option stops all Main Test iterations and runs Post Test.
Note that when a Stop element is used in Pre Test, All testing stops is the only option, since Pre Test does not have iterations.
Display Message — Enter a message to display in the Test Report.

Subsection Element

Use subsection elements to organize one or more elements to maintain readability of your test or to better manage complex test structures. Use a subsection to: