This topic describes the process of creating custom runtime objects with script extensions. It assumes that you are familiar with common procedures of script extension development described in the Creating Script Extensions - Basic Concepts topic.

Define the object purpose

First of all, you need to decide why you need a custom runtime object. Do you need scripting functionality that is not natively built in the scripting languages or TestComplete objects? Do you need to a common routine library that can be used in different projects? Or maybe you need a wrapper over some ActiveX or COM object (such as Excel.Application), which will provide easier or more convenient access to the underlying object’s functionality? Once you have clearly defined the object's purpose, you can proceed thinking over the object architecture.
Define the object name

The object name is used to address the object in keyword tests and scripts. This name must be meaningful and must reflect the object's purpose, so that the users can easily understand what the object does. For example, if you are creating an object that is a wrapper over Microsoft Excel, you can name this object Excel.

The object name must meet the following requirements:
- It must start with a letter and can include only letters (A..Z, a..z), digits (0..9) and underscores (_).
- It must differ from the names of:
  - TestComplete built-in objects –Sys, Log and others.
  - Objects added by third-party plugins.
  - Native objects and routines of JavaScript, JScript, Python, VBScript and DelphiScript.
  If you want to use the same name for your object, create a namespace for it (see below).
- It must not be a reserved word in JavaScript, JScript, Python, VBScript and DelphiScript. For a list of reserved keywords, see:
  
  JavaScript’s lexical grammar
  
  INFO: Reserved Words in VBScript 5.5 and JScript 5.5
  
  The Python Language Reference
  
  DelphiScript - Unsupported Keywords
- It must differ from the names of the object’s methods and of the corresponding script routines in the script extension’s source code (see below).
Nevertheless, the object name can coincide with the names of objects provided by other script extensions. In this case, the objects with the same name (and namespace) will be merged and the resulting object will contain properties and methods provided by different script extensions.

Names of objects provided by JScript extensions are case-sensitive. Wrong naming of these objects can cause errors in VBScript units, since this script engine is case-insensitive. For more information, see VBScript - Specifics of Usage.

(Optional) Define the object namespace

If you plan to create several objects, you may wish to organize them into a namespace. In this case, the objects will be addressed using the Namespace.ObjectName syntax rather than simply the object name. In this way, for example, you can distinguish your custom objects from standard ones of TestComplete.

The following Code Completion images show the differences between the objects defined within a namespace and those that have no namespace defined.

MyObject1 and MyObject2 do not have namespaces

MyObject1 and MyObject2 are defined in the MyNamespace

Like the object name, the namespace name must be a valid script identifier. It must also be unique, that is, does not coincide with the names of standard TestComplete objects, objects provided by third-party plugins and script extensions as well as intrinsic objects, routines and reserved words of scripting languages supported by TestComplete.

If the namespace name coincides with the name of another namespace provided by a script extension, they will be merged into one. This way, objects added by different script extensions can be united under the same namespace.
Decide which methods and properties the object will provide

Objects contain members -- properties and methods -- that represent the object’s data and behavior. So, the next step in planning a runtime object is defining the set of its members.

If you want the object to hold some data available for external access, consider implementing a property. At that, you also need to decide the access type of the property -- read-write, read-only or write-only.

If you want the object to do some actions, consider implementing a method. You also need to decide such aspects as: whether the method needs to be parameterized, whether it needs to return a value indicating its result, and so on.
Write the object code

After you have planned the object, you can write the code of its properties and methods. For more information on this, see Creating Object Properties and Creating Object Methods. Note that custom objects are language-independent: they can be used in any TestComplete project no matter which language it uses and in which language the object is written. You can choose the language for writing the object code -- JScript or VBScript -- based on your personal preferences.

The source code of object properties and methods can reside in a single script unit or in several units (or even script extensions). The latter is made possible by the fact that multiple object implementations are merged into one if these objects have the same name and namespace. So, if you have several scripts (or script extensions) that implement different methods and properties of the same object, you will have to define objects with the same name and namespace for each of the source script files (or script extensions). The resulting object will contain all of the properties and methods provided by the partial objects.

Note, that objects created with script extensions do not have explicit constructors and destructors. However, you can implement this functionality using initialization and finalization routines. See Creating Initialization and Finalization Routines.

It is not recommended that the names of scripting routines that implement the object’s functionality coincide with the object's name. This concerns not only the object methods, but also the helper script routines that reside in the source units. The coincidence will cause malfunctions of the TestComplete Code Completion window. It will not display information on methods.

You can find an example of a custom object’s code in the <TestComplete>\Bin\Extensions\ScriptExtensions\AQAScriptExtensions.tcx file that is shipped with TestComplete. This file is a ZIP archive, so you can extract files from it using any archiver that supports ZIP files. For more information about files included in this package, see Pre-Installed Script Extensions.
Add information about the object to the description file

Finally, you need to define the object in the description.xml file of the script extension package. Runtime objects are defined using the RuntimeObject element of the file’s XML markup. This element has attributes to specify the object name and namespace. The object’s methods and properties and their attributes are defined in the child Method and Property elements of the RuntimeObject element. A special Description element lets you define description of the object and its members, which will be displayed in the Code Completion window. For more information about writing the description file, see Structure of the Description File.

You can find a sample description file in the <TestComplete>\Bin\Extensions\ScriptExtensions\AQAScriptExtensions.tcx file that is installed along with TestComplete.

Creating Runtime Objects - Basic Concepts

See Also