Standard keyword test operations included in TestComplete, being added to the test or double-clicked, display special wizards that allow the users to specify the operation parameter values. This topic explains how you can provide the same functionality for custom keyword test operations you create with script extensions.

When users add a custom operation to the test or double clicks it in the test, the operation raises the OnSetup event. By subscribing to this event and creating a handler for it, you can specify the actions to be performed as the operation setup process. For example, you can display a custom form that prompts the user to enter the parameter values (see Using Forms in Script Extensions). The event handler must meet the following requirements:

It should have the Data and Parameters arguments, which specify the objects providing access to the operation’s fields and parameters, respectively. (See the event description for details.) At that, if the routine has only parameters or both fields and parameters, both Data and Parameters arguments are required. If the operation has only fields or neither fields nor parameters, the routine must have the Data argument only.

Accessing operation parameters in the OnSetup event handler code has one specific. It comes from the possibility to use special values, such as keyword test variables, code expressions and others, as parameter values. The issue is that such values are not accessible in the operation code, as they can only be evaluated during test execution. In the operation code, they evaluate to empty values, so that the aqObject.GetVarType method reports their type as varEmpty. Your operation should correctly handle such cases in order not to reset these values.

It must return a boolean value -- True in case of successful setup and False in case of unsuccessful or aborted setup. The return value controls what happens next:
- If the event handler returns True and the operation has parameters, TestComplete will display the Operation Parameters dialog where the users can specify the parameter values in advanced mode.
- If the event handler returns False for a newly created instance of the operation, the operation will not be added to the test.

The following example demonstrates how you can implement the setup routine. The sample Copy File operation from this example is a wrapper over the aqFileSystem.CopyFile method and has the same parameters. The operation’s setup routine first displays a sample form where the users can supposedly browse for the file to copy and the destination file, and then displays the standard Operation Parameters dialog that provides advanced options for parameter values. The custom form is named frmCopyFile and contains two TcxButtonEdit controls named txtSourceFile and txtDestinationFile and a TcxCheckBox control named chkRename.

description.xml

JScript

// This routine specifies the default values of the operation parameters
function CopyFile_OnCreate (Data, Parameters)
{
  Parameters.Source = "";
  Parameters.Destination = "";
  Parameters.RenameOnCollision = true;
}

// This routine is executed when the operation is added to the test
// or double-clicked in the test
function CopyFile_OnSetup(Data, Parameters)
{
  // If current parameter values are inaccessible in script code, ...
  if (! CheckParams())
    return true; // ... display them in the Operation Parameters dialog

  // Display the edit form
  var frm = UserForms.frmCopyFile;
  frm.ResetForm();
  frm.txtSource.Text = Parameters.Source;
  frm.txtDestination.Text = Parameters.Destination;
  frm.chkRenameOnCollision.Checked = Parameters.RenameOnCollision;

  if (frm.ShowModal() != mrOk) return false;

  // Save the changes made to parameter values
  Parameters.Source = frm.txtSource.Text;
  Parameters.Destination = frm.txtDestination.Text;
  Parameters.RenameOnCollision = frm.chkRenameOnCollision.Checked;
  return true;
}

// Verifies that the operation parameters evaluate to non-empty values
function CheckParams(Params)
{
  return
    (GetVarType(Params.Source) != varEmpty) &&
    (GetVarType(Params.Destination) != varEmpty) &&
    (GetVarType(Params.RenameOnCollision) != varEmpty);
}

// This routine is executed by the operation during the test run
function CopyFile_OnExecute (Data, Source, Destination, RenameOnCollision)
{
  var result = aqFileSystem.CopyFile(Source, Destination, RenameOnCollision);
  if (! result)
    Log.Error("Failed to copy the \"" + Source + "\" file.");
  return result;
}

VBScript

' This routine specifies the default values of the operation parameters
Sub CopyFile_OnCreate (Data, Parameters)
  Parameters.Source = ""
  Parameters.Destination = ""
  Parameters.RenameOnCollision = True
End Sub

' This routine is executed when the operation is added to the test
' or double-clicked in the test
Function CopyFile_OnSetup(Data, Parameters)
  ' If current parameter values are inaccessible in script code, ...
  If Not CheckParams Then
    CopyFile_OnSetup = True ' ... display them in the Operation Parameters dialog
    Exit Function
  End If

  ' Display the edit form
  Dim frm
  Set frm = UserForms.frmCopyFile
  frm.ResetForm
  frm.txtSource.Text = Parameters.Source
  frm.txtDestination.Text = Parameters.Destination
  frm.chkRename.Checked = Parameters.RenameOnCollision

  If frm.ShowModal <> mrOk Then
    CopyFile_OnSetup = False
    Exit Function
  End If

  ' Save the changes made to parameter values
  Parameters.Source = frm.txtSource.Text
  Parameters.Destination = frm.txtDestination.Text
  Parameters.RenameOnCollision = frm.chkRename.Checked

  CopyFile_OnSetup = True
End Function

' Verifies that the operation parameters evaluate to non-empty values
Function CheckParams(Params)
  CheckParams = _
    GetVarType(Params.Source) <> varEmpty And _
    GetVarType(Params.Destination) <> varEmpty And _
    GetVarType(Params.RenameOnCollision) <> varEmpty
End Function

' This routine is executed by the operation during the test run
Function CopyFile_OnExecute (Data, Source, Destination, RenameOnCollision)
  CopyFile_OnExecute = aqFileSystem.CopyFile(Source, Destination, RenameOnCollision)

  If Not CopyFile_OnExecute Then
    Log.Error "Failed to copy the """ & Source & """ file."
  End If
End Function

To only display the standard Operation Parameters dialog upon adding or double-clicking the operation, create the OnSetup event handler that simply returns True:

JScript

VBScript

Copy Code

JScript

function MyOperation_OnSetup(Data, Parameters)
{
return true;
}

VBScript

Function MyOperation_OnSetup(Data, Parameters)
MyOperation_OnSetup = True
End Function

Creating the Operation Setup Routine

See Also