Waiting for an Object, Process or Window Activation

Using the Default Auto-Wait Timeout

Using WaitNNN Methods

Using Custom Timeouts in Keyword Tests

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:

• Sys.Process
• Process.Window
• Window.Window

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.

• Use the Sys.WaitProcess and Process.WaitWindow methods to wait for a process to be launched or a window to be opened respectively.

• Use the WaitXXXX methods that match the type of the tested objects: WaitWinFormsObject, WaitCLXObject, WaitJavaFXObject, WaitQtObject, WaitSlObject, WaitWPFObject, and so on.

  To learn which Wait method to use:

  1. Examine the needed object in the Object Browser.

  2. Note the method that the Name property uses to address the object.

  3. Add the Wait prefix to the method name.

  For example, if your object is addressed by the VCLNETObject method, you can use the WaitVCLNETObject method to wait for this object for a desired period.

• Use the WaitChild method to address the object directly by its name. This method waits for a child to appear in the parent’s child list for a specified timeout period.

• Use the WaitNamedChild and WaitAliasChild methods to delay the test execution until the specified mapped child object or child alias appears in the system.

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:

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:

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

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 next example is a more realistic use of WaitWindow. It delays the test execution until the desired window is created and displayed onscreen:

def Test():
  i = 0
  p = Sys.Process("Notepad")
  while True:
    w = p.WaitWindow("*", "Open", -1, 5000)
    i = i + 1
    if (w.Exists and w.VisibleOnScreen) or (i > 10):
      break
  if not (w.Exists and w.VisibleOnScreen):
    Log.Warning("Window not found.")
  else:
    Log.Message("Window was found.")

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

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

    Python

    VBScript

    DelphiScript

    C++Script, C#Script

    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.

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.