This object's methods provide information about the browser being used.

This function returns the name of the browser which is being used for running the test.

This function returns the type of the browser which is being used for running the test. The type can have one of the following values:

This class provides the API for HTML anchor elements (hyperlinks). This class inherits the HTML_Object Class (Section 14.10.24).

This function clicks this anchor (hyperlink), as if the user had clicked it.

This class represents a JavaScript array, such as those returned by web functions like HTML_Document.getElementsById and HTML_Document.getElementsByTagName. This class inherits the HTML_Object Class (Section 14.10.24).

This function returns the element at position index in the array. Valid index positions are in the range 0 to array.length - 1.

This read-only property holds the number of elements in the array. This will be 0 if the array is empty.

This class provides the API for HTML button and submit input elements. This class inherits the HTML_ButtonBase Class (Section 14.10.5) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

For normal buttons, this is the same as calling HTML_ButtonBase.click. For submit buttons, this invokes the button's form's submit action.

This is the base class of all the HTML input button elements—such as, button, submit, radio, checkbox, and image—and provides the common API shared by all of them. This class inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

Clicks this button (or checkbox, or image, and so on), as if the user had clicked it. (Some subclasses allow keyboard modifiers and the precise position where the element is clicked to be specified.)

This property holds this button's (or checkbox's, or image's, and so on's), value as a string.

This class provides the API for HTML checkbox input elements. This class inherits the HTML_ButtonBase Class (Section 14.10.5) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This property holds true if this checkbox is checked; otherwise it holds false.

Clicks this checkbox as if the user had clicked it. All the arguments are optional. See Web Object API Function Parameters for which values are valid for the modifierState. The x and y are the checkbox-relative coordindates of the click.

This class provides an API to support calendar events: it provides four useful properties. This class inherits the HTML_Object Class (Section 14.10.24).

Note that for properties of type DateTime Type (Section 14.3.15.1), the time resolution is to the nearest minute (i.e., the seconds are always zero).

This read/write property holds a description of the event as a string (which may be empty).

This read/write property holds the DateTime Type (Section 14.3.15.1) when the event is due to end.

This read/write property holds the DateTime Type (Section 14.3.15.1) when the event is due to start.

This read/write property holds the title of the event as a string.

See also, Calendar Event Support (Section 14.10.36.6.3).

This class provides an API to support web calendar widgets that includes one useful property and two methods. This class inherits the HTML_CustomItemView Class (Section 14.10.14) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This read/write property holds the calendar's current date as a DateTime Type (Section 14.3.15.1). Note that the time resolution is to the nearest minute (i.e., the seconds are always zero.

Returns the number of HTML_CalendarEvent Class (Section 14.10.7)s that are visible in the view.

Returns the index-th HTML_CalendarEvent Class (Section 14.10.7) of those that are visible in the view.

See also, Calendar View Support (Section 14.10.36.6.4).

This class provides the API for HTML color picker elements. This class inherits the HTML_Object Class (Section 14.10.24).

This read-only property holds the text of the field's label if available.

This read–write property holds whether the color picker is enabled.

This read–write property holds the color picker's color as an HTML-formatted string of the form "#RRGGBB"; see the chooseColor function.

This class provides an API to support web toolkits that use highly customized buttons (e.g., those created using <div> or <span> HTML elements rather than <input> elements). The API is very similar to that provided by the HTML_Button Class (Section 14.10.4). This class inherits the HTML_CustomButtonBase Class (Section 14.10.11) (which provides most of the class's properties) and the HTML_Object Class (Section 14.10.24).

See also, Button Support (Section 14.10.36.6.1).

This read/write property holds a toolkit-specific data value for the button. (This is not the same as the HTML_CustomButtonBase.text property.)

This class provides an abstract API to support web toolkits that use highly customized buttons (e.g., those created using <div> or <span> HTML elements rather than <input> elements). The API is very similar to that provided by the HTML_Button Class (Section 14.10.4). This class inherits the HTML_Object Class (Section 14.10.24).

See also, Button Support (Section 14.10.36.6.1).

This read/write property indicates whether the button is disabled (true) or enabled (false).

This read/write property indicates whether the button shows text (true) or an image (false).

This read/write property holds the text shown on the button if the showText property is true; otherwise it holds an empty string.

This read/write property holds the button's tooltip text (which may be empty).

This read–only property indicates whether the button is visible in the web page.

This class is designed to support web toolkits that implement highly customized comboboxes (e.g., those that use <div> or <span> elements rather than the standard <select> element) in extensions. The API is similar to the one for the HTML_Select Class (Section 14.10.27). This class inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

See Combobox Support (Section 14.10.36.6.2) for how to add support for custom comboboxes.

This function returns true if the combobox contains the given option.

This read/write property holds the currently selected option's text.

This class provides an abstract item API to access any supported item type contained in a custom item view (HTML_CustomItemView Class (Section 14.10.14).) This item class inherits the HTML_Object Class (Section 14.10.24). (See How to set up Support for Complex Widgets (Section 14.10.36.5) for how this API can be used to support those custom item view widgets which Squish doesn't support as standard.)

Here are some quick links to the HTML_CustomItem class's methods and properties:

Returns a reference to this item's first child item (of type HTML_CustomItem Class (Section 14.10.13)) or returns 0 if there isn't one.

The column is optional (and not all item's support it), but if it is specified (and supported), then the item's first child item in the given column is returned if there is one; otherwise 0 is returned.

This read-only property holds the item's column or -1 if this property isn't supported by the relevant HTML extension.

This function returns a reference to the child item at the given row and column. If the item isn't found or if the extension doesn't support this function, the function returns 0.

This function returns a reference to this item's handle (as type HTML_Object Class (Section 14.10.24)), or returns 0 if this item doesn't have an item handle.

This function returns the view (of type HTML_CustomItemView Class (Section 14.10.14)) that contains this item.

Returns a reference to this item's next “sibling” item (of type HTML_CustomItem Class (Section 14.10.13)); or returns 0 if there isn't one.

The column is optional (and not all item's support it), but if it is specified (and supported), then the function returns the item in the given column in the following row; or 0 if there isn't one.

This read-only property holds the how many immediate child items this item has (for items in tree views). The value will be 0 if the item has no children (or the item isn't in a tree view), and -1 if this property isn't supported by the relevant HTML extension.

This property holds true if this item is open (i.e., expanded—in which case this item's children will be visible); otherwise it holds false.

If this property is set to true, it opens (expands) this item so that any children it has become visible. And if this property is set to false, it closes (collapses) this item so that any children it has become hidden.

Returns a reference to this item's parent item (of type HTML_CustomItem Class (Section 14.10.13)); or returns 0 if there isn't one, that is, if this is the root item.

The column is optional (and not all item's support it), but if it is specified (and supported), then the item's parent item for the given column is returned if there is one; otherwise 0 is returned.

This read-only property holds the type name of the actual (i.e., real) type wrapped by this API as a string. The name could be the view's type name rather than the item's type name, depending on the implementation. (The example shipped with Squish returns the view's type name.)

The type name returned might be, for example “gwttree”, or “itmilltree”, or “dojotree”, and so on.

This read-only property holds the item's row. For items in tree views the row is relative to the view for a top-level item or relative to the item's parent otherwise. For items not in tree views it is the item's row in the view. The value could be -1 if this property isn't supported by the relevant HTML extension.

This property holds true if this item is selected; otherwise it holds false.

If this property is set to true this item is selected. If this property is set to false this item is deselected.

This read-only property holds the item's text as a string.

If the extension provides an itemText function, that function's return value is returned; otherwise the item's innerText property's value is returned.

This class provides an abstract item view API to access any supported item view, that is, any DHTML/AJAX/JS item view widget with dedicated support. This class inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24). (See How to set up Support for Complex Widgets (Section 14.10.36.5) for how this API can be used to support those custom item view widgets which Squish doesn't support as standard.)

The API for the items in the item view is provided by the HTML_CustomItem Class (Section 14.10.13).

The itemText used in many of the methods listed below identifies the relevant item. In the example shipped with Squish, the itemText is always the item's text as a string.

Here are some quick links to the HTML_CustomItemView class's methods and properties:

Returns a reference to the view's first item (of type HTML_CustomItem Class (Section 14.10.13)); or returns 0 if the view is empty.

The column is optional (and not all view's support it), but if it is specified (and supported), then the view's first child item in the given column is returned if there is one; otherwise 0 is returned.

Clicks the expand/collapse handle of the item called itemName.

This function clicks the item with the given itemName text or the item at the given row and column. If the item isn't found or if the extension doesn't support this function (some only support the itemName version), the function does nothing.

Returns the view's caption for the given column.

Double-clicks the item called itemName. See Web Object API Function Parameters for which values are valid for the optional modifierState.

This function returns a reference to the item (of type HTML_CustomItem Class (Section 14.10.13)) with the given itemName or at the given row and column. If the item isn't found or if the extension doesn't support this function (some only support the itemName version), the function returns 0.

This function returns true if the view has an item called itemName; otherwise it returns false.

This function returns true if the view has an item called itemName, and the item is open (i.e., any child items it has are visible); otherwise it returns false.

This function returns true if the view has an item called itemName, and the item is seleced; otherwise it returns false.

This read-only property holds the number of columns displayed in the view.

This read-only property holds the number of rows displayed in the view. For tree views this is the number of top-level children. Not all extensions support this property, in which case its value is -1.

This read-only property holds the type name of the actual (i.e., real) type wrapped by this API as a string.

The type name might be, for example, “gwttree”, or “itmilltree”, or “dojotree”, and so on.

This class represents a date picker object and provides a useful property. This class inherits the HTML_Object Class (Section 14.10.24).

This read/write property holds the date chooser's current date/time as a DateTime Type (Section 14.3.15.1).

See the chooseDate function and also, Date Picker Support (Section 14.10.36.6.6).

This class represents a web page's HTML document object and provides useful accessor methods. This class inherits the HTML_Object Class (Section 14.10.24).

This function returns an array of all the DOM tree's elements that have the given id. (See also, HTML_Array Class (Section 14.10.3).)

This function returns an array of all the DOM tree's elements that have the given tagName. (See also, HTML_Array Class (Section 14.10.3).)

This class represents a web page's HTML expandable section header element. (Expandable sections are sometimes called “accordions” or “toolboxes”.) The class provides some useful properties and inherits the HTML_Object Class (Section 14.10.24). See also, the toggleExpandable function and Expandable Section Header Support (Section 14.10.36.6.7).

This read–write property holds whether the expandable section is enabled.

This read–write property holds whether the expandable section is expanded.

This read–write property holds the expandable section's title text.

This class provides the API for a web page's HTML form elements. This class inherits the HTML_Object Class (Section 14.10.24).

Invoke's the form's “submit” action.

This class is the base class for HTML form elements such as buttons, checkboxes, and so on, and provides the common API shared by all these elements. This class inherits the HTML_Object Class (Section 14.10.24).

This property holds true if this form element is disabled; otherwise it holds false.

Gives the keyboard focus to this form element.

This read-only property holds the name of this form element's type (such as, button, select, text, etc.).

This class provides the API for HTML image input elements—its methods are all inherited from its base classes. This class inherits the HTML_ButtonBase Class (Section 14.10.5) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This class provides the API for HTML menus and menubars. This class inherits the HTML_Object Class (Section 14.10.24) and in addition, has its own property and methods. See Menu Support (Section 14.10.36.6.8) for how to add support for custom menus.

This function returns the first HTML_MenuItem Class (Section 14.10.23) whose icon has the given iconUrl or a null value if there isn't one. (The null value can be tested for using the isNull function.)

This function returns the first HTML_MenuItem Class (Section 14.10.23) with the given text or a null value if there isn't one. (The null value can be tested for using the isNull function.)

This function returns the HTML_MenuItem Class (Section 14.10.23) at the given index position or a null value if there isn't one. (The null value can be tested for using the isNull function.)

This read-only property holds the count of how many menu items are in the menu (or menubar).

This class provides the API for HTML menu buttons. This class inherits the HTML_CustomButtonBase Class (Section 14.10.11) (which provides most of the class's properties) and the HTML_Object Class (Section 14.10.24). In addition, this class has its own method. See Menu Button Support (Section 14.10.36.6.9) for how to add support for custom menu buttons.

This function returns the HTML_Menu Class (Section 14.10.21) that is popped up when this button is clicked or a null value if there isn't one. (The null value can be tested for using the isNull function.)

This class provides the API for HTML menu items. This class inherits the HTML_Object Class (Section 14.10.24) and in addition, has its own properties and methods. See Menu Item Support (Section 14.10.36.6.10) for how to add support for custom menu items.

This read/write property holds the URL of the menu item's icon or an empty string if the item doesn't have an icon.

This read/write property holds whether the menu item is checked.

This read/write property holds whether the menu item is enabled.

This read/write property holds whether the menu item is just a menu item separator.

This function returns the HTML_Menu Class (Section 14.10.21) (i.e., the menu or menubar) that this menu item is contained in.

This function returns the HTML_Menu Class (Section 14.10.21) attached to this menu item or a null value if there isn't one. (The null value can be tested for using the isNull function.)

This read/write property holds the menu item's text.

This is the ultimate base class used for all objects that are HTML elements. The functions and properties defined in this class are available for all objects which are returned from Squish's findObject function.

Here are some quick links to the HTML_Object class's methods and properties:

This function returns the subclass name of the HTML object; for example, HTML_Button Class (Section 14.10.4). (See also, HTML_Object.domClassName.)

This read-only property holds the object's class name that is used by the DOM. (See also, HTML_Object.className.)

Evaluates the XPath statement and returns an HTML_XPathResult Class (Section 14.10.35) object. The XPath statement is executed relative to this HTML_Object's XPath.

This method makes it possible to efficiently operate on a web application's DOM document, for example, to retrieve elements and access their properties.

See also How to Use XPath (Section 13.3.2).

This function returns the object's first child (as an HTML_Object), or an invalid object if the object has no children. (See also, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.numChildren, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This read-only property holds the object's height. (See also, HTML_Object.width.)

This function returns this object's hierarchical, qualified name.

This read-only property holds the object's ID.

This read-only property holds the object's inner text—this might contain HTML markup. (See also, HTML_Object.innerText.)

This read-only property holds the object's inner text as plain text, so the returned string does not contain any HTML markup. (See also, HTML_Object.innerHTML.)

Invokes an HTML_Object method called methodName, and returns the value returned by the method call as a string. Both the argument1 and argument2 arguments are optional. If either or both are given it or they are passed as argument(s) to the method call.

This function returns the object's last child (as an HTML_Object), or an invalid object if the object has no children. (See also, HTML_Object.firstChild, HTML_Object.nextSibling, HTML_Object.numChildren, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This function returns this object's internal JavaScript reference name.

This function returns the object's next sibling (as an HTML_Object), or an invalid object if the object has no following sibling. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.numChildren, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This read-only property holds how many children this object has—this could be 0. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This function returns the object's parent object (as an HTML_Object), or an invalid object, if this object has no parent. Note that only a web site's document node has no parent; all other nodes are children of the document or of other nodes within the document. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.numChildren, and HTML_Object.previousSibling.)

This function returns the object's previous sibling (as an HTML_Object), or an invalid object if the object has no preceding sibling. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.numChildren, and HTML_Object.parentElement.)

This function returns the value of the property called name as a string. (The returned value is always a string even if the property was set to an integer or Boolean.) (See also, HTML_Object.setProperty.)

Sets the property called name's value to value. The value may be a string, integer, or Boolean. (See also, HTML_Object.property.)

This function returns an HTML_Style Class (Section 14.10.29) object that can be used to query this object's CSS (Cascading Style Sheet) attributes.

This read-only property holds the object's style.display value.

This function returns the object's style.visibility value.

This read-only property holds the object's HTML tag name, for example, DIV or INPUT.

This read-only property holds the object's title.

This read-only property holds true if the object has a visible attribute otherwise it holds false. See the HTML_Object.styleDisplay property and the HTML_Object.styleVisibility and HTML_Object.style functions for other ways of checking the object's visibility.

This read-only property holds the object's width. (See also, HTML_Object.height.)

This read-only property holds the object's x-coordinate.

This read-only property holds the object's y-coordinate.

This class provides the API for HTML option elements which provide the contents of selection elements. This class inherits the HTML_Object Class (Section 14.10.24). (See also, HTML_Select Class (Section 14.10.27).)

This read-only property holds true if this option is selected by default; otherwise it holds false.

This property holds the 0-based index position of this option in the selection element.

This read-only property holds true if this option is selected; otherwise it holds false.

This property holds this option's text as a string.

This property holds this option's value as a string.

This class provides the API for HTML radio button input elements. This class inherits the HTML_ButtonBase Class (Section 14.10.5) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This property holds true if this radio button is checked; otherwise it holds false.

Clicks this radio button as if the user had clicked it. All the arguments are optional. See Web Object API Function Parameters for which values are valid for the modifierState. The x and y are the radio button-relative coordindates of the click.

This class provides the API for HTML selection input elements (select and select-one). Web browsers normally render select elements as list boxes and select-one elements as comboboxes. This class inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This function returns true if this selection element is a multi-selection (type select); otherwise it returns false (meaning that this element is of type select-one).

Returns the option (HTML_Option Class (Section 14.10.25)) at position index in this selection element. (The indexing is 0-based.)

This is a convenience function equivalent to html_select_object.options().at(index).

This function returns an array (HTML_Array Class (Section 14.10.3)) of all the options (as HTML_Option Class (Section 14.10.25) objects) contained in this selection element.

This property holds this selection element's selected index. (This property is only really useful for single selection boxes, that is, those of type select-one.)

This property holds the selected option's text, or if this is a select (multi-selection) element, holds a string that contains a comma-separated list of the selected options' texts.

If this property is assigned to, it sets the option which has the same text as the given text to be selected.

If this is a select (multi-selection) element, the text string can specify a list of option texts by separating each one with a comma. In such cases, every option that has a text that matches one of the texts in the comma-separated list will be selected.

This class provides the API for HTML progress bars to enable their state to be verified. This class inherits the HTML_Object Class (Section 14.10.24). See also Progress Bar Support (Section 14.10.36.6.11).

This read–only property holds the progress bar's maximum value.

This read–only property holds the progress bar's minimum value.

This read/write property holds the progress bar's value. The value should be an integer between the minimum and the maximum inclusive.

This class provides the API for accessing an object's CSS (Cascading Style Sheet). HTML_Style objects are returned by the HTML_Object.style function. This class inherits the HTML_Object Class (Section 14.10.24).

This function returns the string value of the CSS (Cascading Style Sheet) attribute with the given name, or an empty string if there is no element called name.

When it comes to composite attributes (such as background-color), Squish adopts the widely-used JavaScript convention of capitalizing the letter following a hyphen and then dropping hyphens. So, for example, to access the background color, we would write something like:

var style = myobject.style();
var bgColor = style.value("backgroundColor");

This class provides the API for HTML tab widget tabs. This class inherits the HTML_Object Class (Section 14.10.24). Every tab belongs to a tab widget of type HTML_TabWidget Class (Section 14.10.31).

This read/write property holds whether the tab is enabled.

This read/write property holds the URL of the tab's icon if it has one. If the tab doesn't have an icon then the property holds an empty string.

This read/write property holds the tab's title text.

This class provides the API for HTML tab widgets. This class inherits the HTML_Object Class (Section 14.10.24). Each tab in the tab widget is of type HTML_Tab Class (Section 14.10.30).

This function clicks the tab with the given tab title text (if there is one). Normally this will cause the clicked tab to come to the front.

This function returns a reference to the tab with the given tab title text as an object of type HTML_Tab Class (Section 14.10.30). If there is no such tab the function returns a null value for which the Squish isNull function returns a true value.

This function returns a reference to the currently active tab as an object of type HTML_Tab Class (Section 14.10.30).

This class provides the API for HTML text input elements. All the class's API is inherited from its base classes. This class inherits the HTML_TextBase Class (Section 14.10.34) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This class provides the API for HTML textare input elements. All the class's API is inherited from its base classes. This class inherits the HTML_TextBase Class (Section 14.10.34) which inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This is the base class for HTML text input elements (text and textarea), and provides methods common to both. This class inherits the HTML_FormElement Class (Section 14.10.19) which inherits the HTML_Object Class (Section 14.10.24).

This property holds this text or textarea's text as a string.

This is the type of the result object returned when an XPath is evaluated. This class inherits the HTML_Object Class (Section 14.10.24) .

When evauating an XPath statement on any HTML_Object Class (Section 14.10.24) (see HTML_Object.evaluateXPath), an object of type HTML_XPathResult is returned. This object contains the results of the XPath execution.

See also How to Use XPath (Section 13.3.2).

This read-only property holds the XPath result as Boolean value.

This read-only prototype holds the XPath result as a numerical value.

This function returns the first node (of type HTML_Object Class (Section 14.10.24)) of the node list if the result of the XPath execution was a node list.

This read-only property holds the number of nodes returned by the XPath execution. A value of -1 means that no node list has been returned.

This read-only property holds the XPath result as string value.

This function returns the node (of type HTML_Object Class (Section 14.10.24)) at the given index position in the node list if the result of the XPath execution was a node list.

This section shows how to use the JavaScript extension API to support the testing of custom AJAX/DHTML/JavaScript widgets.

Squish provides access to Web DOM elements, giving tests the potential for complete low-level access and control. However, working at this level is the Web equivalent of using hard-coded screen coordinates when testing GUI applications—that is, it is a rather fragile approach.

To create robust test scripts, a test framework and the automated tests should interact with the application and the HTML on high-level widgets, instead of interacting with low-level DOM elements. This way tests work on an abstract GUI level without needing any knowledge of the application's internals (i.e., without needing to directly access the application's DOM).

The advantage of using high-level tests which work on widgets rather than directly on the DOM, is that the tests will not break just because the DOM representation or widget implementation changes. And such changes are quite common as applications, and the frameworks they use, evolve.

So in addition to providing low-level access, Squish also provides a way of creating high-level tests that are likely to be a lot more reliable. This is possible because Squish comes with built-in support for popular AJAX and DHTML frameworks and recognizes their widgets. But given the amount of available AJAX, DHTML, and JavaScript frameworks and custom widgets that currently exist, and also the new ones that keep appearing, it is not possible for Squish to support all of them out-of-the box.

Fortunately, even those testing a Web framework that isn't currently supported by froglogic, can still add support for their framework to Squish. This is done by using Squish's JavaScript extension API which makes it possible to extend Squish's widget support to recognize custom AJAX, DHTML, and JavaScript widgets, to identify them properly, and to interact with them, and of course to make their APIs accessible to test scripts.

In this section we begin with the Squish Object API that is available to extension scripts, then we present an overview and examples that show you how to implement support for your custom widgets yourself. Alternatively, contact <squish@froglogic.com> if you want froglogic to implement the extension for your custom widgets or framework for you.

function typeOf(element)
{
    if (element.className == "span")
	return "button";
    return undefined;
}

if (Squish.hasClassName(element, "warning"))
    handleWarningElement(element)

if ((Squish.hasClassName(element, "heading") and
     Squish.hasClassName(element, "major")):
    # Both class names present
    handleMajorHeadingElement(element)
elif Squish.hasClassName(element, "heading"):
    # Only "heading" class name present
    handleHeadingElement(element)

Wrappers/Web/ExtensionScripts="C:\\squishext\\myextension.js"

<span class='ajaxbutton'>Click Me</span>

Squish.registerWidget({Class: "ajaxbutton", Event: "click"});

<SPAN class='menu' id='fileMenu'>
    <SPAN class='menuItem' menuID='fileOpen'>Open</SPAN>
    <SPAN class='menuItem' menuID='fileQuit'>Quit</SPAN>
</SPAN class='menu'>

Squish.registerWidget({Class: "menuItem", Event: "click"});

var myUiExtension = new Object;

myUiExtension.nameOf = function(obj) {
    if (obj.tagName == "SPAN" &&
        Squish.hasClassName(obj, "menuItem")) {
        var name = '{' +
            Squish.propertiesToName(obj, ["tagName", "menuID"]) +
            " parentID='" + obj.parentNode.id + "'" +
            " className='menuItem'" +
            "}";
        return escape(Squish.uniquifyName(name, obj));
    }
    return undefined;
}

Squish.addNameOfHook(myUiExtension.nameOf);

myUiExtension.matchObject = function(obj, property, valueObject) {
    if (property == "parentID")
	return Squish.matchProperty(valueObject, obj.parentNode.id);
    return undefined;
}

Squish.addMatchObjectHook(myUiExtension.matchObject);

14.10.36.5. How to set up Support for Complex Widgets

Using the extension mechanism it is also possible to add dedicated support for complex widgets—that is, widgets which contain items—such as tree widgets, tables, menus, calendar controls, and other item-based widgets. (For example, trees contain nodes, tables contain cells, menus contain items, and calendars contain date cells.) We will generally refer to such complex widgets as “item views”, and will often refer to their nodes, cells, and items, simply as “items”.

To make high-level interactions with such widgets possible, user actions such as mouse clicks on cells or items, and expanding and collapsing tree nodes, must be recognized and replayed—and in a way that is independent of the underlying HTML representation. In addition, certain states and properties, such as the current selection, ought to be queryable from test scripts, to allow for robust and automatic verifications.

Using the item and item view abstractions and the necessary JavaScript hooks and APIs, Squish supports the addition of any custom item view DHTML/AJAX/JS widget so that test scripts can access the widget's and its items' states, properties and functions.

This section explains how to implement such dedicated item view support so that Squish will correctly be able to record test scripts using custom item views and accurately replay such tests. This is done by using Squish's JavaScript extension API.

We will illustrate the explanation by using an example AJAX widget—the tree control from Google's Web Toolkit (GWT). We will implement all the necessary support to properly record and replay clicks on items and item handles, to identify the tree and items independent of the DOM, and to allow querying the tree's selection.

Once the necessary hooks are implemented, calls to the clickItem function and to the clickTreeHandle function will be recorded when interacting with the supported item view widget. In addition, using the HTML_CustomItemView Class (Section 14.10.14) and HTML_CustomItem Class (Section 14.10.13) abstraction API, the test scripts will be able to access the widget and work with its items, states, and properties.

14.10.36.5.1. DOM structure of the widget

Before we can start implementing the necessary support, we need to look at the widget's DOM structure since our custom support will use the Web application's DOM internally to provide the abstraction and encapsulation that test scripts will rely on.

Below is a screenshot of the GWT Tree widget as it appears in a Web browser:

The GWT Tree widget

The DOM hierarchy that GWT uses to represent this tree widget has the following structure (with irrelevant details, and most of the data, omitted):

<DIV class="gwt-Tree">
  <TABLE>
    <TR>
      <TD>
      <IMG src="tree_open.gif"/>
      </TD>
      <TD>
      <SPAN class="gwt-TreeItem">Beethoven</SPAN>
      </TD>
    </TR>
  </TABLE>
  <SPAN>
    <DIV>
    <TABLE>
      <TR>
        <TD>
        <IMG src="tree_closed.gif"/>
        </TD>
        <TD>
        <SPAN
class="gwt-TreeItem gwt-TreeItem-selected">Concertos</SPAN>
        </TD>
      </TR>
      </TBODY>
    </TABLE>
    </DIV>
    <DIV>
    <TABLE>
      <TR>
        <TD>
        <IMG src="tree_closed.gif"/>
        </TD>
        <TD>
        <SPAN class="gwt-TreeItem">Quartets</SPAN>
        </TD>
      </TR>
      </TBODY>
    </TABLE>
    </DIV>
  </SPAN>
...
</DIV>

So we can see that a tree widget is represented using a DIV element with the class name of gwt-Tree. The tree itself is contained inside this DIV element, in a TABLE.

Each tree item is held in a SPAN element that has a class of gwt-TreeItem. The item's text is the element's inner text, and selected items have an additional class of gwt-TreeItem-selected.

Item handles (typically shown as + or - symbols to indicate that the item can be expanded or is already expanded), are represented by an IMG element in the TD element above the item—specifically, the item's parent's previous sibling's first child. The IMG's src property can be used to determine if the item is expanded (src="tree_open.gif") or collapsed src="tree_closed.gif").

The relationship between the items (i.e., the actual tree structure), is modeled using nested SPAN elements which contain a set of siblings relative to their parent.

This information is sufficient for us to be able to detect a GWT Tree element, the tree's item elements, and the items' handles, in the web page's DOM structure. Armed with this knowledge we can create a high-level API that our test scripts can use to interact with a GWT Tree and its items, using Squish's uniform “item view” API.

Note that all the code used in the following subsections is taken from the file lib/extensions/web/jshook_gwt.js.

14.10.36.5.2. Hooks for recording high-level GUI operations

	Functions to implement in the toolkit's extension object
	eventObject typeOf nameOf

The first step is to implement the JavaScript hooks for recording high-level GUI operations on the GWT Tree. This means, if the user clicks an item, a clickItem(treeName, itemName) function call should be recorded. Similarly, a click on a tree item's handle should be recorded as clickTreeHandle(treeName, itemName).

To achieve this, we must implement three different hooks:

• Event object hook: A function that returns the DOM element that is the source of an event.

• Type of object hook: A function that returns a DOM object's high-level type name (as a string).

• Name of object hook: A function that returns a DOM object's Squish object name (as a string).

Once these functions are implemented, they must be registered with Squish so that they are called by Squish's event recorder. When Squish calls them, it will pass the event's DOM source object as an argument, and based on this we can decide whether we will respond or not. (We can safely ignore events we don't want to handle and leave them for Squish to deal with.)

For the GWT Tree when we implement these functions we must handle three different high-level objects:

• Tree objects

• Tree items

• Tree item handles

So for all three functions we need a way to determine which type of object we are dealing with. To do this we will start by defining a gwtExtension object to contain all the GWT Tree-related code we write. Then we'll define some constants, and then we will create a getType function.

JavaScript

var gwtExtension = new Object;

gwtExtension.Tree = 0;
gwtExtension.TreeItem = 1;
gwtExtension.TreeItemHandle = 2;

We will use these constants to distinguish between the objects we are interested in handling. Now we need a function that can match DOM class names to these constantts:

JavaScript

gwtExtension.getType = function(obj)
{
    if (Squish.hasClassName(obj, 'gwt-TreeItem'))
	return gwtExtension.TreeItem;
    else if (obj.tagName == 'IMG' &&
        (obj.src.indexOf('tree_open') != -1 || 
	 obj.src.indexOf('tree_closed') != -1) && 
        Squish.hasClassName(gwttreeExtension.itemOfHandle(obj),
                'gwt-TreeItem'))
	return gwtExtension.TreeItemHandle;
    else if (Squish.hasClassName(obj, 'gwt-Tree'))
	return gwtExtension.Tree;

    return undefined;
}

The custom getType function uses Squish's Squish.hasClassName function to see if the element is a tree item, and if it is, the appropriate constant is returned. Similar code is used to handle trees themselves, but for tree handles we must check that the tag is IMG and that it has one of the appropriate images and that the element associated with the image is an item with the correct class (gwt-TreeItem). We will see the creation of the gwttreeExtension object and of the gwttreeExtension.itemOfHandle function shortly.

If the element is not one of those we are interested in, we return undefined which indicates to Squish that it should try whatever type functions it hasn't yet tried, or to fall back on its own built-in functionality.

14.10.36.5.2.1. Event Objects

Now that we have a suitable getType function, it is quite easy to implement the three hook functions that are needed:

JavaScript

gwtExtension.eventObject = function(obj)
{
    if (!obj)
        return undefined;
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem: // fallthrough
    case gwtExtension.TreeItemHandle:
	return obj;
    }
    return undefined;
}

If the high-level object type is a tree item or a tree item's handle, we return this object. This tells Squish that the object is one we want to record events on, and so should not be ignored by the event recorder. As usual, if we don't recognize the object, we return undefined which tells Squish to handle it for us.

14.10.36.5.2.2. Object Types

If Squish encounters an object for which events should be recorded, it will need know the object's type. For this we must implement a suitable hook function:

JavaScript

gwtExtension.typeOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem:
	return 'custom_item_gwttree';
    case gwtExtension.TreeItemHandle:
	return 'custom_itemhandle_gwttree';
    case gwtExtension.Tree:
	return 'custom_itemview_gwttree';
    }
    return undefined;
}

The type names returned from this function follow a convention that must be followed! Squish provides a common item view abstraction, and for it to work correctly, we must return type names of the correct form.

14.10.36.5.2.3. Object Names

The three main components used by the item view API for custom trees, and that correspond to components that the DOM object represents, are items, handles, and views—a view is a list or table or tree widget. The naming convention we must follow for custom type names is very simple: Item type names must begin with custom_item_; Item handle type names must begin with custom_itemhandle_; and view type names must begin with custom_itemview_. The rest of the name must identify our custom view (so in this example, each type name ends with _gwttree).

The third hook function that we must implement returns the name of a specific high-level object:

JavaScript

gwtExtension.nameOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem:
	return escape(gwtExtension.nameOfTreeItem(obj));
    case gwtExtension.TreeItemHandle:
	return escape(gwtExtension.nameOfTreeItem(
                gwttreeExtension.itemOfHandle(obj)));
    case gwtExtension.Tree:
	return Squish.uniquifyName(gwtExtension.nameOfTree(obj), obj);
    }
	
    return undefined;
}

As usual, we tell Squish to handle any objects that we are not interested in by returning undefined.

This function makes use of two other functions, gwtExtension.nameOfTree and gwtExtension.nameOfTreeItem to create suitable real (multi-property) names for the custom objects. Here are their implementations:

JavaScript

gwtExtension.nameOfTree = function(obj)
{
    return '{' + Squish.propertiesToName(obj,
        ["tagName", "id", "name"]) + "className='gwt-Tree'}";
}

This function creates a unique name for each GWT Tree object that Squish encounters. (See How to Implement a Custom Name Generator (Section 14.10.36.4.1) for more information about creating names.)

Here is the function which generates a name for a tree item:

JavaScript

gwtExtension.nameOfTreeItem = function (obj)
{
    var tree = obj;
    while (tree && (!Squish.hasClassName(tree, 'gwt-Tree')))
	tree = tree.parentNode;
    var treeName = Squish.nameOf(tree); 
    var item = obj;
    return Squish.createItemName(treeName, item.innerText);
}

An item's name consists of the name of the item view containing the item (the tree widget) and the actual name of the item (usually the item's text—i.e., its innerText—is used).

First we find the tree widget that the item belongs to. This is done by going to the item's parent, and if that isn't the tree, the parent's parent, and so on until we get an object of class gwt-Tree. Once we have located the tree object, we can call the Squish.nameOf function to get its real (multi-property) name, and then use the Squish.createItemName function to generate a unique real name for the item; essentially, the same name as the tree's but with an additional property containing the item's text (which we get from the item's innerText).

Now that we have implemented all the necessary hook functions we must register them to make them take effect:

Squish.addNameOfHook(gwtExtension.nameOf);
Squish.addTypeOfHook(gwtExtension.typeOf);
Squish.addEventObjectHook(gwtExtension.eventObject);

With these hooks in place, if we now record events on a GWT Tree, the expected high-level operations will be correctly recorded.

14.10.36.5.3. Hooks for replaying high-level GUI operations

	Functions to implement in the view's extension object
	findItem itemHandle

Once the recording hooks are implemented and recording works, the next step is to implement the hooks to enable Squish to recognize and correctly replay the recorded GUI operations.

14.10.36.5.3.1. Find Item

To support replaying clicks on items (clickItem), only one additional function needs to be implemented. This function has to search for an item by name in the tree, and should return a reference to the DOM object representing the item. Squish will use this function to get the item to send click events to.

The name of this function has to follow a certain naming convention. In particular, it must be called findItem and it must exist as a function property of an object called typenameExtension where typename is exactly the same name as we appended to the type names of the objects in our typeOf hook function.

For the GWT Tree example we have typenames custom_item_gwttree and so on, so the name we must use is gwttree. This means that we have to create an object called gwttreeExtension and give it a findItem function, as the following code illustrates:

JavaScript

var gwttreeExtension = new Object;

gwttreeExtension.findItem = function(tree, name)
{
    var node = tree.firstChild;
    while (node) {
	if (node.firstChild) {
	    var node2 = gwttreeExtension.findItem(node, name);
	    if (node2) {
		return node2;
	    }
	}
	if (node.className &&
	    Squish.hasClassName(node, 'gwt-TreeItem') &&
	    Squish.cleanString(node.innerText) == name) {
	    return node;
	}
	node = node.nextSibling;
    }
    return undefined;
}

The tree is a reference to the tree DOM element and the itemText is the item's text (actually its innerText).

The function iterates through all child elements of the tree until it finds an element of class gwt-TreeItem whose innerText matches the requested item text.

14.10.36.5.3.2. Item Handle

For list and table widgets it is sufficient to provide a findItem function, but for tree widgets an additional function is required to deal with item handles.

For this purpose an itemHandle function must be implemented in the same object that returns the handle belonging to the given item. Here is an implementation of the function that works for GWT Tree items:

JavaScript

gwttreeExtension.itemHandle = function(node)
{
    return node.parentNode.previousSibling.firstChild;
}

This function returns the GWT Tree element that corresponds to an item handle (an IMG element in the TD element above the item—i.e., the item's parent's previous sibling's first child.)

The implementation of these two functions is all that's needed to enable the replaying of high-level operations on items and item handles.

14.10.36.5.4. Exposing the Item View API

	Functions to implement in the view's extension object
	itemText isItemSelected isItemOpen setItemSelected (see isItemSelected) setItemOpen (see isItemOpen) childItem (see Item Traversal) parentItem (see Item Traversal) nextSibling (see Item Traversal) itemView (see Item Traversal) numColumns (see Columns) columnCaption (see Columns)

For Squish to be able to detect an item view and its items, and be able to record and replay high-level GUI operations involving them, what we have done so far is sufficient.

But Squish's item view abstraction also provides the tester with APIs to iterate through the items and to query and set the selection and other properties. To support such functionality, various additional functions need to be implemented—all of which we will cover here, again providing examples based on the GWT Tree example.

14.10.36.5.4.1. Item Text

Squish's test script item-view API allows us to retrieve a tree item (e.g., using tree.findItem(...)), and to query the item's text property.

By default, Squish returns the item's innerText, but if this is inappropriate for the items you are working with you can implement your own itemText(item) function in the view's extension object, and which will then be called instead of Squish's default function for your items:

JavaScript

gwttreeExtension.itemText = function(item)
{
    return item.innerText;
}

If the typenameExtension has an itemText function property, Squish will call this function and pass a reference to the DOM object representing the relevant item. This principle applies to the other functions too: if we provide the function it is used for our extension types; otherwise Squish falls back to its own built-in functionality.

In this particular case (i.e., for GWT Tree items) there is no need to implement this function because Squish's built-in version returns the innerText anyway.

14.10.36.5.4.2. Item Selection

Squish's test script item-view API allows us to retrieve a tree item (e.g., using tree.findItem(...)), and to query the item's selected property.

To support the querying of an item's selection state, we must provide an isItemSelected function in the view's extension object. Here is an example that works for GWT Trees:

JavaScript

gwttreeExtension.isItemSelected = function(item)
{
    return Squish.hasClassName(item, "gwt-TreeItem-selected");
}

If the typenameExtension has an isItemSelected function property, Squish will call this function and pass a reference to the DOM object representing the relevant item.

To check if the item is selected we simply return true or false depending on whether one of the item's class names is gwt-TreeItem-selected.

Squish's item-view API also supports the changing of an item's selection state. This can be achieved by implementing a setItemSelected(item, selected) function in the same extension object. The item is a reference to the item's DOM object and selected is a Boolean value, with true meaning that the item should be selected and false meaning that it should be unselected.

14.10.36.5.4.3. Item Handle's State

Squish's test script item-view API allows us to access a tree item's handle and query it to see if the item is expanded (its children are visible) or collapsed (its children are hidden). The handle's state is held in the opened property, and to support this property we must implement an isItemOpened function in the tree's extension object. (Note that this functionality doesn't make sense for list or table views.)

Here is an example implementation for the GWT Tree:

JavaScript

gwttreeExtension.isItemOpen = function(item)
{
    try {
        var obj = item;
        while (obj && obj.tagName != 'TABLE') {
            obj = obj.parentNode;
        }
        if (!obj || !obj.nextSibling) {
            return undefined;
        }
        obj = obj.nextSibling;
        return Squish.isElementVisible(obj);
    }
    catch (_e) {
        return false;
    }
}

If the typenameExtension has an isItemOpen function property, Squish will call this function and pass a reference to the DOM object representing the relevant item.

Here, we simply retrieve the item's handle and return a Boolean that reflects whether it has the opened image.

Squish's item-view API also supports the changing of an item's expanded/collapsed state. This can be achieved by implementing a setItemOpen(item, expand) function in the same extension object. The item is a reference to the item's DOM object and expand is a Boolean value, with true meaning that the item should be expanded (opened) and false meaning that it should be collapsed (closed).

14.10.36.5.4.4. Item Traversal

The item view API also includes functions for traversing items in a tree view. The traveral functions are: childItem(treeOrItem), nextSibling(item), and parentItem(item). There is also an itemView(item) function; this returns the view that the given item is in.

Using these APIs it is possible to iterate over the items in a tree, and using the functions shown earlier, it is then possible to retrieve items' texts, select or unselect items, or expand or collapse items.

If we want our custom view to provide traversal then we must implement our own versions of these four functions as properties of our custom view's extension object. And, just the same as for the functions we have already discussed, if we create our own versions of these functions, Squish will call them and pass a reference to the DOM object representing the relevant item. Note that exceptionally, in the case of the childItem function, Squish might call it with either a tree or an item.

Here are implementations of these function for the GWT tree:

JavaScript

gwttreeExtension.childItem = function(parent)
{
    if (Squish.hasClassName(parent, "gwt-Tree")) {
        return gwttreeExtension._findFirstTreeItem(parent);
    } else {
	while (parent && parent.tagName != 'TABLE')
	    parent = parent.parentNode;
	if (!parent || !parent.nextSibling)
	    return undefined;
	parent = parent.nextSibling;
        return gwttreeExtension._findFirstTreeItem(parent);
    }
}

gwttreeExtension._findFirstTreeItem = function(baseNode)
{
    obj = Squish.getElementByClassName(baseNode,
            'gwt-TreeItem', 'SPAN');
    if(!obj) {
        obj = Squish.getElementByClassName(baseNode,
            'gwt-TreeItem', 'DIV');
    }
    return obj;
}

gwttreeExtension.nextSibling = function(node)
{
    node = node.parentNode;
    while (node && node.tagName != 'DIV')
        node = node.parentNode;
    if (!node || !node.nextSibling)
        return undefined;
    node = node.nextSibling;
    return gwttreeExtension._findFirstTreeItem(node);
}

gwttreeExtension.parentItem = function(node)
{
    node = node.parentNode;
    while (node && node.tagName != 'DIV')
	node = node.parentNode;
    if (!node || !node.parentNode || !node.parentNode.previousSibling)
	return undefined;
    node = node.parentNode.previousSibling;
    return gwttreeExtension._findFirstTreeItem(node);
}

gwttreeExtension.itemView = function(node)
{
    var obj = node;
    while (obj && (!Squish.hasClassName(obj, 'gwt-Tree')))
	obj = obj.parentNode;
    return obj;
}

The implementations are quite self-explanatory, especially if you look at the DOM structure that the GWT Tree uses. (Note though, that the GWT implementation has changed so we must account for both the old version and up to date versions—this is why we have the gwttreeExtension._findFirstTreeItem function.)

14.10.36.5.4.5. Columns

If the item view supports multiple columns, the functions columnCaption(view, column) and numColumns(view) can be implemented in the view's extension object to allow the test script to query the column information using the API calls with the same names through the item view API.

14.10.36.5.5. Testing and Conclusion

This concludes the coverage of the JavaScript Extension API. A couple of test scripts which use the GWT Tree APIs developed in this section can be found in the examples/web/suite_gwt suite.