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.

In this topic:

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_installdir>\bin\PackagesToLoad folder.

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

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

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:

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 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.

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.

Back to top

Use the jQuery libraries provided with UFT One

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

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

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

                            <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 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.

Back to top