This topic explains specifics of creating custom keyword-test operations that run child operations in a loop.

About Loop Operations

Loop operations are keyword-test operations that execute child operations in a loop. Typical examples of these operations are the For Loop and While Loop operations built into TestComplete. You can create custom keyword-test loop operations to simplify iterations of specific types, for example, to enumerate files in a folder more easily or enumerate certain controls on screen.

About Creating Custom Loop Operations

Creating loop operations is very similar to creating other script extensions. You need to do the following:

Declare the operation and define its parameters in the description.xml file.
Implement script code that will handle the operation’s events and implement the operation’s functionality.

For detailed information on creating operations, see topics of the Creating Keyword Test Operations section. This topic explains specifics of creating custom loop operations.

Declaring Loop Operations

You declare loop operations in the same manner in which you declare other custom keyword-test operations. You can find an example below. For detailed information on elements and attributes, see Structure of the Description File.
Important: In order for the test engine to recognize your operation as a loop operation, the OperationType attribute of the KDTOperation element must be equal to Iterator. You should also specify handlers for events that are specific to loop operations (see below for information on these events):

XML

XML

[File: description.xml]

<?xml version="1.0" encoding="UTF-8"?>
<ScriptExtensionGroup>

  <Category Name="My Custom Keyword Test Operations">

    <ScriptExtension Name="My Loop Operation" Author="John Smith" Version="1.0" HomePage="someURL.com">
      <Script Name="myUnit.js">
        <KDTOperation Name="My Loop" Category="Standard" Icon="clc-icon.bmp" OperationType="Iterator">
          <Data>
            ...
          </Data>
          <Events>
            <Event Name="OnCreate" Routine="MyOp_OnCreate"/>
            <Event Name="OnSetup" Routine="MyOp_OnSetup"/>
            <Event Name="OnExecute" Routine="MyOp_OnExecute"/>
            <Event Name="OnIterate" Routine="MyOp_OnIterate"/>
            <Event Name="CanExecuteBody" Routine="MyOp_OnCanExecuteBody"/>
          </Events>
          <Columns>
            ...
          </Columns>
        </KDTOperation>
      </Script>
      <Description>
        ...
      </Description>
    </ScriptExtension>

  </Category>
</ScriptExtensionGroup>
Like any other keyword-test operation, loop operations can have parameters and fields. You may want to define some parameters that will specify conditions for the iteration. For instance, if you create an operation that enumerates files in a folder, you can create parameters that specify the desired folder, the file mask and, perhaps, a parameter that will return the current file name during iteration (or a parameter that specifies the variable to which the current file name will be stored). For detailed information on defining parameters and fields, see Creating Operation Parameters and Fields.

Events to Be Implemented

The functionality of custom keyword-test operations is implemented by script event handlers that are called at specific points of time. Some of events are triggered during the test run; their event handlers implement the operation’s run-time behavior. Some other events occur at design time; their event handlers and used for configuring operation properties.

Run Time Events

Execution of a loop operation includes several steps:

Initializing the loop.
Checking conditions and “reporting” to the test engine whether it should run child operations.
Running child operations.
Changing internal counters and variables and proceeding with the next iteration.

Each loop operation must implement specific events that are executed in these steps:

1. OnExecute - Occurs when the test engine starts executing your loop operation.

Write an event handler for this event to perform initialization actions that are needed by the loop.

2. CanExecuteBody - Occurs at the beginning of each iteration.

Write an event handler for this event to signal to the test engine whether to start the iteration and execute child operations.

3. Run child operations - On this step, the test engine executes child operations.

No event of your loop operation is triggered at this time.

4. OnIterate - Occurs at the end of each iteration.

Write an event handler for this event to update internal counters and variables for the next iteration.

Here are some notes on implementing event handlers:

The CanExecuteBody event handler should return true or false: true indicates that the test engine should run child operations; and false means child operations should not be executed.
Checking conditions can take some time. It is recommended that you perform needed checks within the OnExecute and OnIterate event handlers, save the results to some global script variable and use the CanExecuteBody handler to return the variable’s value (that is, to return the results of the check).

Design-Time Events

Design-time events of custom loop operations do not differ from events of other operations. Here is information on some events for which you may want to create event handlers:

OnCreate - This event is triggered only once, when your operation is added to a keyword test. You can create an event handler for it to perform various initialization actions. See Creating Operation Initialization Routine.
OnSetup - This event is triggered every time when a user modifies your operation’s properties. This happens, for instance, when the user adds the operation to their test or the user double-clicks the operation in the Keyword Test editor to modify the operation’s properties. Write an OnSetup event handler to display the Operation Properties wizard for your operation and apply changes to operation properties. See Creating the Operation Setup Routine.
You can also create script routines that handle column editing events: StartEditing, GetEditValue, SetEditValue, and ApplyChanges. See Implementing In-Place Editing Support.

Creating Custom Loop Operations