Designing JavaScript functions for your toolkit support set

As part of the toolkit support set, you design JavaScript functions that UFT One calls. The JavaScript Function Reference describes the JavaScript functions you implement.

Supported conventions, utility objects and global functions

The Web Add-in Extensibility API provides the following elements for you to use in your JavaScript functions:

_elem. token

The _elem token represents the Web element that UFT One is currently handling.

In identification functions, the _elem token represents the HTML element being learned.

In all other contexts, it represents the root element of the custom control. These contexts include:

Event handlers and event registration functions.
Functions for returning base elements, property values, and lists of possible values.
Filter functions.
For example, the following JavaScript function returns the value of the id identification property of the current Web element:
```
function get_property_value(prop)
{
    if (prop == "id")
    {
        return _elem.id;
    }
}
```

_util object

Use the _util utility object methods to use to instruct UFT One to perform different operations.

Global JavaScript functions, constants, and variables

Global JavaScript functions and constants are defined in the common.js file located in the <Extensibility Accelerator installation folder>\bin\PackagesToLoad folder.

This file is also located in the <UFT One installation folder>\dat\Extensibility\Web\Toolkits folder.

Tip: As a best practice, create one JavaScript file for each test object class.

However, if you want to call the same JavaScript function from JavaScript functions of multiple test objects, store these global functions in a separate file. Then, use this separate file as the toolkit support set's common JavaScript file.

To do this, specify the path of the common JavaScript file in the Controls\Settings\Variable element in the toolkit configuration file.

Window object

The window object provides access to the Window object that corresponds to the Web browser window you are testing.

Use this object to access objects and functions that reside in the browser namespace and manage the controls for which you are creating support.

For example, if a web page contains a global JavaScript function getTree(). This function returns a Tree object that manages a specific tree control, and has Collapse, Expand, and Select methods.

You could write the following JavaScript method to support running a Collapse test object method:

function Collapse (treeBranch)
{
   var tree = window.getTree(_elem);
   tree.Collapse(treeBranch);
}

Create browser-independent support

Use one or more of the following methods to enable your toolkit support set to work smoothly on different browser types and versions:

Treat controls different in different browsers

If you need to treat a control differently in different browsers, call the GetBrowserType or GetBrowserVersion utility methods to retrieve the relevant browser information.

Use external functions

Use functions from external browser-independent JavaScript function libraries, such as jQuery, to create code that can run smoothly on different types and versions of browsers.

The jQuery and jQuery.simulate libraries are included with the UFT One installation and provide browser-independent functions.

Use jQuery function calls to retrieve information and perform operations.
Use jQuery.simulate function calls to handle dispatching events.

For example, if you need to perform a click operation on your control, one line of code that uses jQuery would replace a complex block of code that sends the event differently, depending on the current browser.

In such cases, replace a complex block of code, such as:

if ( _util.GetBrowserType()==QtpConstants.FireFox)
{
    var myEvent = window.document.createEvent("MouseEvents")
    myEvent.initEvent("click", true, true)
    _elem.dispatchEvent(myEvent)
}
else
    _elem.click();

With one of the following JQuery code syntaxes:

In UFT versions 14.50 and earlier

Call the JQuery library as follows:

$(_elem).simulate("click");

In UFT versions 14.51 and later

Do one of the following:

Call a native JQuery library as follows:
$(_elem).simulate("click");
Isolate the web extensibility library from your website by wrapping the jQuery namespace, as follows:
_uft.$(_elem).simulate("click");

For more details, see:

http://jquery.com/
https://github.com/jquery/jquery-simulate
Call functions from external JavaScript libraries
Use the jQuery libraries provided with UFT One

Browser-specific modifications

Even if your code is designed to be browser-independent, each browser works using different logic, so validate your scripts on all browsers.

For example, you may need to perform the following modifications:

Mozilla Firefox

In JavaScript functions that need to run on Mozilla Firefox, you must explicitly use the window object to access any item in the global namespace.

For example:

window.document correctly accesses the document object on both Internet Explorer and Mozilla Firefox.
document correctly accesses the document object only on Internet Explorer

Chrome

Identifying controls using a <body> tag

If you identify a control using the <body> tag, and the <body> is a child of an <iframe> that has a blank or about:blankSRC value, then UFT can identify the control only in Chrome 37 and later.

Custom controls with two or more siblings

In Chrome, if a custom control is comprised of two or more sibling controls, you must include both of them in the identification of the object.

For example, this may be relevant if your custom control is comprised of an edit box and its adjacent submit button or a check box and its label.

For a code sample, see Example: Using Sibling Controls to Identify an Object.

Call functions from external JavaScript libraries

In the JavaScript functions that you design, call any JavaScript function included in the Web page that UFT One is testing. However, when your toolkit support is loaded, UFT One can call your code on any web page opened in a browser.

To ensure that your own JavaScript libraries can be used even on pages that do not include them, instruct UFT One to inject the library into every page. We recommend designing your JavaScript library so that it will only be loaded if it is not already included in the Web page.

Example: When learning objects on a web page, UFT One might call the identification function you designed, even if the page doesn't contain any of your controls, and does not include your function library.

Do the following:

Specify the file system path to the library in the JSLibrariesToInject\JSLibrary element in the toolkit configuration file.
When you deploy the toolkit support set to UFT One, make sure that the JavaScript libraries you reference are located in the paths that you specified in the toolkit configuration file.

Global JavaScript variables

When you define global variables in your JavaScript function, the variables exist in the scope of the JavaScript engine running in the browser.

UFT One can only connect to the JavaScript engine if UFT One is opened before the browser. Therefore, your global JavaScript variables are accessible until either the browser or UFT One is closed.

Use the jQuery libraries provided with UFT One

The UFT One installation includes the JQuery and JQuery.simulate libraries, in the <UFT One installation folder>\bin\JSFiles

Note: In UFT One versions 14.50 and earlier, the JQuery version is 1.3.2. In UFT One versions 14.51 and later, the JQuery library is isolated, and uses JQuery version 1.12.4.

If errors occur due to conflicting jQuery libraries, we recommend you upgrade your toolkit using UFT 14.51 or later.

To call the jQuery library functions from your JavaScript functions, specify the library locations in your toolkit configuration file.

UFT One versions 14.50 and earlier

<Controls> 
    <JSLibrariesToInject>
        <JSLibrary path="INSTALLDIR\bin\JSFiles\jQuery-1.3.2.js" /> 
        <JSLibrary path="INSTALLDIR\bin\JSFiles\jQuery.simulate.js" /> 
    </JSLibrariesToInject> 
</Controls>

UFT One versions 14.51 and later

<Controls> 
    <JSLibrariesToInject>
        <JSLibrary path="INSTALLDIR\bin\JSFiles\jQuery-1.12.4.js" /> 
        <JSLibrary path="INSTALLDIR\bin\JSFiles\jQuery.simulate-1.12.4.js" /> 
    </JSLibrariesToInject> 
</Controls>

These jQuery libraries are designed so that they are not loaded into the Web page if the page already includes some version of the library.

Handle exceptions

If the JavaScript function that you design throws an exception, UFT One displays a run-time error message and the test step fails. The message that you provide with the exception is added to the test report details for the failed step.

If you want to add a message to the run results that the step failed, but not cause a run-time error, call the _util.Report method from your JavaScript function.

Note: If the message you include in the exception is a simple string, the run-time error that UFT One displays includes the line of code that threw the exception.