About Operation Parameters and Fields
Each keyword test operation can have parameters and fields that store the operation data and can be used to control the operation functionality and behavior. The concept of operation parameters and fields is similar to the concept of public and private class members.
Parameters are like public class members: they are available in the operation’s source code as well as accessible by TestComplete and the users. Operation parameters are displayed in the Value column of Test Steps page of the Keyword Test editor, and their valued can be modified by users via the Operation Parameters dialog.
Fields are analogs to private class members: they are available only in the operation’s source code and are supposed to be used by the operation’s developer only. Fields are like variables defined in the script extension code. However, the difference is that global script variables are shared between all operation instances, whereas each operation has its own copy of the field set. So, fields are usually used to store some helper operation-specific data.
The difference in the scope of operation parameters and fields also conditions the difference in the values they can store:
-
Fields can only store only Variant-compatible values: integer and floating-point numbers, strings, boolean values, objects, and so on.
-
Parameters can store Variant-compatible values as well as specific value types, such as project variables, code expressions, last operation result and so on (see Specifying Operation Parameters). In the script extension code or the description file, operation parameters can be initialized with Variant values only; other value types can be assigned by the user at design time.
An operation can have both parameters and internal fields, only one type of these items, or none of them. It all depends on a particular operation.
Both operation parameters and fields are defined in the description file of the script extension package using special elements of the XML markup. The rest of the topic explains how you can add parameters and fields to your custom operations.
Creating Operation Parameters
As mentioned above, you can define the operation parameters in the script extensions’s description.xml file. For this, add the child Parameters element to the KDTOperation element that corresponds to your operation. The Parameters element is a container of Parameter elements that provide parameter definitions:
XML
[description.xml]
…
<KDTOperation Name="Copy File" Category="Files and Folders">
…
<Parameters>
<Parameter Name="SourceFileName">The name of the file to be copied.</Parameter>
<Parameter Name="DestFileName">The name of the destination file to create.</Parameter>
<Parameter Name="RenameOnCollision" DefaultValue="True">Specifies how to resolve a possible file name collision.</Parameter>
</Parameters>
…
</KDTOperation>
…
As you can see, each parameter must have a name, which is specified by the Name attribute. This name will be displayed in the Name column of the Operation Parameters dialog called for the operation. The parameter name is also used to refer to that parameter in the operation’s source code, so it must be a valid identifier in the scripting language that you use to write the operation code. The easiest way to follow this rule is to use only alphanumeric (A…Z, a…z, 0…9) and underscore ( _ ) characters in the name and start the name with a letter.
A parameter may have a default value. It can be specified in the DefaultValue attribute of the Parameter element. Alternatively, you can initialize parameter values in the operation’s OnCreate event handler (see the example below).
| Note: | Default parameter values specified in the description.xml file are considered as string values. That is, the attribute DefaultValue="42" initializes the parameter with the string "42", not the number 42. If you need to initialize parameters with values other than strings, it is recommended that you do this in the operation’s OnCreate event handler. |
The Parameter element may also contain a short descriptive text for that parameter. This text is ignored by TestComplete and is not displayed anywhere. However, you can use it to document the operation parameters.
| Note: | The order in which the operation parameters are defined in the description.xml file determines their display order in the Value column of the Keyword Test editor and also the order in which they are passed to the operation’s OnExecute routine. You should keep this in mind when writing the OnExecute routine code. |
In the script extension code, operation parameters are available in the operation’s event handlers. At that, they are accessible either as properties of the event handler’s Parameters argument (like in the OnCreate event handler), or as individual event arguments (like in the OnExecute event handler). The following example illustrates access to operation parameters in the script extension code:
JScript
// Initializes the operation's parameter values
function CopyFile_OnCreate(Data, Parameters)
{
Parameters.SourceFileName = "";
Parameters.DestFileName = "";
Parameters.RenameOnCollision = true;
}
// This function is executed by the operation during the test run
function CopyFile_OnExecute(Data, SourceFileName, DestFileName, RenameOnCollision)
{
return aqFileSystem.CopyFile(SourceFileName, DestFileName, RenameOnCollision);
}
VBScript
' Initializes the operation's parameter values
Sub CopyFile_OnCreate(Data, Parameters)
Parameters.SourceFileName = ""
Parameters.DestFileName = ""
Parameters.RenameOnCollision = True
End Sub
' This function is executed by the operation during the test run
Function CopyFile_OnExecute(Data, SourceFileName, DestFileName, RenameOnCollision)
CopyFile_OnExecute = aqFileSystem.CopyFile(SourceFileName, DestFileName, RenameOnCollision)
End Function
Creating Operation Fields
Like parameters, operation fields are also defined in the description.xml file, however, using different elements. The container of field definitions is the KDTOperation’s child Data element. It contains child Field elements that provide information about fields:
XML
[description.xml]
…
<KDTOperation Name="Change Attributes" Category="Files and Folders">
…
<Data>
<Field Name="Path">The path to the file or folder whose attributes will be modified.</Field>
<Field Name="ReadOnlyAction">Indicates how the Read-only attribute will be changed.</Field>
<Field Name="HiddenAction">Indicates how the Hidden attribute will be changed.</Field>
<Field Name="SystemAction">Indicates how the System attribute will be changed.</Field>
<Field Name="ArchiveAction">Indicates how the Archive attribute will be changed.</Field>
</Data>
…
</KDTOperation>
…
Field elements are very similar to the Parameter elements. Each field also has a name, which must be a valid script identifier, and may optionally have a default value and a description specified. Instead of specifying the fields’ default values in the description file, you can initialize them in the operation’s OnCreate event handler (see the example below).
| Note: | Default field values specified in the description.xml file are considered as string values. If you need to initialize parameters with other value types, such as numeric or boolean values, it is recommended that you do this in the operation’s OnCreate event handler. |
Fields also have the special Persistent attribute that specifies whether the field value should be stored in the Keyword Test file along with other operation data, whether it should be preserved when the operation is copied, and so on. By default, all fields are persistent. An example of when this attribute should be set to False is when the field is computer based on other operation’s fields and parameters. In many cases, however, such fields can be replaced by global script variables.
In the script extension code, fields are accessible as properties of the Data argument of operation’s event handlers. The following example demonstrates how fields can be addressed:
JScript
// Initializes the operation's field values
function ChangeAttrs_OnCreate(Data)
{
Data.Path = "";
Data.ReadOnlyAction = -1;
Data.HiddenAction = -1;
Data.SystemAction = -1;
Data.ArchiveAction = -1;
}
VBScript
' Initializes the operation's field values
Sub ChangeAttrs_OnCreate(Data)
Data.Path = ""
Data.ReadOnlyAction = -1
Data.HiddenAction = -1
Data.SystemAction = -1
Data.ArchiveAction = -1
End Sub
See Also
Creating Keyword Test Operations
Creating Keyword Test Operations - Basic Concepts
Structure of the Description File