Typical Event Handler Tasks

Applies to TestComplete 15.40, last modified on March 25, 2022

This topic describes typical tasks that you may need to perform in your event handlers.

Posting a Screen, Mobile Screen or Window Image

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

    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

    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

    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");
    }

Changing Message Text or Attributes

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.

JavaScript, JScript

function 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;
}

Python

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

VBScript

Sub 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
End Sub

DelphiScript

function GeneralEvents_OnLogMessage(Sender, LogParams);
begin
  // 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;
end;

C++Script, C#Script

function 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;
}

Blocking Log Messages

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:

JavaScript, JScript

function GeneralEvents_OnLogMessage(Sender, LogParams)
{
  // Check if the message includes the desired substring
  var 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;
  }
}

Python

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

VBScript

Sub GeneralEvents_OnLogMessage(Sender, LogParams)
  ' Check if the message includes the desired substring
  locked = aqString.Find(LogParams.Str, "Some Substring")
  If locked <> -1 Then
    ' If found, block the message
    LogParams.Locked = True
  Else
    ' Else, post the message
    LogParams.Locked = False
  End If
End Sub

DelphiScript

function GeneralEvents_OnLogMessage(Sender, LogParams);
var
  locked : OleVariant;
begin
  // Check if the message includes the desired substring
  locked := aqString.Find(LogParams.Str, 'Some Substring');
  if (locked <> -1) then
  begin
    // If found, block the message
    LogParams.Locked := True;
  end
  else
  begin
    // Else, post the message
    LogParams.Locked := False;
  end;
end;

C++Script, C#Script

function GeneralEvents_OnLogMessage(Sender, LogParams)
{
  // Check if the message includes the desired substring
  var 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;
  }
}

Performing Specific Actions on Starting and Stopping Tests

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.

JavaScript, JScript

function GeneralEvents_OnStartTest(Sender)
{
  if (Project.TestItems.Current.Name == "FirstTestItem")
    // Do something
}
 

function GeneralEvents_OnStopTest(Sender)
{
  if (Project.TestItems.Current.Name == "LastTestItem")
    // Do something
}

Python

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

VBScript

Sub GeneralEvents_OnStartTest(Sender)
  If Project.TestItems.Current.Name = "FirstTestItem" Then
    ' Do something
  End If
End Sub
 

Sub GeneralEvents_OnStopTest(Sender)
  If Project.TestItems.Current.Name = "LastTestItem" Then
    ' Do something
  End If
End Sub

DelphiScript

procedure GeneralEvents_OnStartTest(Sender);
begin
  if (Project.TestItems.Current.Name = 'FirstTestItem')  then
    begin     // Do something
    end;
end;
 

procedure GeneralEvents_OnStopTest(Sender);
begin
  if (Project.TestItems.Current.Name = 'LastTestItem')  then
    begin     // Do something
    end;
end;

C++Script, C#Script

function GeneralEvents_OnStartTest(Sender)
{
  if (Project["TestItems"]["Current"]["Name"] == "FirstTestItem")
      // Do something
}
 

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

See Also

Creating Event Handlers for TestComplete Events
Creating Event Handlers for External COM Objects
Handling Events - Overview
Creating Event Handlers in TestComplete

Highlight search results