Designing JavaScript functions for your toolkit support set

As part of the toolkit support set, you design JavaScript functions that UFT 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 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:

_util object

Use the _util utility object methods to use to instruct UFT 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 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);
}

Back to top

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 installation and provide browser-independent functions.

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 extensiblity library from your website by wrapping the jQuery namespace, as follows:

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

For more details, see:

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 will correctly access the document object on both Internet Explorer and Mozilla Firefox.
  • document will correctly access 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.

Back to top

Call functions from external JavaScript libraries

In the JavaScript functions that you design, call any JavaScript function included in the Web page that UFT is testing. However, when your toolkit support is loaded, UFT 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 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 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:

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 can only connect to the JavaScript engine if UFT is opened before the browser. Therefore, your global JavaScript variables are accessible until either the browser or UFT is closed.

Back to top

Use the jQuery libraries provided with UFT

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

Note: In UFT versions 14.50 and earlier, the JQuery version is 1.3.2. In UFT 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 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 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.

Back to top

Handle exceptions

If the JavaScript function that you design throws an exception, UFT 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 displays includes the line of code that threw the exception.

If the message uses formatting to include a variable in the string, the run-time error does not include the line of code.

Back to top