This topic explains how to step through C++test test cases with a debugger to better examine the code's internal state during a given test. For example, you might want to debug test cases to learn more about how C++test obtained an unexpected outcome, or to determine why a test case failed. You do not need to manually add breakpoints to the code. C++test will automatically set the breakpoints at the beginning of each test case that you select for execution.You can execute tests with your compiler’s debugger, or debug directly in the Eclipse IDE (according to an Eclipse Debug Configuration you have configured).

Sections include:

Configuring Debugger Settings

C++test can be configured for two different modes of test cases debugging:

• Debugging internally in the IDE (Eclipse/VisualStudio)
• Debugging with external debugger

To enable debugging inside Eclipse IDE 

1. Open test configuration you use for running test cases
2. Choose the Execution> Runtime tabs
3. In the Test cases debugging section, enable the Run tests in debugger(*) option.
4. Make sure the Use Eclipse internal debugger with configuration option is selected and choose an Eclipse Debug Configuration from the drop-down menu.

In this mode C++test will use selected Eclipse Debug configuration to automate test exectable execution and entering the debugging mode inside IDE. For more details see Debugging in Eclipse Internal Debugger Mode.

To enable debugging with external debugger:

1. Open test configuration you use for running test cases
2. Choose the Execution> Runtime tabs.
3. In the Test cases debugging section, enable the Run tests in debugger(*) option.

4. Enable the Use External debugger option.

In this mode some further configuration may be required depending on development environment. See Debugging Using External Debugger, mode for additional details. 

Debugging in Eclipse Internal Debugger Mode

Preparing Eclipse Debug Configuration

You can use any of your existing Eclipse Debug configurations for test cases debugging. If you don't have a working Eclipse Debug configuration you will need to first prepare a configuration. For details on configuring Eclipse Debug configuration please refer to your development environment documentation.

It is recommended to verify that your Eclipse Debug configuration can be used for debugging your original project code before specifying it in C++test test configuration.    

Using Selected Eclipse Debug Configuration

1. Open test configuration you use for running test cases
2. Choose the Execution> Runtime tabs
3. Make sure the Use Eclipse internal debugger with configuration option is selected and choose an Eclipse Debug Configuration from the drop-down menu. You may need to click Refresh to reload the names of existing Eclipse Debug configuration.

Executing Tests with a Debugger

This section covers debugging tests in native development environments. For information about debugging tests in embedded environments see Debugging Test Cases.

To execute a test withyour compiler’s

debugger:

1. Prepare a "Debug Unit Tests" Test Configuration.
   • Either use the built-in "Debug Unit Tests" Test Configuration or develop a custom Test Configuration by duplicating the built-in configuration and customizing it as described in the Configuring Test Configurations and Rules for Policies.
2. Run your preferred "Debug Unit Tests" Test Configuration as follows:
   
   1. Select test case(s) that you want to debug in one of the following ways:
      • Select the test case in the Test Case Explorer.

      • Select the test case function name in the code editor.

      • Select the test case function in the Project Explorer (not available for CDT 4.x+ Managed C/C++ projects).

   2. Launch your preferred "Debug Unit Tests" Test Configuration. For example, right-click the selection, then use the Parasoft shortcut menu to run the preferred Test Configuration. C++test will then launch appropriate debugger and automatically set the break-points at the beginning of each selected test case function.

      Debugging in Microsoft Visual Studio

      When using Microsoft Visual Studio 6 as the debugger environment, perform the following steps after the Visual Studio GUI opens:

      • Select the test process in the Attach to Process dialog and click OK.
      • Click Break Execution  (or choose Debug> Break from the menu bar).
      • Press the F5  (Go) button. The debugger will break at the beginning of the test case function.

      When using Microsoft Visual Studio 2003 with Service Pack 1 as the debugger environment, perform the following steps after the Visual Studio GUI opens:

      • Select the test process in the Processes dialog and click Attach.
      • Confirm the application type (Native) by clicking OK in the Attach to Process dialog.
      • Close the Processes dialog.

      For other versions of Microsoft Visual Studio, no extra steps are needed.

3. Use standard debugger features to step through the test case.

   • Before you use your debugger with C++test, ensure that your debugger executable is included in the $PATH environmental variable.

   • The debugger will be activated only if the debugging Test Configuration is run on a selection of one or more test cases. Otherwise, the following warning will appear in the console output and the execution will continue without debugging:
     Warning: debugger will not be activated - no valid breakpoints found. Select (test case) function definitions to set breakpoints.

   Use the Standard Create Process Launcher

   
   For the debug configurations, we recommend using the Standard Create Process Launcher (modified via Windows> Preferences> Run/Debug> Default Launchers) because this allows you to select a debugger. The default Eclipse launcher (GDB DSF) Create Process Launcher does not provide this option.