This topic explains how to configure and run unit testing on code that is designed to be compiled/built using Wind River Tornado compilers and/or written with the aid of Wind River Tornado IDE.

In this section:

About Unit Testing

The term "unit testing" encompasses everything related to building and running test objects. Before you perform unit testing, it is helpful to familiarize yourself with the following C++test terms/features:

Because VxWorks test objects/relocatables are linked with the -r option, the existence of symbol (function/variable) definitions is not checked, so any symbol resolution errors that occur will not be reported during linking. As a result, you won’t know if you forgot to define these definitions, or made a scope mistake that prevented their inclusion—until the execution phase, when the test object crashes. To receive advance warning about such problems, ensure that the Test Configuration you use for unit testing has the Perform early check for potential linker problems option enabled (in the Execution> Symbols tab) and that it is configured to use the generated external VxWorks image symbols list(as described in Providing an External List of Library Symbols).

You must have all project settings set properly in order to perform unit testing successfully (for details on settings, see Setting Target/Platform Dependent Options).  

The following sections in this topic explain how to build the C++test Runtime library (in case you want do this manually for additional control/customization), describe how to generate an external symbols list from your VxWorks image, remind you what Tornado tools must be up and running before you can actually execute your test object, familiarize you with Test Configurations designed specially for Tornado testing, and explain how customization of the test flow allows you to adjust the test object as needed to suit the circumstances of embedded testing. 

For more information on unit testing, see Test Creation and Execution

Understanding and Building the Runtime Library

To learn about the runtime library, see Working with the C++test Runtime Library

Example: Building the Runtime Library for Tornado with VxWorks

To build the runtime library with Tornado tools and for the VxWorks OS (assuming that you have the required Tornado environment variables set correctly - see Prerequisites):

  1. Go to the Runtime Library sources root directory (C++test_install_dir/engine/runtime).
  2. Enter the command
    make TARGET_CFG:=
    followed by either or
    (depending on your Tornado/VxWorks version).

You can also specify the following variables on the command line:

Example: Using the Provided Tornado Project/Workspace

To build the runtime library from the Tornado project or workspace provided with C++test:

  1. Go to C++test_install_dir/engine/runtime/projects.
  2. Open the appropriate project or workspace. Choose from the ones in Tornado2_0 or Tornado2_2, depending on your Tornado/VxWorks version.
  3. Build the opened C++testRtLib project.

You can copy and edit any .mk target configuration available in C++test_install_dir/engine/runtime/target and provide it for the TARGET_CFG argument. You can also add other Build Targets to Tornado projects to adjust building options and/or change targets. 

Generating an External VxWorks Image Symbols List

An external symbols list is required to build the VxWorks test object using Test Configuration that have the Perform early check for potential linker problems option enabled—for example, all built-in Tornado-related Test Configurations. The list should contain all symbols defined in the VxWorks kernel image that you use for running your applications.

You can generate this list as follows:

  1. Ensure that you have the required Tornado environment variables set correctly - see Prerequisites.
  2. Duplicate the built-in "Embedded Systems> Wind River> Extract Symbols from VxWorks Image" Test Configuration.
  3. Open the Execution tab.
  4. Adjust the Symbols listing tool name Test Flow property to match the name of the symbols dumping tool suited for the compiler used to create the image—e.g., nmsimpc (for ccsimpc)
  5. Adjust Symbols listing options if needed
  6. Set the Path to a VxWorks image to scan for symbols Test Flow property to the path to your VxWorks image—e.g., "%WIND_BASE%\target\config\simpc\vxWorks"
  7. Run the adjusted configuration

For more information on external symbol lists, see Providing an External List of Library Symbols.

Executing Test Objects

When we refer to the term "test object" in this section of the user’s guide, we mean the final artifact that is produced from your source files and the test suites, and which must be executed to collect runtime data (such as test case results and coverage data). However in other parts of the C++test User’s Guide, the term "test executable" is used instead. We make this distinction when discussing embedded development because embedded systems don't always support "executables"—the type of binary files that can be called application images, and can be loaded (unpacked) and executed by the system itself. For example, in the case of VxWorks 5.4 and VxWorks 5.5, you can build a full system image that links in your application procedure—or you can build  an incomplete relocatable object that contains symbols from only your application and is linked against a prebuilt system's image at a later time. 

In the case of Tornado testing for VxWorks, C++test will try to build the second type of objects, which can be best described as "test relocatables," and run them using an original Tornado tool called Tornado Shell (windsh). You will need to have the Tornado Registry (wtxregd) and Target Server (tgtsvr) up and connected with a target running VxWorks prior to launching the runtime testing (see Prerequisites).

For example, to prepare the testing environment to test on a VxWorks simulator (assuming you have the required Tornado environment variables set correctly - see Prerequisites) you can use the original Tornado interface or the following example steps/commands: 

  1. Set the WIND_UID environment variable to your UID. For more information on WIND_UID, see the Tornado User’s Guide.
  2. Launch the Tornado Registry.
    wtxregd & '
  3. Launch VxSim.
    "%WIND_BASE%\target\config\simpc\vxWorks" &

  4. Launch Target Server.
    tgtsvr vxsim -B wdbpipe -R "C:\Temp" -RW &

The default Tornado-shipped version of VxSim has preconfigured support for the Pass Through File System (PassFS) and Target Server File System (TSFS). This support, plus the above setup, enables the test object to be linked against the default version of the Runtime library with file communication (see Understanding and Building the Runtime Library) and to use one of the File Systems for transferring results. 

For more information on Tornado tools and VxWorks, refer to the Tornado manual. 

Understanding the Tornado Test Configurations

There are several Test Configurations designed specifically to work with Tornado projects:

All are available in the Embedded Systems> Wind River> Tornado category. 

These Test Configurations are all based on the following specially-designed Test Flow Recipes (see Customizing Test Configurations through Test Flow Recipes): 

Here are short explanations of the terms used in the above Test Configurations and Test Flow recipes. 

Other builtin Test Configurations you may need are:

If you need to build a customized VxWorks/VxSim version to suit your needs (e.g., for C++ code, TSFS, network), refer to the Tornado manual for instructions. 

For more information on Test Configurations, see Configuring Test Configurations and Rules for Policies

Customizing Test Configurations through Test Flow Recipes 

It’s important for embedded developers to become familiar with the flow of unit testing processing and the chaining of tools that C++test applies to the source code. This understanding is crucial for building a robust process that behaves exactly as you expect. 

Much of the flow always remains the same across different environments. In most cases, the order and parameters of flow steps shouldn't be altered. However, in certain situations, some critical steps must be adjusted. You can configure test execution flow parameters to suit your specific needs by using an editor in the Test Configuration manager. Usually, there is no need to create a custom version of the execution flow because built-in Test Configurations allow easy editing of the most critical and commonly-modified flow properties. 

For details on how to customize the test flow, see Customizing the Test Execution Flow.

In rare cases, more advanced customizations may be needed. In such cases, you can define a custom test flow as described in Defining a Custom Test Execution Flow: Advanced. If you need to do this, here are some tips and suggestions:

Debugging Test Cases

C++test does not support direct Test Cases debugging for this environment.

Load Test Executable to target kernel using 'hostShell' and set breakpoints on wanted Test Cases manually.