Waiting for an Object, Process or Window Activation

Applies to TestComplete 14.40, last modified on April 22, 2021

Testing conditions differ from one test run to another. It is often necessary to wait until a specific process launches or a specific window becomes active. This topic provides detailed information on how to organize waiting for objects from your test.

To make TestComplete wait for objects for a desired period of time, you can modify the value of the Auto-wait timeout option or specify a certain time period in one of the following ways:

Using the Default Auto-Wait Timeout

By default, TestComplete is waiting for objects, processes and windows for a period of time. This time period is specified by the Auto-wait timeout project option. By default, it is 10 seconds. If an object, window or process has not been found by the end of the specified period, the test fails.

The Auto-wait timeout affects the following methods:

Using WaitNNN Methods

You can use the WaitNNN methods to wait for objects in tests. These methods have the Timeout parameter that specifies the period during which TestComplete will wait for the needed object. The methods will return the needed object if it exists; otherwise, they will return a stub object.

For detailed information about WaitNNN methods, see their description.

All WaitNNN methods can be called from scripts and keyword tests (see below). Use the Exists method after any of these methods to determine whether the returned object is valid.

From script

The following code shows how to implement a waiting period of up to two seconds for launching Microsoft Word from script:

JavaScript, JScript

p = Sys.WaitProcess("winword", 2000);
if (p.Exists) // if the process exists ...
...

Python

p = Sys.WaitProcess("winword", 2000)
if p.Exists: #If the process exists ...
...

VBScript

Set p = Sys.WaitProcess("winword", 2000)
If p.Exists Then' if the process exists ...
...

DelphiScript

p := Sys.WaitProcess('winword', 2000);
if p.Exists then// if the process exists ...
...

C++Script, C#Script

p = Sys["WaitProcess"]("winword", 2000);
if (p["Exists"]) // if the process exists ...
...

If you launch a tested application using the TestedApp.Run method, you can use the method’s Timeout parameter to specify how long the method will wait before the application is launched. You can use this parameter as an alternative to the Sys.WaitProcess method:

JavaScript, JScript

var p;
// Wait for the application for 2 seconds
p = TestedApps.Items(0).Run(1, false, 2000);

Python

# Wait for the application for 2 seconds
p = TestedApps.Items(0).Run(1, False, 2000)

VBScript

' Wait for the application for 2 seconds
Set p = TestedApps.Items(0).Run(1, False, 2000)

DelphiScript

var p;
begin
  // Wait for the application for 2 seconds
  p := TestedApps.Items[0].Run(1, False, 2000); end;

C++Script, C#Script

var p;
// Wait for the application for 2 seconds
p = TestedApps["Items"](0)["Run"](1, false, 2000);

The following code uses the Process.WaitWindow method to wait up to ten seconds for a window to be created. Although the window may be created, it may not be fully opened onscreen:

JavaScript, JScript

p = Sys.Process("Notepad");
// Waits for the window for 10 seconds
w = p.WaitWindow("*", "Open*", -1, 10000);
if (w.Exists)
{
  w.Activate();
  Log.Picture(w, "Open dialog picture");
}
else
  Log.Warning("Incorrect window");

Python

p = Sys.Process("Notepad")
# Waits for the window for 10 seconds
w = p.WaitWindow("*", "Open*", -1, 10000)
if w.Exists:
  w.Activate
  Log.Picture(w, "Open dialog picture")
else:
  Log.Warning("Incorrect window")

VBScript

Set p = Sys.Process("Notepad")
' Waits for the window for 10 seconds
Set w = p.WaitWindow("*", "Open*", -1, 10000)
If w.Exists Then
  w.Activate
  Log.Picture w, "Open dialog picture"
Else
  Log.Warning "Incorrect window"
End If

DelphiScript

p := Sys.Process('Notepad');
// Waits for the window for 10 seconds
w := p.WaitWindow('*', 'Open*', -1, 10000);
if w.Exists then
begin
  w.Activate;
  Log.Picture(w, 'Open dialog picture');
end
else
  Log.Warning('Incorrect window')

C++Script, C#Script

p = Sys["Process"]("Notepad");
// Waits for the window for 10 seconds
w = p["WaitWindow"]("*", "Open*", -1, 10000);
if (w["Exists"])
{
  w["Activate"]();
  Log["Picture"](w, "Open dialog picture");
}
else
  Log["Warning"]("Incorrect window");

The following example illustrates the use of the WaitChild method in scripts. The following code waits for 10 seconds for the WINWORD process to appear in the system (note that all processes are children of the Sys object).

JavaScript, JScript

var p, s;
...
s = "Process(\"WINWORD\")";
p = Sys.WaitChild(s, 10000);
if (p.Exists)
  Log.Message(p.Name);
else
  Log.Message("Not found");

Python

s = 'Process("WINWORD")'
p = Sys.WaitChild(s, 10000)
if p.Exists:
  Log.Message(p.Name)
else:
  Log.Message("Not found")

VBScript

s = "Process(""WINWORD"")"
Set p = Sys.WaitChild(s, 10000)
If p.Exists Then
  Log.Message p.Name
Else
  Log.Message "Not found"
End If

DelphiScript

var s, p;
...
s := 'Process(''WINWORD'')';
p := Sys.WaitChild(s, 10000);
if p.Exists then
  Log.Message(p.Name)
else
  Log.Message('Not found');

C++Script, C#Script

var p, s;
...
s = "[\"Process\"](\"WINWORD\")";
p = Sys["WaitChild"](s, 10000);
if (p["Exists"])
  Log["Message"](p["Name"]);
else
  Log["Message"]("Not found");

From keyword tests

You can call the WaitNNN methods from keyword tests by using the Call Object Method operation.

Suppose that you need to wait for Microsoft Word to launch up to two seconds. For this purpose, add operations to the keyword test following the steps below:

  • Open your keyword test for editing.

    Switch to the Variables page of the Keyword Test editor and create a p variable in it. This variable will have the Object type and will store a reference to the process scripting object.

  • Add the Call Object Method operation to the test. Upon adding the operation, TestComplete will display the Operation Parameters wizard.

  • On the first page of the wizard, type Sys and click Next.

  • The second page will display a list of available methods of the Sys object. Choose the WaitProcess method from the list and click Next to continue.

  • On the third page of the Operation Parameters wizard you can specify the method’s parameters:

    • ProcessName

      • Choose Constant from the Mode drop-down list.

      • Specify String in the Type cell.

      • Enter the desired process name into the Value cell. In our case, the process name is WINWORD. Press Enter to confirm the input into the Value cell.

    • WaitTime

      • Choose Constant from the Mode drop-down list.

      • Specify Integer in the Type cell.

      • Enter the number of milliseconds to wait into the Value column. In our case, the waiting time equals 2000 milliseconds. Press Enter to confirm the input.

    • GroupIndex - Specifies the process instance if there are several WINWORD processes running in the operating system. We will not use this parameter in our example, leave it as it is.

  • Click Finish to save the changes and close the wizard. TestComplete will append the operation to the test.

Now let’s add the Set Variable Value operation to the test and save the method’s result to the p variable:

  • Drag the Set Variable Value operation from the Operations list to the test. TestComplete will display the wizard in which you can specify the operation’s parameters.

  • On the first page of the wizard, choose the p variable that we have created on the first step (see above). Click Next to continue.

  • On the second page you can specify the value to be assigned to the variable. In our example, the variable will store the result of the WaitProcess method, so select Last Operation Result in the Mode column and click Finish to close the wizard.

    TestComplete will add the operation to the keyword test.

Now we can check whether the desired application exists in the system. If the application exists, the WaitProcess method returns a reference to the process object that provides scripting access to the application. If the application does not exist, the method returns an empty stub object whose Exists property is False. Let’ check the property value.

  • To check the variable’s value, append the If ... Then operation to the test. TestComplete will display the Operation Parameters dialog where you can specify the condition to be checked.

  • In the Value 1 band:

    • Select Code Expression in the Mode column.

    • Type the following code into the Value cell:

      JavaScript, JScript

      KeywordTests.KeywordTest1.Variables.p.Exists

      Python

      KeywordTests.KeywordTest1.Variables.p.Exists

      VBScript

      KeywordTests.KeywordTest1.Variables.p.Exists

      DelphiScript

      KeywordTests.KeywordTest1.Variables.p.Exists

      C++Script, C#Script

      KeywordTests["KeywordTest1"]["Variables"]["p"]["Exists"]

  • Choose equal to in the Condition column.

  • In the Value 2 band:

    • Select Constant in the Mode column.

    • Choose Boolean from the Type drop-down list.

    • Select the check box in the Value column.

Now you can add operations that will work with the desired process as child operation to the If... Then operation. You can also add the Else operation to your test and then add others operations to the test as child items of this Else operation. These operations will be executed when the checked condition is False.

Using Custom Timeouts in Keyword Tests

To wait for a needed tested object to become available in a keyword test, you can specify a custom timeout for the operation that interacts with the object. For information on how to do this, see Specifying Custom Timeouts For Operations.

See Also

Working With Application Objects and Controls
Common Tasks
Waiting for Object State Changes
Waiting for an Object to Have a Specific Property Value
Delaying Test Execution
WaitWindow Method
WaitChild Method

Highlight search results