Using the NI TestStand Object Model

Publish Date: Oct 31, 2013

Overview
This document introduces the use of the NI TestStand object model, which contributes to the power and flexibility of TestStand. The TestStand object model is a collection of objects with specific
functionality. In other words, the TestStand object model is the object oriented interface to all TestStand capabilities. Most basic applications do not need to interact directly with the object model,
but when you understand how the internals of TestStand work, you gain a vision of what you can accomplish to quickly create advanced TestStand solutions.
The TestStand object model is a complex topic, and this document does not cover every aspect of the TestStand Engine. This document includes an overview of the TestStand architecture and
engine and information about the TestStand API, primarily the Engine, SequenceContext, and RunState objects.

Table of Contents
1. Overview of TestStand Architecture
2. The TestStand API
3. Commonly Used API Objects
4. Dynamically Creating and Running Sequences
5. Additional TestStand APIs
6. Conclusion
7. View Additional Sections of the NI TestStand Advanced Architecture Series
8. About the Authors

1. Overview of TestStand Architecture

In a test environment with rapid product cycles, varied devices, and multiple configurations, a well designed testing architecture provides immense value. You can reuse a generalized, adaptable
architecture on a range of test systems to extend the lifetime of the test system and to reduce test development costs. TestStand provides a comprehensive platform that includes a solid sequence
editor development environment and customizable user interfaces to simplify the development of test systems and corresponding tests. However, TestStand is more than just a test sequencer.
The real power of TestStand lies in its open architecture, which you can leverage to create complex and flexible test solutions. Figure 1 illustrates the basic TestStand architecture.

Figure 1 TestStand Architecture Overview

As Figure 1 shows, the TestStand Engine is the core of the TestStand architecture. Notice that other components of the architecture interact with and closely leverage the functionality of the
TestStand Engine. Almost all the functionality you can access through the sequence editor and user interfaces invokes a function in the engine.

TestStand provides a clear layered architecture with a separation between the presentation layer (what the user sees) and the business logic layer (the actions behind a user action). This
approach enables you to build complex solutions on top of the TestStand Engine and leverage all the functionality TestStand provides out of the box to create any type of test application you need,
including creating custom user interfaces, dynamically controlling the flow of tests, creating sequences on the fly, and developing other advanced solutions.

Conceptual Overview of the TestStand Engine

Understanding the TestStand Engine can help you leverage other important APIs in TestStand, such as the User Interface Controls and the sequence file translator framework.

The TestStand Engine is an ActiveX/COM automation server that exposes functionality through an API. Microsoft developed the ActiveX application communication standard to provide a method
of communication between applications. Widely used in the industry for many years, ActiveX is built on COM technologies. Because TestStand is built on COM, it will continue to work on future
versions of Windows operating systems even if ActiveX becomes obsolete.

ActiveX uses a client/server approach. An ActiveX server is an application that exposes specific functionality to clients that follow the ActiveX standard. In addition, ActiveX applications use a strict
Object Oriented Programming (OOP) approach. All objects in the automation server comply with the concepts of OOP, such as encapsulation, inheritance, abstraction, and polymorphism. Refer to
The TestStand API section of this document for more information about some of these concepts and how they relate to TestStand.

As an ActiveX server, the TestStand Engine uses methods and properties to expose functionality to any client that connects to the engine. The ActiveX server architecture allows any programming
language capable of invoking ActiveX code, such as LabVIEW, LabWindows/CVI, C#, VB .NET, C++, and so on, to interact with the TestStand Engine. For example, a user interface built in
LabVIEW acts as an ActiveX client and connects to the TestStand Engine to leverage the capabilities of the engine. By communicating with the TestStand Engine, the LabVIEW user interface
doesnt have to implement complex test execution routines. All the LabVIEW user interface needs to do is invoke the TestStand Engine and present the results of the invocations to the user.

2. The TestStand API

The TestStand API methods and properties provide access to the TestStand object model, which in turn includes numerous objects. This document explains only the basic structure of the object

1/8

www.ni.com

The TestStand API methods and properties provide access to the TestStand object model, which in turn includes numerous objects. This document explains only the basic structure of the object
model, including examples of how to use it. Refer to the NI TestStand Help and the NI TestStand API Reference Poster for detailed information about all the TestStand API objects, methods, and
properties.

Before continuing, it is important to understand the following components of an ActiveX server interface:
Class: A class defines a list of methods and properties you can use with respect to the objects you create as instances of the class. Classes are similar to data type definitions, but classes
apply to objects not variables.
Object: An object is a service an ActiveX server makes available to clients. A class is a definition of something. An object is an instance of that definition.
Method: Methods perform an operation or function on an object.
Property: Properties store and maintain settings or attributes of an object.

As mentioned previously, you can use any programming language that supports ActiveX/COM to access the TestStand API. The methodology to communicate with the TestStand API depends on
the language you use. For example, LabVIEW uses Property and Invoke Nodes to communicate with ActiveX/COM, LabWindows/CVI uses an instrument driver wrapper around API or
ActiveX/COM calls, and .NET languages call the TestStand API directly or use an interop assembly TestStand provides. TestStand itself provides an ActiveX/COM Adapter to access the API, and
you can also use expressions to access the API directly. Regardless of the way you access the API, the result is always the same because all environments access the exact same TestStand API.

Note: When you access the TestStand API directly from a development environment, make sure you close all references accordingly to avoid memory leaks and unexpected behavior that might
cause the application to crash. Refer to the Adding and Releasing References topic of the NI TestStand Help for more information about handling references in specific development environments.

API Inheritance
In OOP, inheritance refers to the ability to create a new class from a previously existing class. The new class, also called a derived class, inherits all the properties and methods of the original class
and makes these properties and methods available to use once the class is instantiated, or converted into an object. TestStand implements an inheritance model, as shown in Figure 2, which is
also available in the API Inheritance topic of the NI TestStand Help.

Figure 2 TestStand API Inheritance

As Figure 2 shows, almost all TestStand API classes inherit from the base PropertyObject class, which includes common methods and properties TestStand objects share. You can use
PropertyObject methods and properties on objects of other classes. Understanding that most objects in the TestStand object model inherit from a common class is crucial when you develop
applications using the TestStand API.

The PropertyObject class defines useful properties, such as Name and Numeric Format, and provides common methods for object management, such as cloning, setting and getting values,

2/8

www.ni.com

The PropertyObject class defines useful properties, such as Name and Numeric Format, and provides common methods for object management, such as cloning, setting and getting values,
creating and deleting objects, manipulating arrays, and so on. When you learn how to get the name of a PropertyObject, you also learn how to get the name of any object. Similarly, when you learn
how to set, get, clone, or delete a property object, you also learn how to perform the same task on any object that inherits from PropertyObject. For example, you can use the
PropertyObject.GetType method to get the type of a step, a sequence, or a sequence file.

Most development environments prevent you from accessing the properties of a parent class directly. Similarly, in TestStand you cannot obtain the type of a step by calling a Type property directly.
If you want to access the properties and methods of the PropertyObject part of any object, you first need to convert the object into its parent class by calling the AsPropertyObject method on any
object that inherits from the PropertyObject class. Calling this method returns the PropertyObject version of that object so you can access the corresponding properties and methods. For example,
calling myType = Step.AsPropertyObject.GetType works correctly, but calling myType = Step.Type does not. Using this approach, you can write one code module to programmatically examine the
type of any object and execute specific functionality based on the type the GetType method returns. The objects that inherit from the PropertyObject all include features available from the
PropertyObject class. Refer to the NI TestStand Help for more information about the API inheritance and the PropertyObject class properties and methods.

API Containment
In the TestStand API, many objects contain other types of objects. For example, a SequenceFile object contains Sequence objects. Sequence objects, in turn, contain Step objects. Figure 3, which
is also available in the API Containment topic of the NI TestStand Help, shows the containment relationship among some objects in the TestStand API.

Figure 3 TestStand API Containment

Understanding the concept of containment provides you with a guide for navigating specific objects to leverage the TestStand API. You can also think of containment as using arrays in a
development language. For example, using an array analogy, a SequenceFile object contains an array of Sequence objects. Each element of the array includes one particular sequence, and each
sequence is an array of Step objects. The following example shows how you can obtain the value of the myNumber variable, which is buried inside the myContainer object:

myValue = myContainer.GetNthSubProperty(4).GetValNumber

The previous example assumes you know the exact index of the object you are trying to retrieve, which might not be the case. You can also retrieve the information by searching for the specific
name if you do not know the indexes, as shown in the following example:

count = myContainer.GetNumSubProperties
Loop until, myContainer.GetNthSubProperty(i).name == myNumber
myValue = myContainer.GetNthSubProperty(i).GetValNumber

You can also use this expression in a development environment, and you can uncover valuable information associated with each object by converting it into a PropertyObject. As shown in the
previous examples, you can retrieve the number of elements inside a container and then create a loop to iterate through the container to obtain information about each element. You can apply this
same strategy to any TestStand object that inherits from the PropertyObject class after you use the AsPropertyObject method to convert the object to a PropertyObject . As these examples show,
you can programmatically manipulate TestStand API objects, which provides significant flexibility.

Navigating through TestStand API Objects

As the previous section explains, navigating objects is a useful way to obtain information. Sometimes though, the information you need is not readily available or is not accessible from the current
object. However, when you understand the relationships among TestStand API objects, you can navigate to most of the objects in memory at any time. Figure 4, which is also available in the
Referencing TestStand API Objects topic of the NI TestStand Help, shows the relationship among many TestStand objects. Color represents items that are duplicated. Notice how you can obtain a
reference to any object as long as you know the correct path to the object.

3/8

www.ni.com

Figure 4 TestStand API Object Relationships

The following example shows you how to navigate the object model to obtain information. Assume you receive a UIMessage, and you need to know the name of the sequence that posted that
message so you can update the GUI accordingly. Based on Figure 4 , the path to the sequence, starting on the UIMessage object, is UIMessage>>Execution>>Thread>>Sequence
Context>>Sequence.

This example does not use the exact syntax to access the object but instead shows you how the objects are related. Refer to the NI TestStand Help to determine the appropriate method or
property to call for each object. The following pseudocode shows the actual methods and properties to call to access the object:

myExecution = UIMessage.Execution
mySeqContext = myThread.GetSequenceContext (callStackIndex, frameId)
mySequence = mySeqContext.Sequence
mySequenceName = mySequence.AsPropertyObject.Name

Refer to the NI TestStand Help for more information about navigating API objects.

3. Commonly Used API Objects

The TestStand API contains numerous objects and hundreds of properties and methods. It might seem like a daunting task at first to become familiar with the TestStand API. However, once you
understand the basics of the technologies the API uses, such as OOP, containment, and inheritance from your programming language of choice, you can become familiar with commonly used
objects, such as the PropertyObject and the commonly used objects the following sections include.

Engine Object
The TestStand Engine is the core of the TestStand architecture and provides many of the methods and properties you need to run tests. You must instantiate the TestStand Engine, which is a

4/8

www.ni.com

The TestStand Engine is the core of the TestStand architecture and provides many of the methods and properties you need to run tests. You must instantiate the TestStand Engine, which is a
per-process singleton, to perform any TestStand functions. The engine holds references to all in-memory objects, sets up and controls executions, and stores the context data for a TestStand
session as well as station globals and user information. Using the engine, you can create and manage all high level objects.

The engine includes numerous properties, such as Engine.ComputerName, Engine.CurrentUser, Engine.Globals, and Engine.LicenseType. A few of the most commonly used methods include
Engine.NewStep, Engine.NewSequence, Engine.NewSequenceFile, Engine.NewPropertyObject, Engine.NewExecution, and Engine.CurrentUserHasPriviledge.

You can also use the engine to launch dialog boxes. TestStand provides numerous dialog boxes that can help you develop applications. In fact, the sequence editor launches many of these dialog
boxes directly from the TestStand Engine. Some example display methods include Engine.DisplsyEditUserDialog, Engine. DisplayBreakpointDialog, and Engine.DisplayHelpFile.

As explained previously these examples are small subsets of the properties and methods of the TestStand Engine object. Refer to the NI TestStand Help for more information about the TestStand
objects, methods, and properties.

The ApplicationManager object can handle most of the tasks this section explains, such as instantiating the TestStand engine, loading files, launching executions, and logging in users because the
ApplicationManager encapsulates all the engine initialization and shut down routines. Use the ApplicationManager to perform basic operations for using the TestStand Engine in your application.
Learning to interact with the ApplicationManager and leverage the TestStand UI Controls can help you become a better TestStand developer.

SequenceContext Object
The SequenceContext object is one of the most widely used objects in the TestStand API because it represents the execution state of a sequence, like a run-time snapshot of all the data inside a
particular executing sequence. The SequenceContext object holds the context, or state, of a particular sequence at a specific point in time. Each executing sequence has its own
SequenceContext. Thus, if you run four sequences in parallel, at least four SequenceContext objects are available.

The SequenceContext is a key element to understand because using the SequenceContext, you can access all the information inside a sequence, including all its objects, variables, and
properties. Refer to Figure 4, TestStand API Object Relationships, and notice that the SequenceContext is the root of the tree. Furthermore, the SequenceContext provides references to many of
the main objects currently loaded into memory. Additionally, you can use the SequenceContext directly within the TestStand environment or you can pass the current sequence context or its
subproperties to code modules you call from steps.

The SequenceContext object includes various levels or properties. Table 1, which is also available in the Sequence Context First-Level Properties topic of the NI TestStand Help, shows the first
level of SequenceContext properties.

Table 1 First-Level SequenceContext Properties

Sequence Context Subproperty

Description

Locals

Run-time copy of the sequence local variables for the current sequence invocation.

Parameters

Run-time copy of the sequence parameters for the current sequence invocation.

FileGlobals

Run-time copy of the sequence file global variables for the current execution.

StationGlobals

Contains the station global variables for the engine invocation. TestStand maintains a single copy of the station globals in memory.

ThisContext

Holds a reference to the current sequence context. Usually, you use this property to pass the entire sequence context as an argument to a
subsequence or a step module

RunState

Contains properties that describe the state of execution in the sequence invocation.

Step

Run-time copy of the properties in the currently executing step of the current sequence invocation. The Step property only exists while a step executes.
The property does not exist when the execution is between steps, such as at a breakpoint.

When you study the properties and methods of the SequenceContext object, you can see that you can gather useful information from this object. For example, you can get a reference to the
currently executing step, the thread, the StepGroup, and so on. You can also retrieve the step index and set the next step index if you want to change the execution flow programmatically. Figure
5, which is also available in the Sequence Context topic of the NI TestStand Help, shows an example SequenceContext. The dots in the graphic indicate that each column is a continuation of the
column to the left.

5/8

www.ni.com

Figure 5 Sequence Context Example

Any changes you make to the SequenceContext object during runtime are lost when the execution of the sequence completes. For example, if at runtime you programmatically create a new Local
variable and insert it into the Locals container of a particular sequence, this new variable is valid and accessible while the sequence is running. Once the execution completes, that change is lost.
Use this technique when you want to create temporary data that needs to exist only at runtime. If you want the changes to persist, make the changes to persistable objects, such as the
SequenceFile or Globals objects.

One exception to this rule is the PropertyObjectFile class, which you can use to change a sequence file and save the changes to disk to persist the changes after the execution completes.

Refer to the NI TestStand Help for more information about the SequenceContext object methods and properties.

RunState Subproperty
The RunState object is a SequenceContext object subproperty that contains properties to describe the run-time state of execution in the sequence invocation. Some of the properties inside the
RunState object are available only at runtime. Figure 6 shows a SequenceContext RunState object in the TestStand Sequence Editor.

Figure 6 - RunState

Refer to the RunState in TestStand on-demand training module for more information about the RunState subproperty.

4. Dynamically Creating and Running Sequences

The TestStand Sequence Editor is a common application for creating and running test sequences. For users, the sequence editor appears to directly provide all the functionality needed to create
sequences. But in reality, the sequence editor is part of the presentation layer that sits on top of the TestStand Engine. When a user clicks the New Sequence File button, right-clicks the
sequence to insert steps, or saves a sequence file, the sequence editor invokes the corresponding engine methods and properties and presents the results in an organized way.

Separating the GUI from the engine enables you to create additional ways for creating, editing, and executing sequences. For example, the customizable user interface that TestStand provides
includes functionality similar to the sequence editor but in a different context. Test developers and engineers need all the functionality of the sequence editor, but users on a manufacturing floor
only need to execute sequences and view reports. Understanding how to expose only the functionality end users need can help you build a user interface to meet those needs. Exposing a
feature-rich interface to operators might not be the ideal solution. Some users need a simplistic interface that sits on top of the functionality that dynamically creates and executes sequences.

6/8

www.ni.com

The following example illustrates the concept of dynamically creating sequences by providing an oversimplified list of the API objects the sequence editor calls when it creates a new sequence file.
Assume you need to create a TestFile sequence file that includes a TestSeq sequence that includes a TestStep step, as shown in the sequence editor in Figure 7.

Figure 7 Image of example Sequence File TestFile

To accomplish this task, you need to be familiar with the following objects:
Engine
SequenceFile
Sequence
Step
PropertyObject

The following pseudocode shows an example of the methods and properties you need to call to dynamically create the sequence file in Figure 7:

myStep = Runstate.Engine.NewStep (adapterKeyNameVal, stepTypeName)

myStep.Name = TestStep
mySequence = Runstate.Engine.NewSequence
mySequence.Name = TestSeq
mySequence.InsertStep (myStep , index, stepGroupParam)
mySequenceFile = Runstate.Engine.NewSequenceFile
mySequenceFile.InsertSequenceEx (index, sequenceToInsert)
mySequenceFile.Save (pathString)

You can also use the SequenceView and SequenceFileViewManager user interface controls to create the sequence file. The TestStand UI Controls are designed to handle common user actions.
Refer to the NI TestStand Help for more information about the user interface controls.

5. Additional TestStand APIs

Using the flexibility of the TestStand architecture, you can create enhancements to the TestStand user experience. In earlier versions of TestStand, you had to manually code user interfaces,
which required an in-depth knowledge of the TestStand API and strong programming skills to perform even the simplest of tasks. More recent versions of TestStand include a set of user interface
controls that can ease the complexity of developing a TestStand solution.

You can think of the TestStand UI Controls as a layer of software on top of the TestStand Engine API. These controls encapsulate many of the features you need in a user interface, such as
opening sequences, running tests, displaying test progress, and so on. The TestStand UI Controls are feature rich and include their own API. Although covering the functionality of the user
interface controls is outside the scope of this document, it is important to mention that these controls provide functionality based on top of the TestStand Engine API.

Other APIs available in TestStand include the Synchronization Server API, the Adapter API, and the Sequence File Translator API. Refer to the NI TestStand Help for more information about these
APIs.

6. Conclusion
A key feature of TestStand is its modular and open architecture. By using the TestStand API to access the engine, you can create and customize solutions that satisfy even the toughest of
requirements.

7. View Additional Sections of the NI TestStand Advanced Architecture Series

Click to view additional documents within the NI TestStand Advanced Architecture Series covering topics of interest to advanced NI TestStand developers

8. About the Authors

Daniel Elizalde - VI Technology
Daniel Elizalde, Product Development Manager, has been with VI Technology in Austin, Texas, since 2006. Daniel graduated from ITESM Mexico City with a BS degree in Electrical Engineering.
Before joining VI Technology, he worked as a Senior Systems Engineer at National Instruments, where he served as a TestStand consultant for many Fortune 500 companies. Daniel is a Certified
TestStand Architect and a Project Management Professional.

Albert DeWeese - VI Technology

Albert DeWeese, Staff Systems Engineer, has been with VI Technology since 2006. Albert graduated from the University of Colorado at Boulder with a BA in Physics. Albert has leveraged
LabVIEW, TestStand, and National Instruments hardware to design test platforms for customers across many different industries. Albert is a Certified LabVIEW Architect.
Special thanks to Daniel Honegger from VI Technology for his efforts toward this paper.

7/8

www.ni.com

8/8

www.ni.com