Tracing Events and Exceptions With Debug Services

Applies to TestComplete 14.40, last modified on April 22, 2021
Information in this topic applies to desktop applications only.

To trace exceptions that occur in tested applications, you can use the Debug run mode or the DbgServices scripting object. This topic describes how you can use these features:

Overview

TestComplete includes the DbgServices plugin that adds the DbgServices program object to the TestComplete object mode and provides support for the tested applications’ Debug run mode. When an application is running in Debug mode or when it is launched with methods of the DbgServices object, TestComplete receives notifications about various debug events that occur in the tested application: exceptions, debug strings, module loads and unloads, thread creation and others (see List of Traced Events).

The events are posted to the log as messages. Detailed event information (for instance, the call stack of exceptions) is visible in the Details pane when an event is selected in the test log:

Call stack in the Details panel

Click the image to enlarge it.

The tracing behavior is controlled by two options located in the DbgServices Options dialog: Enable events and Priority. The Enable events setting turns event tracing on or off. Priority sets the priority attached to the messages posted to the test log for each application event. You can choose a priority level that will distinguish event messages from other messages.

You can also control these options through properties of the DbgServices.Options program object.

To enable exception tracing, activate the Exceptions | Active option.

Using the Exceptions | Depth shown option, you can specify the stack depth (that is, the number of routines TestComplete will show in the stack).

In order for TestComplete to be able to display function names and source code lines in the call stack, the application under test must be compiled with debug information. For more information on how to do this, see the documentation on the development tool that is used to create the tested modules.

Note that in some cases, the location of reported exceptions in the test log may differ from what you expect. Suppose an exception occurred within the OnClick handling routine of a button. When TestComplete simulates mouse clicks, it waits to ensure that the click has been performed and then posts an appropriate event message to the log. Due to some specifics of communication between the application under test and TestComplete, the latter may receive exception notifications after it has posted the event message to the log. In other words, the exception message may be before or after the event message that informs you on a mouse click.

Using the Debug Run Mode

To trace exceptions in an application, you can add this application to the Tested Applications list of your TestComplete project and then run this application in Debug mode:

  • Add your tested application to the Tested Applications list. See Adding and Removing Project Items and Their Child Elements for more information on how to do this.

  • Right-click the TestedApps node in the Project Explorer and select Edit from the context menu to open the Tested Applications editor.

  • Select your application in the editor.

  • Choose Debug in the Run Mode drop-down list shown in the Basic Parameters section of the editor.

  • TestComplete will automatically update the Run-Mode Parameters section of the editor according to the selected mode. You can now use this section for selecting command-line arguments and the working folder for the run.

  • Save the changes made to the tested application settings by selecting File | Save from the TestComplete main menu.

Now, when you command TestComplete to launch your application, TestComplete will run the application and act as a debugger for it. This behavior does not depend on whether you start the application from a keyword test, script or through the TestComplete user interface. Note, however, that when you launch the tested application with Debug mode selected, TestComplete will ignore the Count property of the application. It always launches one new application instance.

You can also activate the Debug run mode and set up run-mode parameters from scripts. To do this, use the TestedApp.Params.DebugParams object. The following code snippet demonstrates how you specify the run-mode parameters and active the mode from scripts:

JavaScript, JScript

var MyApp;
  
// Obtains the tested application
MyApp = TestedApps.MyTestedApp;
  
// Specifies the run mode parameters
MyApp.Params.DebugParams.CommandLineParameters = "-t -e";
MyApp.Params.DebugParams.WorkFolder = "C:\\MyFolder";
  
// Activates the Debug run mode
MyApp.Params.DebugParams.Activate();
  
...

Python

# Obtains the tested application
MyApp = TestedApps.MyTestedApp
  
# Specifies the run mode parameters
MyApp.Params.DebugParams.CommandLineParameters = "-t -e"
MyApp.Params.DebugParams.WorkFolder = "C:\\MyFolder"
  
# Activates the Debug run mode
MyApp.Params.DebugParams.Activate()
  
...

VBScript

' Obtains the tested application
Set MyApp = TestedApps.MyTestedApp
  
' Specifies the run mode parameters
MyApp.Params.DebugParams.CommandLineParameters = "-t -e"
MyApp.Params.DebugParams.WorkFolder = "C:\MyFolder"
  
' Activates the Debug run mode
MyApp.Params.DebugParams.Activate
...

DelphiScript

var
  MyApp : OleVariant;
begin
  // Obtains the tested application
  MyApp := TestedApps.MyTestedApp;
  
  // Specifies the run mode parameters
  MyApp.Params.DebugParams.CommandLineParameters := '-t -e';
  MyApp.Params.DebugParams.WorkFolder := 'C:\MyFolder';

  
  // Activates the Debug run mode
  MyApp.Params.DebugParams.Activate;
  ...
end;

C++Script, C#Script

var MyApp;
 
// Obtains the tested application
MyApp = TestedApps["MyTestedApp"];
  
// Specifies the run mode parameters
MyApp["Params"]["DebugParams"]["CommandLineParameters"] = "-t -e";
MyApp["Params"]["DebugParams"]["WorkFolder"] = "C:\\MyFolder";
  
// Activates the Debug run mode
MyApp["Params"]["DebugParams"]["Activate"]();
...

Using the DbgServices Object

The DbgServices object is only available if the DbgServices plugin is installed. Using methods of this object, you can run the desired application in Debug mode or attach TestComplete to a running process (after TestComplete is attached to the process, it will be able to trace the events and exceptions that occur in this process):

Method Description
LaunchTestedApplication
LaunchAllTestedApplications
Runs one or all tested applications under the debugger. These methods run applications that are included in the project’s list of tested applications.
LaunchApplication Launches the application specified by its path and name.
AttachToProcess Attaches the DbgServices plugin to an unmanaged process running in the operating system.

Using this object’s methods is an analogue to using the Debug run mode. However, as you can see, the object offers the following benefits:

  • It supports running of any applications, not only applications included in the tested applications list of your project.

  • It lets you attach to a process running in the operating system and monitor events in it.

  • If you specify the RunAs mode for a tested application and then launch this application using the LaunchTestedApplication or LaunchAllTestedApplications method, TestComplete will launch the application under the specified user account in debug mode (that is, you can debug an application running under another account).

List of Traced Events

The Debug Services plugin provides TestComplete with the ability to trace the following debug events that occur in the tested application:

Event Type Description
Create process Message The application under test created a new process.
Create thread Message The application started a new thread.
Exception Error An exception occurred in the application under test. If the application was compiled with debug information, the Details panel of the Test Log panel will display a call stack for the exception. The DbgServices plugin includes several options that have effect when exception tracing (see below).
Exit process Message The process ended.
Exit thread Message The application finished a thread.
Load DLL Message The application loaded a dynamic link library (DLL).
Unload DLL Message The application unloaded a DLL.
Output debug string Message The application sent the specified string to the debugger using the OutputDebugString Windows API function.

Additionally, if the Use extended debugger for managed code setting of your test project is selected, TestComplete traces the following events in .NET applications:

Event Type Description
Application domain created Message A new application domain was created.
Application domain exited Message An application domain was unloaded.
Assembly loaded Message The application loaded an assembly.
Assembly unloaded Message The application unloaded an assembly.

Tracing Freezes

The tracing functionality provided by the Debug Services plugin allows tracing events and exceptions that occur in the tested application. However, it is not helpful if the application stops responding to the operating system. To trace these kinds of errors, TestComplete provides special functionality. For more information on this, see Diagnosing Application Freezes.

Samples

TestComplete includes a sample application and a test project that demonstrates how you can use Debug Services:

Application:

<TestComplete Samples>\Desktop\Running Tested Applications\DbgServices\Application

TestComplete project suites:

<TestComplete Samples>\Desktop\Running Tested Applications\DbgServices

Note: If you do not have the sample, download the TestComplete Samples installation package from the support.smartbear.com/downloads/testcomplete/samples/ page of our website and run it.

See Also

DbgServices Object
Options Object
Handling Exceptions in Scripts
Integration With AQtime
Tracing Exceptions, Crashes and Freezes in Tested Applications

Highlight search results