Using Timers

Applies to TestComplete 14.20, last modified on September 11, 2019

A timer runs a specific script procedure or function at regular time intervals. You can use timers to do some regular processing, for example, to check if some application is running.

To manage timers in scripts, use the Timers object. It holds a collection of all existing timers and contains methods for creating new and deleting existing timers from the collection.

To create a new timer, call Timers.Add:

JavaScript, JScript

var MyTimer = Utils.Timers.Add(10000, "Unit1.TimerRoutine", true);

Python

MyTimer = Utils.Timers.Add(10000, "Unit1.TimerRoutine", True)

VBScript

Dim MyTimer
Set MyTimer = Utils.Timers.Add(10000, "Unit1.TimerRoutine", True)

DelphiScript

var MyTimer;
begin
  MyTimer := Utils.Timers.Add(10000, 'Unit1.TimerRoutine', true);
end;

C++Script, C#Script

var MyTimer = Utils["Timers"]["Add"](10000, "Unit1.TimerRoutine", true);

This method uses three parameters that specify properties of the new timer:

Parameter Description
Interval Integer. The timer interval, in milliseconds.
TimerProc String. The name of the script procedure or function to run when the timer interval elapses. Use the format unit_name.routine_name. This routine must have no parameters.
Enabled True/False. Specifies whether the timer is active. If the timer is inactive, it does not fire its script routine.

The Add method returns the Timer object that provides a scripting interface to the created timer. You can use this object to disable or enable a timer, change its interval, and so on. You can save this object to a variable and then use this variable to work with the timer.

Besides the variable, the reference to the created Timer object is also held by the Timers collection. You can get a timer from it using the Timers.Items property. This property is especially useful, if you have to use a timer in different script units. Since the Timers collection contains all of the created timers, there is no need to employ global variables and refer to units from each other in order to work with the same timer.

You can get the timer from the collection using either the timer’s index, or name. The Timer object contains the Name property, which you can assign a name to the timer and then address the timer by this name:

JavaScript, JScript

// Unit1
MyTimer = Utils.Timers.Add(1000, "Unit1.TimerRoutine", false);
MyTimer.Name = "MyTimerName";

// Unit2
Utils.Timers.Items("MyTimerName").Enabled = true;

Python

# Unit1
MyTimer = Utils.Timers.Add(1000, "Unit1.TimerRoutine", False)
MyTimer.Name = "MyTimerName"
...
# Unit2
Utils.Timers.Items("MyTimerName").Enabled = True
...

VBScript

' Unit1
Set MyTimer = Utils.Timers.Add(1000, "Unit1.TimerRoutine", False)
MyTimer.Name = "MyTimerName"

' Unit2
Utils.Timers.Items("MyTimerName").Enabled = True

DelphiScript

// Unit1
MyTimer := Utils.Timers.Add(1000, 'Unit1.TimerRoutine', false);
MyTimer.Name := 'MyTimerName';

// Unit2
Utils.Timers.Items('MyTimerName').Enabled := true;

C++Script, C#Script

// Unit1
MyTimer = Utils["Timers"]["Add"](1000, "Unit1.TimerRoutine", false);
MyTimer["Name"] = "MyTimerName";

// Unit2
Utils["Timers"]["Items"]("MyTimerName")["Enabled"] = true;

If the Enabled parameter is True, the timer becomes active after its creation. You can deactivate it later using the Enabled property of the Timer object. Alternatively, you can create a disabled timer and then activate it when necessary.

To decrease the number of timers, you can either delete the timers you no longer need or disable them. To delete a timer, use the Timers.Delete method. To disable a timer, assign False to the Enabled property of the appropriate Timer object.

TestComplete automatically removes all timers when the test run is over. To explicitly delete all the timers, call Timers.Clear.

Notes
  • When a timer elapses, TestComplete pauses the test to run the timer’s routine. The test is resumed after the timer routine has finished running.

    Because of this, try to make timer routines as fast as possible. Using many timers with long-running routines can slow down the test run.

  • If two or more timers elapse at the same time, TestComplete runs their routines in turn, not in parallel. So, the actual time at which a timer fires may slightly differ from the Interval value.

  • For desktop applications only: If an unexpected window appears during the test run, the timer will not fire until this window is closed. The timer will keep working while the unexpected window is open, but it will not run its routine.

  • The timer cannot be edited, deleted or disabled inside the timer handler routine. If you try to do this, the TestComplete engine will freeze or even crash. This happens due to restrictions of the internal Timer procedure. These restrictions cannot be removed.

    To ensure the correct behavior of the timer, add the following check inside the timer handler routine:

    JavaScript, JScript

    if (!TimerRoutine)
    {
      timerRoutine = true;
    }

    Python

    if not TimerRoutine:
       TimerRoutine = True

    VBScript

    If Not TimerRoutine Then
       TimerRoutine = True
    End If

    DelphiScript

    if not TimerRoutine then
    begin
      TimerRoutine := True;
    end;

    C++Script, C#Script

    if (!TimerRoutine)
    {
      timerRoutine = true;
    }

See Also

Timers Object
Timer Object
Script Tests

Highlight search results