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

	Note
	When using the Qt edition for applications using the QtWebKit module, the name of this object is SquishBrowserInfo in order to avoid clashes with objects provided by the application itself. So instead of Browser.name please use SquishBrowserInfo.name in test scripts that are being used with the Qt edition. The same applies to the other functions and properties provided by this object.

This function returns the name of the browser which is being used for running the test as a string value. Values for common browsers are:

This function returns the major version of the browser which is being used for running the test as an integer value.

This function returns the type of the browser which is being used for running the test as a number value. The returned type value should be compared to one of the following variables (each stands for the respective browser):

Example:

function main()
{
    // ...

    if (Browser.type() == Browser.InternetExplorer) {
        test.log("Using Internet Explorer!")
    }

    // ...
}

This class provides the API for the Tabs in the web browsers windows. Browser tabs can be identified using a multi-property name of the form {type='BrowserTab' title='AddressBook'}. Matching can be done on the BrowserTab.title or the BrowserTab.url property using either strict, wildcard or regular expression matching.

This read-only property holds the title of the web browsers tab.

This property holds the URL of the web browsers tab. Changing this property to a different URL will load the given URL in that browser tab and wait for the tab to be hooked up. Waiting for the hookup to succeed is limited by the Application Startup Time (or AUTTimeout) specified in the squishserver configuration. If you need more control over the timeout please consider using BrowserTab.setUrl.

This function closes the tab in the browser, possibly also closing the window if it is the last tab. After calling this function accessing the other properties on the same object will raise errors.

This function changes the url in the tab to the url and waits for the new page to be hooked by Squish. The time to wait can be specified using the timeout parameter and has to be specified in milliseconds.

This function is provided as an alternative for the BrowserTab.url property in cases where the timeout should be specified explicitly instead of using the value that the url property picks up.

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

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.getElementsByTagName. This class inherits the HTML_Object Class (Section 6.10.29).

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 6.10.6) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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 6.10.6) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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

Note that for properties of type DateTime Type (Section 6.3.21.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 6.3.21.1) when the event is due to end.

This read/write property holds the DateTime Type (Section 6.3.21.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 6.10.44.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 6.10.16) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

This read/write property holds the calendar's current date as a DateTime Type (Section 6.3.21.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 6.10.8)s that are visible in the view.

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

See also, Calendar View Support (Section 6.10.44.6.4).

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

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 6.10.5). This class inherits the HTML_CustomButtonBase Class (Section 6.10.12) (which provides most of the class's properties) and the HTML_Object Class (Section 6.10.29).

See also, Button Support (Section 6.10.44.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 6.10.5). This class inherits the HTML_Object Class (Section 6.10.29).

See also, Button Support (Section 6.10.44.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 6.10.32). This class inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

See Combobox Support (Section 6.10.44.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 represents a customized checkbox—for example, one created using <div> or <span> tags, rather than using a <button> element. This class inherits the HTML_Object Class (Section 6.10.29). (See also CheckBox Support (Section 6.10.44.6.5).)

This read/write property holds whether the checkbox is checked or not.

This class provides an abstract item API to access any supported item type contained in a custom item view (HTML_CustomItemView Class (Section 6.10.16).) This item class inherits the HTML_Object Class (Section 6.10.29). (See How to set up Support for Complex Widgets (Section 6.10.44.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 6.10.15)) 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 6.10.29)), or returns 0 if this item doesn't have an item handle.

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

Returns a reference to this item's next “sibling” item (of type HTML_CustomItem Class (Section 6.10.15)); 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 is a synthetic property, see Synthetic Properties in web objects for more information.

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 6.10.15)); 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 6.10.24) which inherits the HTML_Object Class (Section 6.10.29). (See How to set up Support for Complex Widgets (Section 6.10.44.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 6.10.15).

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 6.10.15)); 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 6.10.15)) 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 is a synthetic property, see Synthetic Properties in web objects for more information.

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 is a synthetic property, see Synthetic Properties in web objects for more information.

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 customized radio button—for example, one created using <div> or <span> tags, rather than using a <button> element. This class inherits the HTML_Object Class (Section 6.10.29). (See also RadioButton Support (Section 6.10.44.6.13).)

This read/write property holds whether the radio button is selected (checked) or not.

This class represents customized multi-selection lists—for example, those created using <div> or <span> tags, rather than using a <select> element. This class inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29). (See also Select List Support (Section 6.10.44.6.14) and HTML_Select Class (Section 6.10.32).)

This function returns true if the given option is the or one of the items in the selection list; otherwise it returns false.

This read/write property holds a single string containing all the currently selected entries. The string has the form "option1delimiteroption2delimiter...optionNdelimiter" where the delimiter can be any one of the characters: “,;|-+*!/”. Even if there is only one selected entry its text will still be followed by the delimiter.

When writing to this property, the string passed must have the option1delimiter etc., format.

This class represents a customized text editor field—for example, those created using <div> or <span> tags, rather than using an <input> element. This class inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29). (See also Text Field Support (Section 6.10.44.6.16) and HTML_Text Class (Section 6.10.38).)

This function puts the keyboard focus into the text field.

This read/write property holds the text field's text.

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

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

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

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

This function returns the element that has the given id. (See also, HTML_Object Class (Section 6.10.29).)

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

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 6.10.29). See also, the toggleExpandable function and Expandable Section Header Support (Section 6.10.44.6.8).

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

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

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 6.10.6) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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

This function returns the first HTML_MenuItem Class (Section 6.10.28) 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 6.10.28) 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 6.10.28) 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 6.10.12) (which provides most of the class's properties) and the HTML_Object Class (Section 6.10.29). In addition, this class has its own method. See Menu Button Support (Section 6.10.44.6.10) for how to add support for custom menu buttons.

This function returns the HTML_Menu Class (Section 6.10.26) 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 6.10.29) and in addition, has its own properties and methods. See Menu Item Support (Section 6.10.44.6.11) 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 6.10.26) (i.e., the menu or menubar) that this menu item is contained in.

This function returns the HTML_Menu Class (Section 6.10.26) 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 read-only property holds the object's rectangle, with the position relative to the web view areas top left corner. The returned object has 4 properties: x and width holding the horizontal position and size and y and height holding the vertical position and size.

This is a synthetic property, see Synthetic Properties in web objects for more information.

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

Clicks this HTML object 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 object-relative coordindates of the click. The button must be one of 1 (left button), 2 (right button), or 4 (middle button).

This read-only property provides access to the various CSS attributes that a HTML object may have. The attributes are modeled as sub properties of the css object so they can be accessed directly individually or all of them retrieved through the object.properties function.

Some CSS attribute names are problematic in script languages, for example background-color. In order to mitigate this problem Squish exposes such properties by removing the dash and turning the following letter to upper case. So the background-color CSS attribute is accessible using the backgroundColor name in the CSS properties object.

The values of the individual CSS attributes are being modeled as strings, except for CSS attributes that provide color information (backgroundColor, color). These color related attributes are modeled using the CssColor Type (Section 6.10.43) type.

Here is an example of verifying an object's background color:

    blue_title = waitForObject(blue_title_H1)
    expectedColor = CssColor.fromRgb(20, 20, 200)
    test.compare(blue_title.css.backgroundColor, expectedColor)
  

    var blue_title = waitForObject(blue_title_H1)
    var expectedColor = CssColor.fromRgb(20, 20, 200)
    test.compare(blue_title.css.backgroundColor, expectedColor)
  

    my $blue_title = waitForObject(blue_title_H1)
    my $expectedColor = CssColor::fromRgb(20, 20, 200)
    test->compare(blue_title->css->backgroundColor, expectedColor)
  

    blue_title = waitForObject(blue_title_H1)
    expectedColor = CssColor.fromRgb(20, 20, 200)
    Test::compare(blue_title.css.backgroundColor, expectedColor)
  

    set blue_title [waitForObject blue_title_H1]
    set expectedColor [invoke CssColor fromRgb 20 20 200]
    set css_props [property get blue_title css]
    test compare [property get css_props backgroundColor] expectedColor
  

This read-only property holds the object's class name that is used by the DOM.

This is a synthetic property, but it can be used in multi property names under a different name. See Synthetic Properties in web objects for more information on synthetic properties and HTML_Object.className for how to use it in multi property names.

This read-only property holds the object's path in the DOM tree. The value of this property can be used as a hierarchical name identifying the object. Note that the domPath is not stable towards changes in the structure of the website.

This is a synthetic property, see Synthetic Properties in web objects for more information.

Executes a double click on this HTML object as if the user had double 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 object-relative coordindates of the double click.

Evaluates the XPath statement and returns an HTML_XPathResult Class (Section 6.10.41) 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 5.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 indicates if the given object has keyboard focus within the document. This is usually only meaningful for text fields.

This is a synthetic property, see Synthetic Properties in web objects for more information.

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

	Note
	This property is deprecated as the value may not be calculated correctly for all browsers. Please consider using the height of the rectangle provided by the HTML_Object.boundingClientRect instead.

This is a synthetic property, see Synthetic Properties in web objects for more information.

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 and HTML_Object.simplifiedInnerText.)

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 and HTML_Object.simplifiedInnerText.)

This read-only property holds the object's inner text as plain text, so the returned string does not contain any HTML markup. In addition the whitespace is simplified, so that only a single space is kept for any number of whitespace. In this context newlines, tabulators and linebreaks are also considered to be whitespace so those are replaced with a single space as well. (See also, HTML_Object.innerHTML and HTML_Object.innerText.)

This is a synthetic property, but it can be used in multi property names. See Synthetic Properties in web objects for more information on synthetic properties.

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

Clicks a HTML object the same way a user would to open a context menu for that object.

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

This read-only property holds the object's rectangle, with the position relative to the top left corner of the desktop screen. The returned object has 4 properties: x and width holding the horizontal position and size and y and height holding the vertical position and size.

This is a synthetic property, see Synthetic Properties in web objects for more information.

The function scrolls the web content to make the object visible for which it is called. The optional top can be used to indicate whether the object should appear at the top or bottom of the web content. Passing true (the default if no argument is given) aligns it to the top, passing false aligns it to the bottom. (This function is internally called by the global scrollTo function.)

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 6.10.34) 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 is a synthetic property, see Synthetic Properties in web objects for more information.

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

This is a synthetic property, see Synthetic Properties in web objects for more information.

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 is visible according to the CSS rules applied to it. If the object's 'visibility' CSS attribute is set to hidden or if the object's or any parent's 'display' CSS attribute is set to none, this property holds false.

This is a synthetic property, but it can be used in multi property names. See Synthetic Properties in web objects for more information on synthetic properties.

	Note
	In older Squish releases this property had a different meaning, it reflected the value of a visible attribute on the object instead of reflecting the objects visibility according to CSS. This behavior can be restored by setting the BackwardsCompatibleVisiblePropertyForHTML_Object setting in the file etc/webwrapper.ini to true.

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

	Note
	This property is deprecated as the value may not be calculated correctly for all browsers. Please consider using the width of the rectangle provided by the HTML_Object.boundingClientRect instead.

This is a synthetic property, see Synthetic Properties in web objects for more information.

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

	Note
	This property is deprecated as the value may not be calculated correctly for all browsers. Please consider using the y property of the rectangle provided by the HTML_Object.boundingClientRect or HTML_Object.screenRect instead.

This is a synthetic property, see Synthetic Properties in web objects for more information.

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

	Note
	This property is deprecated as the value may not be calculated correctly for all browsers. Please consider using the x property of the rectangle provided by the HTML_Object.boundingClientRect or HTML_Object.screenRect instead.

This is a synthetic property, see Synthetic Properties in web objects for more information.

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

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 6.10.6) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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 6.10.24) which inherits the HTML_Object Class (Section 6.10.29). (See also HTML_CustomSelectList Class (Section 6.10.18).)

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 6.10.30)) 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 6.10.4)) of all the options (as HTML_Option Class (Section 6.10.30) objects) contained in this selection element.

This property provides a list of the texts of all options that are currently selected in the selection element.

Assigning a new list of texts to this property changes the selected options in the selection element so that all options whose text matches any of the ones listed will be selected and all other options in the element will not be selected. For example if the element has 4 options with the texts Red, Blue, Green and Black and the currently selected texts are Red and Green, then assigning a new list Blue, Black to this property will deselect the Red and Green entries and instead select the Blue and Black one.

This is a synthetic property, see Synthetic Properties in web objects for more information.

This property provides a list of the value attributes of all options that are currently selected in the selection element.

Assigning a new list of values to this property changes the selected options in the selection element so that all options whose value matches any of the ones listed will be selected and all other options in the element will not be selected.

This is a synthetic property, see Synthetic Properties in web objects for more information.

This property provides a list of the index of all options that are currently selected in the selection element.

Assigning a new list of indexes to this property changes the selected options in the selection element so that all options whose index matches any of the ones listed will be selected and all other options in the element will not be selected.

This is a synthetic property, see Synthetic Properties in web objects for more information.

This property provides a list of the label of all options that are currently selected in the selection element.

This property does not allow assigning a new value to it, it is read only.

This is a synthetic property, see Synthetic Properties in web objects for more information.

This function deselects the items of the selection element that have a value that is listed in the values parameter.

This function deselects the items of the selection element that have a text that is listed in the texts parameter

This function deselects the items of the selection element that have a index that is listed in the indexes parameter

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 is deprecated, please consider using the HTML_Select.selectedTexts property instead.

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 function is deprecated, please consider using the HTML_Select.selectedTexts property instead.

This function selects the option with the given text in the select form element (which may be a select or select-one element). If the element is a multi-selection box, multiple options to be selected can be passed in the text separated by commas.

This function selects options from select form element (which may be a select or select-one element). For each entry in the listOfTexts a corresponding option with that visible text will be selected. If the element only allows single selection, the passed in listOfTexts has to contain only a single entry.

This function selects the option with the given value attribute in the select form element (which may be a select or select-one element).

This function selects options from the select form element (which may be a select or select-one element). For each entry in the listOfValues a corresponding option with that value attribute will be selected. If the element only allows single selection, the passed in listOfValues has to contain only a single entry.

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

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

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 tables. This class inherits the HTML_Object Class (Section 6.10.29).

This read only property holds the number or rows in the table - excluding any header rows.

This is a synthetic property, see Synthetic Properties in web objects for more information.

This read only property holds the number or columns in the table.

This is a synthetic property, see Synthetic Properties in web objects for more information.

This function retrieves the cell object for the given row and column. The indices for row and column are 0-based and the row does not include any header rows, only the actual content rows.

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

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 6.10.29). Each tab in the tab widget is of type HTML_Tab Class (Section 6.10.36).

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

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 6.10.40) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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 6.10.40) which inherits the HTML_FormElement Class (Section 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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 6.10.24) which inherits the HTML_Object Class (Section 6.10.29).

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

Selects all text in the text field, such that a subsequent text input in the field will delete or overwrite it.

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

This is a synthetic property, see Synthetic Properties in web objects for more information.

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

When evauating an XPath statement on any HTML_Object Class (Section 6.10.29) (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 5.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 6.10.29)) 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 6.10.29)) at the given index position in the node list if the result of the XPath execution was a node list.

This class provides an API for accessing references to JavaScript objects. JsObject objects can be returned by the retrieveJSObject function and by the property and call functions of this class.

This function returns the value of the JavaScript property with the given name. The returned value can be either a primitive, like a string or number, or it can be reference to a JavaScript object as JsObject.

This function executes the method with the given name on the JavaScript object. The methodarguments is optional if the JavaScript method that is to be executed does not need any parameters. In case the JavaScript method does require parameters, methodarguments should be a list of values that are to be passed to the JavaScript method. The parameters can be either primitive values, like strings or numbers, or it can be a reference to a JsObject obtained earlier in the script. The returned value can be either a primitive, like a string or number, or it can be reference to a JavaScript object as JsObject.

The CssColor type is capable of holding a color and alpha value.

This construction function creates a new color object from the components provided in the red, green and blue parameters. The object's CssColor.alpha property will be 1.0 when using this function. Here is how to create a valid Color object:

  orange = CssColor.fromgRgb(235, 155, 52)
  

  var orange = CssColor.fromRgb(235, 155, 52)
  

  my $orange = CssColor::fromRgb(235, 155, 52)
  

  orange = CssColor.fromRgb(235, 155, 52)
  

  set color [invoke CssColor fromgRgb 235 155 52]
  

This construction function creates a new color object from the components provided in the red, green, blue and alpha parameters. Here is how to create a valid CssColor object:

    orange = CssColor.fromgRgba(235, 155, 52, 0.5)
    

    var orange = CssColor.fromRgba(235, 155, 52, 0.5)
    

    my $orange = CssColor::fromRgba(235, 155, 52, 0.5)
    

    orange = CssColor.fromRgba(235, 155, 52, 0.5)
    

    set color [invoke CssColor fromgRgba 235 155 52, 0.5]
    

CssColor objects have the following properties:

This read/write property holds the color's red component value. It will be in the range 0-255.

This read/write property holds the color's green component value. It will be in the range 0-255.

This read/write property holds the color's blue component value. It will be in the range 0-255.

This read/write property holds the color's alpha component value. It will be in the range 0-1.0.

This read-only property indicates if the other properties of the object are valid. Invalid color values may be provided by Squish when there was a problem obtaining a color.

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);

6.10.44.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 6.10.16) and HTML_CustomItem Class (Section 6.10.15) abstraction API, the test scripts will be able to access the widget and work with its items, states, and properties.

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

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

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

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

6.10.44.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 view object:

JavaScript

gwtExtension.nameOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
    case gwtExtension.TreeItem:
        return escape(gwtExtension.nameOfTreeItem(obj)["object"]);
    case gwtExtension.TreeItemHandle:
	return escape(gwtExtension.nameOfTreeItem(
                gwttreeExtension.itemOfHandle(obj))["object"]);
    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 6.10.44.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 {"object": treeName, "itemText": 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). The both parts are returned separately to allow reusing this for the nameOf function and the itemTextForEventObject function further down

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. The item's text (which we get from the item's innerText) is returned separately.

The fourth function to implement is a callback that will provide the actual items text whenever a click is found to happen on an item. This allows Squish to generate nicely-looking clickItem invocations for clicks on items.

JavaScript

gwtExtension.itemTextForEventObject = function( eventObject )
{
    switch (gwtExtension.getType(eventObject)) {
        case gwtExtension.TreeItem:
            return gwtExtension.nameOfTreeItem(eventObject)["itemText"];
        case gwtExtension.TreeItemHandle:
            return gwtExtension.nameOfTreeItem(gwttreeExtension.itemOfHandle(eventObject))["itemText"];
    }

    return undefined;
}

This function reuses the nameOfTreeItem function but selects the item text calculated by that to return if the given object is referring to a tree item or tree item handle.

6.10.44.5.2.4.  Register Hook Functions

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);
Squish.addItemTextForEventObjectHook(gwtExtension.itemTextForEventObject);

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

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

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

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

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

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

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

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

6.10.44.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 functions 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.)

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

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