JScript - Calling Routines and Variables Declared in Another Unit

Applies to TestComplete 15.47, last modified on January 20, 2023

This topic describes methods of calling items declared in another unit with JScript code.

Adding Script References

To reference another unit from the current unit using JScript, add the following line at the beginning of the current script (before any functions and variable declarations):

JScript

// To reference one unit
// [UnitA]
//USEUNIT UnitName

// To reference multiple units
// [UnitA]
//USEUNIT UnitName1
//USEUNIT UnitName2

There must be no spaces at the beginning of the line before the // characters, and between these characters and the USEUNIT keyword.

Calling Items From Another Unit

Once an external unit is linked to the current one, all the routines, as well as global variables and constants of the external unit, can be called in the current unit. It is recommended (though it is not obligatory) to prefix the names of external routines, variables and constants with the unit's name. That is, in general, calling items from another unit by using any of the following code instructions is correct:

JScript

MyExtUnit.MyRoutine(Param1, Param2)
MyRoutine(Param1, Param2)

MyExtUnit.MyVariable
MyVariable

MyExtUnit.MyConstant
MyConstant

You must specify the name of the referenced unit in the following cases:

  • When the current unit already contains a routine, global variable or global constant with the same name. Without prefixing, the routine, variable or constant of the current unit will be called.

  • When the name of an external routine is the same as the name of an external unit. Calling such a routine without a prefix will cause an exception.

To call a routine defined in an external unit that is linked to your current unit, you can also pass a string that specifies the target routine’s full name (that is, "unit_name.routine_name") to the eval function. If the external routine you want to call takes parameters, include them in the string parameter you pass to the eval function.

JScript

// [UnitA]

//USEUNIT UnitB
function Test()
  {
  eval("UnitB.TestFunction()");
  eval("UnitB.TestFunction(1, 'string', true)");
  result = eval("UnitB.TestFunction()");
}

To call routines declared in external units, you can also use square bracket notation:

JScript

UnitName["TestFunction"]();
UnitName["TestFunction"](1, 'string', true);
res = UnitName["TestFunction"]();

Important Notes

  • To use JScript prototype methods from referenced units, you need to create wrapper functions for them. For details, see JScript, C#Script and C++Script - Specifics of Usage.

  • To make a variable or constant visible to other units, declare it as global, that is, outside any routines.

  • If the current unit is linked to a unit that is linked to another unit, the script declared in the third unit can be called from the current unit. For instance, if you need to call a function declared in UnitA from UnitC, which is linked to UnitB, you must add references to UnitA in UnitB. They will interact in the following way:

    UnitA (contains no references)UnitB (contains a reference to unitA)UnitC (contains a reference to unitB)

    If the references are correct, the items from UnitA will be available in UnitC, like in the following example:

    JScript

    // [UnitA]
    function testProcedure()
    {
      Log.Message("The procedure is run.");
    }
    // ...
     
    // [UnitB]
    //USEUNIT UnitA
    // ...
     
    // [UnitC]
    //USEUNIT UnitB
    function Test2()
    {
      UnitA.testProcedure();
    }
    // ...

  • The USEUNIT statement does not copy, share, or merge project items. These elements remain available only for the project the unit is imported from. To be able to work with elements that reside within external projects, import them to or share them with the current project. For more information about this, see Sharing Project Items and Their Child Elements Among Several Projects.

  • If you reference a script from another project, and that script uses object names from Name Mapping, you may need to merge the external Name Mapping file with your local Name Mapping file. For instructions, see Merge Name Mapping Files.

  • When a routine is called from another script unit, the caller property of the Function object that corresponds to the current routine returns null. Normally, when a function is called by another routine declared in the same script unit, the caller property returns a reference to the function that invoked the current function. If the caller property is used in a string context, it contains the text of the function that called the current routine. See the description of the Function object and its caller property in the MSDN Library.

  • JScript does not allow the use of circular references. They can cause errors in the jscript.dll library and these errors can cause other errors in TestComplete.

See Also

Calling Routines and Variables Declared in Another Unit from GUI
Calling Routines Declared in Another Project
Supported Scripting Languages - Specifics of Usage

Highlight search results