JavaScript - Calling Routines and Variables Declared in Another Unit

Applies to TestComplete 14.40, last modified on April 22, 2021

Exporting Items From Units

To make an item (variable or function) available to other units, add it to the module.exports object that is available in any JavaScript unit:

JavaScript

JavaScript

// [CommonUnit]
function getObj()
{
  return new Object();
}

let foo = 0;

module.exports.getObject = getObj; // Makes the getObj function available to other units
module.exports.myVar = foo; // Makes the foo variable available to other units

The name you use to assign an item to the object is the alias you will use to call the item.

Notes:

  • If you need an item only for exporting purposes, you can declare it only for the module.exports object. In this case, you will be able to access the item only via the exports object. For example:

    JavaScript

    JavaScript

    module.exports.getObject = function () {return new Object;}

  • You can omit the module prefix when exporting items. However, such exports may be reset, when you override the standard exports object (see Remarks).

Importing Items to Units

To import items to a unit, use the require(unitname) function (the items should be exported from the desired unit). This function returns the exports object of the specified unit.

Make sure the Unit name refers to the name of the unit in the current project. To use units from another project, you must import it first (see Calling Routines Declared in Another Project) and then specify its name.

To call an item, you should use the name specified for the exports object (not the item name specified in the declaration). For example, the code snippet below uses the objects exported above:

JavaScript

JavaScript

// [MainUnit]
var comUnit = require("CommonUnit");
function main()
{
  let obj = comUnit.getObject(); // Calls the getObj function from CommonUnit
  let bar = comUnit.myVar; // Gets the foo variable of CommonUnit
}

Remarks

In TestComplete, you can also specify a custom exports object. To do this, use the following format:

JavaScript

JavaScript

module.exports = { exportedFuncName : myFunction,
                   exportedVarName : myVariable,
                   ...};

But this approach has the following important specifics:

  • It resets all the previous exports.

  • It resets all the exports declared without the module prefix.

JavaScript

JavaScript

function foo()
{
  //Do something
}

// Will not be exported
module.exports.foo_1 = foo;
exports.foo_2 = foo;

// Specifying a custom exports object
module.exports = {foo_3: foo};

module.exports.foo_4 = foo; // Will be exported
exports.foo_5 = foo; // Will not be exported

Legacy Support for Useunit

The USEUNIT keyword is supported by JavaScript. So, most likely, your JScript units converted to JavaScript will work fine. To learn about the difference between JavaScript and JScript, see JavaScript for JScript Users.

Reference to Another Unit

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

JavaScript

JavaScript

// To refer to a single unit
//USEUNIT UnitName

// To refer to multiple units
//USEUNIT UnitName1
//USEUNIT UnitName2

There must be no spaces at the beginning of the line before the // characters, between these characters and before 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 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 with any of the following code instructions is correct:

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

MyExtUnit.MyVariable
MyVariable

MyExtUnit.MyConstant
MyConstant

However, you must specify the name of the unit you refer to 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.

  • When you assign a value to a variable declared in another unit. Otherwise, the value will be assigned to a new variable in the current unit.

To call a routine defined in an external unit 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.

JavaScript

JavaScript

// 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:

JavaScript

JavaScript

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

Important Notes

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

  • To use JavaScript prototype methods from referenced units, you need to create wrapper functions for them. For details, see JavaScript - Specifics of Usage.

  • 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:

    JavaScript

    JavaScript

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

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

  • If you refer to 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.

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