Creating Operation Parameters and Fields

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:

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

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.

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:

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:

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

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:

See Also

Creating Keyword Test Operations
Creating Keyword Test Operations - Basic Concepts
Structure of the Description File