Tracing Events and Exceptions With Debug Services

Overview

Using the Debug Run Mode

Using the DbgServices Object

List of Traced Events

Tracing Freezes

Samples

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:

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.

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:

# 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()
  
...

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):

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).

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

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.

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