Typical Event Handler Tasks

Posting a Screen, Mobile Screen or Window Image

Changing Message Text or Attributes

Blocking Log Messages

Performing Specific Actions on Starting and Stopping Tests

One of the typical tasks that you may need to perform is posting an image of some window or of the whole screen to the test log when an error occurs. For instance, you may want to post the image of an unexpected or overlapping window that prevents test commands from running, or you may want to post the image of the entire screen when an error message is sent to the log.

To post images to the log, you can use the Log.Picture method or Message, Warning, Error and some other methods of the Log object. See Posting Images to the Log.

These methods have a parameter that specifies the Window object, which corresponds to the desired window, or the Picture object that corresponds to the image to be posted. The way you obtain these objects depends on your test and on the event handler. Here are a couple of examples:

• Window Image, OnUnexpectedWindow Event Handler

  The OnUnexpectedWindow event handler has the Window parameter that provides a scripting interface to the "unexpected" window to TestComplete. To post the window’s image to the log, you can use the following code:

  JavaScript, JScript

  Python

  VBScript

  DelphiScript

  C++Script, C#Script

  JavaScript, JScript

  function GeneralEvents_OnUnexpectedWindow(Sender, Window, LogParams)
  {
    Log.Picture(Window, "Image of the unexpected window", "", pmHigher);
  }

  Python

  def GeneralEvents_OnUnexpectedWindow(Sender, Window, LogParams):
    Log.Picture(Window, "Image of the unexpected window", "", pmHigher)

  VBScript

  Sub GeneralEvents_OnUnexpectedWindow(Sender, Window, LogParams)
    Log.Picture Window, "Image of the unexpected window", "", pmHigher
  End Sub

  DelphiScript

  procedure GeneralEvents_OnUnexpectedWindow(Sender : OleVariant; Window : OleVariant; LogParams : OleVariant);
  begin
    Log.Picture(Window, 'Image of the unexpected window', '', pmHigher);
  end;

  C++Script, C#Script

  function GeneralEvents_OnUnexpectedWindow(Sender, Window, LogParams)
  {
    Log["Picture"](Window, "Image of the unexpected window", "", pmHigher);
  }

• Screen Image, Mobile Screen Image, OnLogError Event Handler

  When TestComplete detects that an error message has been sent to the log, it triggers the OnLogError event. The following code snippet demonstrates how you can post the image of the entire screen to the test log from the OnLogError event handler. To obtain the screen image, we use the Sys.Desktop.Picture method:

  JavaScript, JScript

  Python

  VBScript

  DelphiScript

  C++Script, C#Script

  JavaScript, JScript

  function GeneralEvents_OnLogError(Sender, LogParams)
  {
    Log.Picture(Sys.Desktop.Picture(), "Image of the whole screen", "", pmHigher);
  }

  Python

  def GeneralEvents_OnLogError(Sender, LogParams):
    Log.Picture(Sys.Desktop.Picture(), "Image of the whole screen", "", pmHigher)

  VBScript

  Sub GeneralEvents_OnLogError(Sender, LogParams)
    Log.Picture Sys.Desktop.Picture(), "Image of the whole screen", "", pmHigher
  End Sub

  DelphiScript

  procedure GeneralEvents_OnLogError(Sender : OleVariant; LogParams : OleVariant);
  begin  Log.Picture(Sys.Desktop.Picture(), 'Image of the whole screen', '', pmHigher);
  end;

  C++Script, C#Script

  function GeneralEvents_OnLogError(Sender, LogParams)
  {
    Log["Picture"](Sys["Desktop"]["Picture"](), "Image of the whole screen", "", pmHigher);
  }

  To post a script image to the log, you can also enable the Post image on error property of your test project. However, with the event handler you can perform some additional operations or change the image before posting it. For example, you can use the Picture.GetRect method to obtain some rectangular area of the screen and post this area to the log:

  JavaScript, JScript

  Python

  VBScript

  DelphiScript

  C++Script, C#Script

  JavaScript, JScript

  function GeneralEvents_OnLogError(Sender, LogParams)
  {
    var pict, region;
   
    pict = Sys.Desktop.Picture();
    region = pict.GetRect(10, 10, 200, 100);
    Log.Picture(region, "Image");
  }

  Python

  def GeneralEvents_OnLogError(Sender, LogParams):
    pict = Sys.Desktop.Picture()
    region = pict.GetRect(10, 10, 200, 100)
    Log.Picture(region, "Image")

  VBScript

  Sub GeneralEvents_OnLogError(Sender, LogParams)
    Set pict = Sys.Desktop.Picture()
    Set region = pict.GetRect(10, 10, 200, 100)
    Log.Picture region, "Image"
  End Sub

  DelphiScript

  procedure GeneralEvents_OnLogError(Sender : OleVariant; LogParams : OleVariant);
  var
    pict, region : OleVariant;
  begin  pict := Sys.Desktop.Picture();
    region := pict.GetRect(10, 10, 200, 100);   Log.Picture(region, 'Image');
  end;

  C++Script, C#Script

  function GeneralEvents_OnLogError(Sender, LogParams)
  {
    var pict, region;
   
    pict = Sys["Desktop"]["Picture"]();
    region = pict["GetRect"](10, 10, 200, 100);
    Log["Picture"](region, "Image");
  }

There are a number of events that TestComplete triggers when messages are posted to the test log. You can change the default message text in the event handlers of these events.

The event handlers have the LogParams parameter that is a reference to the LogParams object that provides a scripting interface to the message’s text and attributes (like message priority, font color and style). To change the message text, use the MessageText or AdditionalText property of this object.

def GeneralEvents_OnLogMessage(Sender, LogParams):
  # Change message text
  LogParams.MessageText = "New message text"
  LogParams.AdditionalText = "New text of the Details panel."
 
  # Change message attributes
  LogParams.FontStyle = fmBold
  LogParams.FontColor = clMaroon
  LogParams.Color = clYellow

Events that post messages to the test log use the LogParams parameter. This parameter holds a reference to the LogParams object that provides a scripting interface to the message-related data. The Locked property of this object specifies whether TestComplete should post messages to the log. Set this property to True if you do not want TestComplete to post messages. You can set the property only when some specific condition occurs. For instance, the following code snippet demonstrates how to block a message that contains specific text:

def GeneralEvents_OnLogMessage(Sender, LogParams):
  # Check if the message includes the desired substring
  locked = aqString.Find(LogParams.Str, "Some Substring")
  if locked != -1:
    # If found, block the message
    LogParams.Locked = True
  else:
    # Else, post the message
    LogParams.Locked = False

To perform specific actions on test start, create the OnStartTest event handler. To perform actions on stopping a test, use the OnStopTest event handler.

If you use test items in your project, then both events are also triggered on start and stop of each test item. So, if you want to perform specific actions on starting or stopping the entire test run, you need to implement special logic in the event handlers to determine whether the event is triggered for the first or for the last test item.

To do this, use the Project.TestItems.Current property. It provides a scripting interface to the currently running test item. To determine whether this item is the first or the last one, compare its name with the name of the first or last item in your project.

def GeneralEvents_OnStartTest(Sender):
  if Project.TestItems.Current.Name == "FirstTestItem":
    # Do something
    ...
    
def GeneralEvents_OnStopTest(Sender):
  if Project.TestItems.Current.Name == "LastTestItem":
    # Do something
    ...

In some cases, global variables can become unavailable to the OnStopTest event handler. That happens because all global variables are cleared by the moment the OnStopTest event handler starts execution. To avoid such situations, we recommend that you use project variables rather than global variables in your tests. For more information, see the OnStopTest event description.

The OnStopTest event is triggered when the test completes successfully or fails. So, you can use it to perform finalization actions for your project regardless of the test result. The following topics describe some operations that can be performed from within the OnStopTest event handler: