Squish Object

The Squish Object provides an API through which Squish's web edition can be extended to recognize custom AJAX/JavaScript/DHTML widgets. This means that Squish can work on high-level custom widgets instead of working on the low-level DOM objects. (Note that this API cannot be used in test scripts—for tests use the HTML_* classes described above.)

Using this mechanism makes it possible to create robust high-level tests for those AJAX/JavaScript/DHTML widgets that Squish doesn't support as standard.

For examples of how to use the Squish Object, see How to set up Support for Complex Widgets, and Writing HTML Class-Specific Extensions.

Here are some quick links to the Squish Object's methods:

Squish.addClickHook(function)

This function registers the given function as a handler for simulating mouse clicks. The function will be called with an HTML element when a click on that element ought to occur. If the element is one that the handler function wants to handle the handler function should perform the click and return true; otherwise it should return undefined if it wants Squish to try other handlers (and default to Squish's own functionality if no other handler is available or if all the handlers return undefined).

Squish.addEventObjectHook(function)

This function registers the given function as a handler when finding the actual object an event refers to. The function will be called with an HTML element when an event for that element occurs, and may return the element, or another element, or undefined if it wants Squish to try other handlers (and default to Squish's own functionality if no other handler is available or if all the handlers return undefined).

Squish.addEventToStringHook(function)

This function registers the given function as a handler. The registered function will be called with three arguments: the type name of the object the event applies to (as a string), as returned by a typeOf function (see the Squish.addTypeOfHook(function) function), a reference to the object itself, and the original event object ready for inspection. The registered function should return a string that contains the customized recording parameters in HTTP-query format—for example, "name1=value1&name2=value2". Of course, every value should be passed through the JavaScript escape function. If the registered function does not want to customize the event string it should return undefined. If a string is returned, Squish will add to it additional information, in particular, the object's x, y coordinates, the keyboard modifier state, and the mouse button state, as well as the object's name and type.

Squish.addEventTypeHook(function)

This function registers the given function as an event type handler. The registered function will be called with two arguments: a reference to the HTML element object itself, and the original event object ready for inspection. (The event object might be different from the event.source property since it comes from the eventObject function which Squish for Web extensions can customize. See also the Squish.addEventObjectHook(function) function.) The registered function should return a string that contains the JavaScript event name such as "mousedown", "click", "change", etc.

Registering an event type handler can be useful when writing extensions for custom HTML elements. For example, doing so makes it possible to transform mouseClick(objectOrName) calls on a custom combobox into selectOption(objectOrName, text) calls. (See also, Writing HTML Class-Specific Extensions.)

Squish.addItemTextForEventObjectHook(function)

This function registers the given function as a handler to figure out the item text if a click on some eventObject is being noticed. The handler received a HTML element which was clicked upon or otherwise interacted with. This should be used in combination with Squish.addNameOfHook(function) to implement item-support. The nameOf hook should always return the name of the item view object and for the same HTML element the itemTextForEventObject hook should return the item text for that element - if applicable. If no item text can be identified the function should return undefined

Squish.addMatchObjectHook(function)

This function registers the given function as an object name matcher function that returns a Boolean to indicate whether the real (multi-property) name matched, i.e., if the object matched by its properties. The function will be called with an object, a property name, and a valueObject—see the Boolean Squish.matchProperty(valueObject, property) function for more about the parameters—and returns a Boolean or undefined if it cannot perform the match. When matching a name, Squish will try as many name matching functions as have been registered using this function, and if all of them return undefined (or if there aren't any), Squish will fall back to using its own built-in name matching algorithm. (For an example of use, see How to Implement a Custom Name Matcher; see also Improving Object Identification.)

Squish.addNameOfHook(function)

This function registers the given function as a name generator function that returns a unique real (multi-property) name for a given object. The function will be called with an object and must return a name that uniquely identifies the object as a string in the form of a real name—or it must return undefined if it cannot generate a name for the object. When generating a real name for an object, Squish will try as many name of functions as have been registered using this function, and if all of them return undefined (or if there aren't any), Squish will fall back to using its own built-in name generation algorithm. (See How to Implement a Custom Name Generator for an example.)

Squish.addTypeOfHook(function)

This function registers the given function as a function that returns the high-level type of a DOM object. The typeOf function (function) takes a single string as argument (an element) and returns a string as its result.

When Squish encounters an HTML element that has been registered with the Squish.registerWidget(argumentObject) function, and whenever it needs to know the element's type, it uses the hook function registered here. So if, for example, we had a <span> tag that we wanted to treat as a button, we could return "button" as the tag's type instead of the default (which in this example would be "span").

Here is a very simple typeOf function that we could register with the Squish.addTypeOfHook function:

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

This function re-identifies <span> tags as buttons, but leaves the types of all other tags unchanged. For elements that you want Squish to treat as interactive elements, you would normally return one of the types button, checkbox, image, radio, or submit. Returning undefined for cases we don't handle is important—it means that Squish will look for another typeOf function (since many can be registered), falling back on its own internal typeOf function if there are no others or if all the others return undefined for the element.

Squish.addUnmatchedProperty(objectName, propertyName)

This function can be used in a match object hook function (see Squish.addMatchObjectHook(function)) to add to the list of unmatched properties for a given objectName. The function should be called with the object name given to the match object hook function and the name of the property (propertyName) that has not been matched by this object. The purpose of this function is to facilitate improved feedback when an object lookup fails, since Squish will include unmatched property names in its error message.

Background: It is possible for custom wrappers to produce a list of the properties that did not match, to provide informative "object not found" error messages. The purpose of the Squish.addUnmatchedProperty function is to allow custom Squish for Web extensions to take advantage of this facility. This is especially useful for extensions which customize (i.e., extend) Squish's built-in object matching algorithm.

For example, suppose we wanted to implement support for a custom web toolkit (like SmartGWT) where the toolkit adds a custom property (such as iscLocator) when generating names. Such a property must be understood by the web extension's match object hook function. So the hook function needs a way of adding the iscLocator property to the list of unmatched properties if matching fails. Therefore, if a web page using this toolkit has an element such as <button name="update">Update</button>, the generated name would be something like {tagName='BUTTON' iscLocator='//[Button id="1"]/'}. (If the toolkit really were SmartGWT, these two properties are all that are needed to uniquely identify elements, so the name property isn't needed or used.) Now during object lookup Squish will fetch all the <button> elements from the DOM and will then try matching the rest of the properties from the real (multi-property) name against each such element it finds. If none of the elements match, the match object hook will call the addUnmatchedProperty function. As a result, when the user gets the "object not found" error message it will include the iscLocator property name.

String Squish.cleanString(s)

This function returns a copy of string s with any leading and trailing whitespace removed and each internal occurrence of multiple whitespace (or of tabs or newlines) replaced with a single space. Also, all occurrences of Unicode characters U+2011 (non-breaking hyphen) and U+2013 (en-dash), are replaced with a hyphen.

Squish.clickButton(buttonElement)

This function clicks the given buttonElement HTML button element. This is for the use of Squish for Web extensions which may have to handle native HTML buttons specially in some browsers. See HTML_CustomButtonBase Class, HTML_CustomButton Class, and Button Support.

String Squish.createClickItemInformationForMenuItem(menuElement, menuText)

The menuElement is a DOM element that represents a menu. This function returns a string that identifies which of the menu's items has been clicked. The string is suitable for use as the return value of an event to string hook function (see Squish.addEventToStringHook(function)).

Squish for Web extensions should use this function when customizing the event to string functionality, to record calls to the clickItem(objectOrName, itemText) function.

See also, Menu Support and Menu Item Support.

String Squish.createClickTabInformation(tabWidgeElement, tabTitle)

The tabWidgetElement is a DOM element that represents a tab widget. This function returns a string that identifies which of the tab widget's tabs has been clicked. The string is suitable for use as the return value of an event to string hook function (see Squish.addEventToStringHook(function)).

Squish for Web extensions should use this function when customizing the event to string functionality, to record calls to the clickTab(objectOrName, tabTitle) function.

See also, Tab Widget Support.

String Squish.createChooseDateInformation(jsDate)

The jsDate is a JavaScript Date object. This function returns a string that is suitable for returning from an event to string hook and that contains the given date's, year, month, and day of the month. (See Squish.addEventToStringHook(function).)

Squish for Web extensions should use this function when customizing the event to string functionality, to record calls to the chooseDate(objectOrName, date) function.

See also, Date Picker Support.

String Squish.createItemName(viewObjectName, itemText)

Support for this function has been removed. In order to support recording of clicks on items you need to add hook function via Squish.addItemTextForEventObjectHook(function).

String Squish.createMultiOptionString(arrayOfSelectedOptions)

This function returns a single string that is the concatenation of all the arrayOfSelectedOptions's values separated by a suitable separator. This function should be useful for web extensions that provide combobox widgets that do not use the standard HTML element type for their rendering. For such widgets extensions need to generate a suitable parameter value for event to string hooks (see the Squish.addEventToStringHook(function) function). For the reverse operation see the ArrayOfStrings Squish.splitMultiOptionString(multiOptionString) function.

HTMLElement Squish.getElementByClassName(contextNode, className, tagName)

This function returns the first element that has the given className and tagName relative to the specified contextNode. (See Item Traversal for examples.)

Array Squish.getElementsByClassName(contextNode, className, tagName)

This function returns an array of those elements that have the given className and tagName relative to the specified contextNode.

Event Squish.getEventSourceElement(event)

This function returns the source element for the given event as provided by the browser. This is the real source element, not one returned by an installed event object hook function (for which, see Squish.addEventObjectHook(function)).

ArrayOfStrings Squish.getSelectedOptionTexts(selectElement)

This function returns an array of the string values of the selected items in a multiselect or combobox element. The selectElement must either be an HTML_Select Class element (i.e., an HTML <select>), or an element that provides the same properties and methods.

Boolean Squish.hasClassName(objectOrName, className)

This function returns true if the given DOM object/web element has a DOM class whose name matches the text passed as className; otherwise it returns false.

For HTML elements that have a single name for their class name, e.g., <span class="warning">dangerous ducks</span> this function works exactly as expected. For example:

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

However, HTML elements are at liberty to have multiple space-separated class names, e.g., <span class="heading major">New Section</span>. In such cases Squish tracks the class names as a list, which is very flexible. For example:

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)

Boolean Squish.isElementVisible(element)

This function returns true if the given element is visible according to the CSS display and visibility properties; otherwise it returns false.

The element's z-value is not considered, so no account is taken of whether the element is underneath another element.

Boolean Squish.matchProperty(valueObject, property)

This function returns true if the given valueObject's value matches the value of the given property; otherwise it returns false.

The valueObject contains both a string value to match and an integer flag indicating whether the match should be based on literal string comparison (0), wildcard matching (2), or regular expression matching (1), using the format {value: string, modifiers: integer}.

This function should be used in your custom matchObject function instead of doing a straight comparison.

Custom match property functions are registered using the Squish.addMatchObjectHook(function) function. (For an example of use, see How to Implement a Custom Name Matcher; see also Improving Object Identification.)

Squish.mouseClick(objectOrName)

Squish.mouseClick(objectOrName, ctrl)

Squish.mouseClick(objectOrName, ctrl, shift)

Squish.mouseClick(objectOrName, ctrl, shift, alt)

Squish.mouseClick(objectOrName, ctrl, shift, alt, x, y)

Squish.mouseClick(objectOrName, ctrl, shift, alt, x, y, button)

Sends a mouse click event on the given objectOrName at the specified relative x, y position. The ctrl is a Boolean which if true means that the Ctrl key is pressed. Both shift and alt are also Booleans and work in the same way regarding the Shift and Alt keys. By default the click is with the left mouse button but this can be overridden by specifying the button as a number: 1 for the left button, 2 for the right button, and 4 for the middle button. All the parameters except the first are optional and can be omitted.

String Squish.nameOf(objectOrName)

This function returns the real (multi-property) name of the given objectOrName.

This method might call a registered name hook function, so be careful when calling this from your custom name hook handler.

Squish.ObjectName Squish.ObjectName()

Constructs a new instance of ObjectName Object It allows adding or removing properties which can use plain string comparison, wildcards or regular expressions.

String Squish.propertiesToName(objectOrName, listOfPropertyNames)

Given a DOM objectOrName/web element, this function returns a string containing one or more space separated propertyName='propertyValue' pairs, one for each of the properties in the given listOfPropertyNamess. The resultant string is suitable for use in name generation, for example, by the String Squish.uniquifyName(name, objectOrName) function.

Squish.RegExPropertyValue Squish.RegExPropertyValue(regexString)

Constructs a new instance of RegExPropertyValue which an be add as a property value to an ObjectName Object. The regexString indicates the regular expression that the property should be matched against.

Squish.registerWidget(argumentObject)

This function is used to register custom web elements with Squish so that they can be scripted, recorded, and played back correctly. The argumentObject is a JavaScript object (i.e., a named argument list—an object enclosed in braces and that contains a comma-separated list of name–value pairs), and that supports two keys:

• Event – This is a string that specifies which type of events should be recorded; e.g., "mousedown".
• Class – This is a string that specifies the class name (i.e., the value of the className property), of the DOM objects which Squish should recognize as a widget.

For an example see How to set up Support for Simple Widgets.

The purpose of this function is to allow you to add support for the recording of mouse clicks (mouseClick(objectOrName)) on HTML elements that Squish would normally ignore. This is useful if you want to record clicks on, say, <span> tags, or on custom tags supported by the particular web framework you're using.

Squish can tell an element's type by checking its type attribute or its tagname but you can override this (for example, make a <span> tag be treated as a button), by registering a typeOf function. Such a function should return one of the types button, checkbox, image, radio, or submit, and is registered using the Squish.addTypeOfHook(function) function. Note that although we must register each custom element with its own individual Squish.registerWidget function call; we could call the Squish.addTypeOfHook(function) function just once, since in the typeOf function we can return an appropriate type for all the custom elements we have registered.

ArrayOfStrings Squish.splitMultiOptionString(multiOptionString)

This function returns the array of strings that is produced by splitting the given multiOptionString. The splitting is done on commas unless the last character in the string is one of ";|-+*!/", in which case the splitting is done on that character. For the reverse operation see the String Squish.createMultiOptionString(arrayOfSelectedOptions) function.

String Squish.uniquifyName(name, objectOrName)

This function returns a "uniquified" version of the name for the given objectOrName by adding the correct occurrence into the name.

The name must be provided as a real name, that is a string of the form {propertyName1='propertyValue1' propertyName2='propertyValue2' ... propertyNameN='propertyValueN'}. Given a name and an objectOrName, this function returns the name unchanged if the name uniquely identifies an application object. Otherwise it returns name with an additional property (occurrence) whose value is an integer such that the name is unique. The purpose of this function is to create a name that uniquely identifies the given objectOrName.

Squish.WildCardPropertyValue Squish.WildCardPropertyValue(wildcardString)

Constructs a new instance of WildCardPropertyValue which can be added as a property value to an ObjectName Object. The wildcardString indicates the wildcard expression that the property should be matched against.