Web Object API

Squish provides a comprehensive API for web objects, which is documented here in its entirety.

Squish's global web functions are listed below in alphabetical order, and these are followed by various predefined objects and classes listed in alphabetical order and with the functions, methods, and properties they contain also alphabetically ordered.

Web Object API Function Parameters

In all the functions listed below that take an objectOrName argument, the argument can be a reference to an object or the name of an object.

Some of the Web Object API functions can take a modifierState argument which indicates which special keys are pressed at the time of a mouse click, and if the right button is clicked. Tthe default is the left button.

The modifierState can be one or more of the following: HTML_Event.AltKey, HTML_Event.ControlKey, HTML_Event.ShiftKey, HTML_Event.RightButton. The form shown here works for Python and JavaScript. For Perl and Ruby replace the period with two colons, e.g., HTML_Event::ControlKey, and for Tcl use the enum function, e.g., enum HTML_Event Control.

The modifierState values can be combined by using bit-wise OR, for example (JavaScript, Perl, JavaScript, Ruby) mouseClick(..., HTML_Event.ShiftKey | HTML_Event.RightButton).

Interacting with Multiple Tabs or Browser Windows

Squish supports interaction with multiple browser windows or tabs for Firefox, Microsoft Edge, Safari on Mac, Google Chrome and Chromium-based Applications at the moment. It uses the concept of an active browser tab to execute clicks in or query object information. So whever the active tab is changed by opening a new tab or window or using the dedicated tab functions provided by Squish for Web the interactions and object lookups will happen in the newly activated tab.

The individual tabs are represented by the BrowserTab Class and can be accessed either through the activeBrowserTab(), browserTabs() or by using multi-property names as described for the BrowserTab Class.

The support for Chromium-based Applications is somewhat limited as Squish can only access the contents of multiple web views inside such an application. If the application allows changing which web views are visible and which ones are hidden - for example because it uses a tab widget to show them - Squish cannot record or replay such changes.

Native Variants of Web Functions

Many of the interaction functions (such as, mouseClick, setText, clickItem, or selectOption) that do not mention native generate events inside the web page on the JavaScript level. Whereas the ones that do mention native generate operating system events.

The native variants need to properly determine the place of the object on the screen, which can be a challenge depending on the browser and web site content. They also require that nobody interacts with the system and disturbs them. The functions that use JavaScript events generally work even if you use the mouse or keyboard for something else.

However, certain interactions are limited by browsers for security reasons, so they must not be triggered from the JavaScript on the web site. Further, the JavaScript-based functions might not be able to replicate the original intent properly. For example setText cannot properly generate keyboard events in JavaScript, so it sets the value of the field and triggers a change event, which is not sufficient to make some web sites aware of the new value.

Synthetic Properties in Web Objects

The objects representing HTML elements in the DOM tree provide access to the common properties and attributes of those HTML elements according to the HTML standards. In addition to that they may provide convenience properties for certain information that are called synthetic properties. Most of those synthetic properties can not be used as part of realnames for looking up those objects as Squish provides them through a mechanism that is not available directly for the object lookup. So for example the HTML_Object.height property cannot be used in realnames. There are some exceptions to this rule noted in the individual property documentation, for example HTML_Object.simplifiedInnerText.

Web Object API Objects and Classes

Here are some quick links to the Web Object API's objects and classes (shown in terms of their inheritance hierarchy):

Here are some quick links to the Web Object API's functions:

activateBrowserTab(tab)

This function changes the active tab in the browser, also activating the corresponding window if necessary. The tab that should be activated has to be an instance of the BrowserTab Class.

This function is not supported when using a CEF-based, Electron or other Chromium-based applications. An exception will be thrown when it is being called for a BrowserTab object other than the first one in the list.

Activating different web views within such an application should be automated through a matching Squish edition for desktop applications.

activeBrowserTab()

This function retrieves the currently active tab in the form of an instance of the BrowserTab Class. This will be the tab in which all other functions and object lookups are executed.

This function is not fully supported when using a CEF-based, Electron or other Chromium-based applications. The returned BrowserTab object will always be the first one in the list of BrowserTabs and does not change based on which web view is being made active in the application.

automateLogin(username, password)

This function automates a login using the native browser's authentication dialog and passing it the given username and password.

For detailed information about how to use this function in different scenarios, see Automating a native login.

Note: On macOS, you must turn on Universal Access in the System Preferences to use this function. See macOS Universal Access.

browserTabs()

This function retrieves a list of instances of the BrowserTab Class mapping to the currently open tabs in all windows of the web browser.

cancelPrompt()

This function is used to simulate the user canceling the dialog that JavaScript pops up in response to a call to the prompt function in a web page's JavaScript code.

Behind the scenes, when Squish tests a web application that executes a JavaScript prompt function call, instead of Squish allowing the dialog to pop up (if the browser allows this, otherwise the dialog will be automated), Squish suppresses the dialog, stops execution of the web application, and calls the cancelPrompt function if replaying a cancel or the closePrompt(":dummy", text) function if replaying an okay. Then Squish resumes the web application's execution.

chooseColor(objectOrName, htmlRGBvalue)

This function is used to simulate user interaction with an HTML color field element through which the user can choose a color. The objectOrName must be recognized as a HTML_ColorField Class or a catchable exception will be raised. The htmlRGBvalue must be a string containing an HTML color value of the form "#RRGGBB" where each component (RR for red, GG for green, and BB for blue) is a two-digit hexadecimal number in the range 00 to FF representing the component's color value. (See, for example, W3School's HTML colors page.)

See Color Picker Support for how to add support for custom color pickers.

chooseDate(objectOrName, date)

This function is used to simulate user interaction with a date picker element through which the user can choose a date. The objectOrName must be recognized as a HTML_DateChooser Class or a catchable exception will be raised. The date must be a DateTime Type.

See Date Picker Support for how to add support for custom date pickers.

chooseFile(filepath)

This function can be used to automate the interaction with the file dialog opened by the browser when wanting to upload a file. The filepath needs to be the absolute path to an existing file that should be selected in the dialog.

This function can be useful in cases where the file dialog is not opened through a standard HTML file field, but rather using some customized controls for managing the uploaded files. The interaction with those controls can usually be recorded normally and then a chooseFile line can be added to the script to automate the selection of the file in the file dialog.

clearObjectCache()

This is an advanced function that may be useful when testing websites that update themselves, replacing some or all HTML elements with new ones. In such cases, it can be helpful to call this function after such an update, to force Squish to refresh its internal object cache by re-reading the web page's DOM tree.

This function clears an internal cache used by Squish for Web so that Squish doesn't have to look up the same objects repeatedly in the browser. After calling this function, all object references (such as those returned by the Object waitForObject(objectOrName) and Object findObject(objectName) functions) are invalid, so new object references must be obtained—for example, using the Object waitForObject(objectOrName) function—for any objects that you want to interact with after the cache is cleared.

See also, the rehook(browserTab) function.

clickButton(objectOrName)

This function clicks the specified objectOrName button which can be a button, radio, checkbox, submit, or image object.

clickItem(objectOrName, itemText)

clickItem(objectOrName, itemText, modifierState)

clickItem(objectOrName, row, column)

clickItem(objectOrName, row, column, modifierState)

This function clicks the mouse on the item with the given itemText or the item at the given row and column inside the given objectOrName view widget using the optional modifierState modifier state (if given).

Note that for the row and column version the objectOrName must be of type HTML_CustomItemView Class. Also, if the row or column is out of range (below zero or greater than the number of rows or columns), no exception will be raised and no click will take place.

See Web Object API Function Parameters for which values are valid for the modifierState.

clickLink(objectOrName)

This function clicks the hyperlink (anchor) identified by the objectOrName object.

clickTab(objectOrName, tabTitle)

This function clicks the tab in the tab widget with the tab title text tabTitle in the objectOrName tab widget. If such a tab exists it will now be the top-most (i.e., visible) tab. If the objectOrName isn't recognized as a HTML_TabWidget Class a catchable exception is raised.

See Tab Widget Support for how to add support for custom tab widgets.

clickTreeHandle(objectOrName, itemText)

This function clicks on the expand/collapse (tree handle) for the item that has the specified itemText on the objectOrName tree widget.

Note: This function should not normally be used in hand-written test scripts since Squish can handle this interaction for all the tree widgets used by the web toolkits that are supported as standard. The primary reason for this function's existence is to support interactions with custom Web tree widgets that are not supported by Squish out of the box.

For more details, including examples of use, see How to set up Support for Complex Widgets.

closeAlert(":dummy")

This function is used to simulate the user clicking Ok in the dialog that JavaScript pops up in response to an alert function call in a web page's JavaScript code. The first parameter must be a fake object name (e.g., ":dummy");.

Behind the scenes, when Squish tests a web application that executes a JavaScript alert function call, instead of Squish allowing the dialog to pop up, Squish suppresses the dialog (if the browser allows this, otherwise the dialog will be automated), stops execution of the web application, and expects the closeAlert function. Then Squish resumes the web application's execution as if the user had closed the dialog.

closeConfirm(":dummy", confirmed)

This function is used to simulate the user clicking Yes or No in the dialog that JavaScript pops up in response to a confirm function call in a web page's JavaScript code. The first parameter must be a fake object name (e.g., ":dummy"); the confirmed is a Boolean, with true indicating the user clicked Yes, and false indicating that the user clicked No.

Behind the scenes, when Squish tests a web application that executes a JavaScript confirm function call, instead of Squish allowing the dialog to pop up, Squish suppresses the dialog (if the browser allows this, otherwise the dialog will be automated), stops execution of the web application, and calls the closeConfirm function, passing true if it was recorded that the tester clicked Yes or false if they clicked No. Then Squish resumes the web application's execution, returning the true or false result to the application as the confirm function call's return value.

closePrompt(":dummy", text)

This function is used to simulate the user typing some text into the dialog that JavaScript pops up in response to a prompt function call in a web page's JavaScript code. The first parameter must be a fake object name (e.g., ":dummy"); the text is the text that is normally entered into the prompt dialog's text edit.

Behind the scenes, when Squish tests a web application that executes a JavaScript prompt function call, instead of Squish allowing the dialog to pop up, Squish suppresses the dialog (if the browser allows this, otherwise the dialog will be automated), stops execution of the web application, and calls cancelPrompt() if replaying a cancel or the closePrompt function for an okay, passing the text that the tester entered when the test was recorded. Then Squish resumes the web application's execution, returning the text to the application as the prompt function call's return value.

closeWindow(":[Window]")

This function closes the browser window. The parameter must be the string ":[Window]".

attachToBrowser(portOrWindowTitle)

This function allows connecting Squish for Web to an already running instance of the browser selected in the server configuration. This can be used in cases where the browser should not be started by Squish itself but is rather started by some other program that is being automated as part of the test. The portOrWindowTitle is required for most supported browsers and specifies how to find the instance of the browser that Squish should connect to. The example code below shows which browsers use the parameter and what type of value is to be provided. When specifying a number it has to match the communication port number configured during the installation of the browser extensions.

When the portOrWindowTitle is a string it needs to match the window title of an existing browser window. The window title pattern can use wildcards to allow connecting to a window where some parts of the title are changing. (* matches any number of characters, ? matches any single character). The wildcard must however be specified in such a way that only a single browser window is being identified. The window title is usually the title of the active tab of the browser and it can usually be obtained from the tooltip when hovering over the entry of that window in the task bar.

See Attaching to a running Web Browser for a more complete introduction how to use this feature.

javascriptperlpythonrubytcl

function main() {
  // Firefox (for Chrome use 9935)
  attachToBrowser( 9932 );
  // Internet Explorer
  // attachToBrowser( "*Automated Cross-Platform GUI Testing" );
  // Safari
  // attachToBrowser();
}

sub main {
  # Firefox (for Chrome use 9935)
  attachToBrowser( 9932 );
  # Internet Explorer
  # attachToBrowser( "*Automated Cross-Platform GUI Testing" );
  # Safari
  # attachToBrowser();
}

def main():
  # Firefox (for Chrome use 9935)
  attachToBrowser( 9932 )
  # Internet Explorer
  # attachToBrowser( "*Automated Cross-Platform GUI Testing" )
  # Safari
  # attachToBrowser()

def main()
  # Firefox (for Chrome use 9935)
  attachToBrowser( 9932 )
  # Internet Explorer
  # attachToBrowser( "*Automated Cross-Platform GUI Testing" )
  # Safari
  # attachToBrowser()
end

proc main {} {
  # Firefox (for Chrome use 9935)
  invoke attachToBrowser 9932
  # Internet Explorer
  # invoke attachToBrowser "*Automated Cross-Platform GUI Testing"
  # Safari
  # invoke attachToBrowser
}

String contextOf(window)

Note: This function is deprecated unless you disabled tab support. Consider using realnames for identifying browser tabs and windows.

This function returns the context string of the given window. A context string is a page's "base location"—this includes any parent locations necessary to precisely identify the page (for example, if the page is actually a frame or iframe element). (See also, HTML_Array contextList() and Boolean setContext(context).)

HTML_Array contextList()

Note: This function is deprecated unless you disabled tab support. Consider using the browserTabs() function instead to access the browser tabs and windows.

This function returns an HTML_Array Class containing references to the browser windows that Squish has hooked. The context of a particular window can be retrieved using the String contextOf(window) function.

Note: This list does not include any frame or iframe elements that exist in the web pages. It only contains windows that Squish hooked into.

String currentContext()

Note: This function is deprecated unless you disabled tab support. Consider using the activeBrowserTab() function instead.

This function returns the currently active browser window. You can obtain a string representation of this window using String contextOf(window). If the page uses frames or iframes this can also be the content window of such a frame instead of the window containing the page itself. (See also, String contextOf(window), Boolean setFrameContext(browserTab, frameName), Boolean setContext(context), and waitForContextExists(context).)

doubleClick(objectOrName, x, y)

This function double-clicks the mouse on the objectOrName widget. The click occurs at the top left corner of the widget or at position (x, y)—which is relative to the top left corner of the widget itself—if specified.

dragAndDrop(src_objectOrName, sx, sy, target_objectOrName, tx, ty)

This function performs a drag and drop operation. It begins by initiating a drag on the source_objectOrName widget starting at position sx and sy (in the source_objectOrName widget's coordinates), and then it does the drop on the target_objectOrName widget at position tx and ty (in the target_objectOrName widget's coordinates).

startDrag(src_objectOrName, sx, sy)

This function performs a start drag operation. It initiates a drag on the source_objectOrName widget starting at position sx and sy (in the source_objectOrName widget's coordinates). This can be useful if the drop target object becomes available only after the drag starts.

dropOn(target_objectOrName, tx, ty)

This function performs a drop operation. It drops the dragged object on the target_objectOrName widget at position tx and ty (in the target_objectOrName widget's coordinates). This function should only be called after startDrag has been called, i.e., a drag operation is in progress.

Object evalJS(browserTab, code)

Object evalJS(code)

This function evaluates the JavaScript code string in the web browser's tab referenced by the browserTab. The result of the last statement in the code is returned. (See also How to Use evalJS.)

Note: If the browserTab is not specified, the call will always use the initially loaded tab even if another tab is currently active. This can lead to unexpected behavior if the test works with multiple browser tabs or windows, so we suggest to always specify the browserTab parameter in new scripts.

Boolean hasContext(context)

Note: This function is deprecated unless you disabled tab support. Consider using hasFrameContext when you want to verify whether a given frame exists or waitForObject with a qualified name that identifies a particular tab if you want to check that the tab exists.

This function returns true if the window with a URL that matches the context is open and can be accessed by the test script; otherwise it returns false. A context string is a page's "base location"—this includes any parent locations necessary to precisely identify the page (for example, if the page is actually a frame or iframe element). (See also, Boolean setContext(context), and waitForContextExists(context).)

Boolean hasFrameContext(browserTab, context)

This function returns true if the tab referenced by browserTab has a frame that matches the context and can be accessed by the test script; otherwise it returns false. A frame context is a string identifying a frame inside a page based on its nesting inside other frames. For example the first frame in a page has the context FRAME1, the second FRAME2 etc. and if a frame has itself another frame that one can be identified using FRAME1.FRAME1. (See also, Boolean setFrameContext(browserTab, frameName).)

installEventHandler(eventName, handlerFunctionNameOrReference)

This function installs a global event handler. The script function named or referenced in handlerFunctionNameOrReference, will be called when an event of the eventName type occurs.

The eventName can be the name of any of the following event types:

AlertOpened – occurs when an alert box would be shown by the JavaScript window.alert function
BodyUnloaded – occurs when the Squish the browser loads a new page or reloads the current page. This event is also sent out for any frames or iframes that Squish was able to hook when they load or reload their content. The handler function receives two parameters. The first parameter is the Squish context name of the window or frame that changes. The second parameter is the location URL of the content that is being unloaded by the browser.
ConfirmOpened – occurs when a confirmation (OK/Cancel) box would be shown by the JavaScript window.confirm function
Crash – occurs if the AUT crashes
ModalDialogOpened – occurs when a modal dialog is opened with the Internet Explorer-specific JavaScript showModalDialog function
ModelessDialogOpened – occurs when a modeless dialog is opened with the Internet Explorer-specific JavaScript showModelessDialog function
PromptOpened – occurs when a prompt box would be shown by the JavaScript window.prompt function
Timeout – occurs when the Squish response timeout is reached
WindowOpened – occurs when a new window is opened by the JavaScript window.open function

The function named in handlerFunctionName is called (with no arguments) whenever one of the registered events occurs.

For examples see How to Use Event Handlers.

Note: The installEventHandler function will only work if it is called after the AUT has been started. For example, by using the ApplicationContext startApplication(autName) function.

Boolean isBrowserDialogOpen()

This function returns true if a native browser dialog (such as a login dialog, certificate dialog, etc.) is currently open; otherwise it returns false.

Note: On macOS, you must turn on Universal Access in the System Preferences to use this function. See macOS Universal Access.

Note: Squish cannot detect dialogs opened from the web content, so this function always returns false when automating Chromium-based applications.

Boolean isBrowserOpen()

This function returns true if a browser is already running and false otherwise.

Boolean isPageLoaded(browserTab)

Boolean isPageLoaded()

This function returns true if the page in the tab referenced by browserTab has been completely loaded; otherwise it returns false. A complete and successful load implies that all of the page's objects can potentially be accessed. This function can be used with the Boolean waitFor(condition) function to wait for a page to be loaded before accessing it from a test script.

Since page loading, HTTP requests, and so on, are asynchronous, even after a call to the isPageLoaded function returns true it is essential that the Object waitForObject(objectOrName) function (or another wait function) is used to ensure that the specific objects of interest are ready to be accessed. Also, it may be necessary to pass a longer timeout to the Object waitForObject(objectOrName) function than the default 20 000 milliseconds. (See also How to Synchronize Web Page Loading for Testing.)

String lastAlertText(browserTab)

String lastAlertText()

This function returns the text that appeared in the web page's most recent alert function call in the referenced browserTab (which will be empty if no alert calls have been made).

If there are multiple alerts, the value should be cleared between alerts with clearAlertText().

clearAlertText()

This function clears the value of the String lastAlertText(browserTab).

String lastConfirmText(browserTab)

String lastConfirmText()

This function returns the text that appeared in the web page's most recent confirm function call in the referenced browserTab (which will be empty if no confirm calls have been made).

If there are multiple confirms, the value should be cleared between confirms with String clearConfirmText().

String clearConfirmText()

This function clears the value returned by String lastConfirmText(browserTab)

String lastPromptDefault(browserTab)

String lastPromptDefault()

This function returns the text that appeared in the web page's most recent prompt function call in the referenced browserTab (which will be empty if no prompt calls have been made).

String clearPromptDefault(browserTab)

This function clears the value returned by String lastPromptDefault(browserTab).

String lastPromptText(browserTab)

String lastPromptText()

This function returns the text that appeared in the web page's most recent prompt function call in the referenced browserTab (which will be empty if no prompt calls have been made).

String clearPromptText(browserTab)

This function clears the value returned by the String lastPromptText(browserTab)

loadUrl(url)

Note: This function is deprecated. Consider using startBrowser(url) if possible, or setting a the window's location.href property directly via JavaScript if you need it to return immediately. See Automating a native login for an example that compares the two.

This function opens a web browser and loads the given url.

mouseClick(objectOrName)

mouseClick(objectOrName, modifierState)

mouseClick(objectOrName, x, y)

mouseClick(objectOrName, modifierState, x, y)

This function clicks the mouse on the specified objectOrName widget. The click occurs at the top left corner of the widget or at position (x, y)—which is relative to the top left corner of the widget itself—if specified, and with the given modifierState, if specified.

See Web Object API Function Parameters for which values are valid for the modifierState.

nativeMouseClick(objectOrName, button)

nativeMouseClick(objectOrName, x, y, button)

This function simulates a native mouse click on the objectOrName widget at position x and y (if specified), otherwise at x=10 / y=10 (in the objectOrName widget's coordinates).

The button parameter is the mouse button that should be used, and must be one of MouseButton.LeftButton, MouseButton.MiddleButton, MouseButton.RightButton, or MouseButton.NoButton (to execute just a mouse move).

Note: The BrowserTab (or WebView) object containing the HTML element will be activated automatically for browser types that support this. Notable exception to this are all browsers automated through the 'Chromium-based Application' option.

Use nativeMouseClick for input fields instead of mouseClick to make sure that clicking them moves input focus into them. This properly replicates a user action. The nativeMouseClick function ensures that the browser tab of the object has input focus and that it appears in front of other windows. This cannot be accomplished through the mouseClick function, which runs as part of the web site and cannot change the operating system input focus. It can only move the focus within the web site.

openNewTab(url)

openNewTab(url, timeout)

This function opens a new tab in the browser loading the specified url. The function returns an object of the BrowserTab Class representing the newly opened tab.

The function takes an optional timeout specified in milliseconds. The function will abort the creation of the tab if creating the tab, loading the url or hooking up the loaded web page takes longer than the specified timeout. An error is generated indicating the cause for the timeout if this happens.

Note: This function is not available for all types of browsers. Currently supported are Internet Explorer, Firefox, Google Chrome, Safari >=12 and Microsoft Edge.

raiseWindow()

This function tries to raise the browser window to the top of the window stack so that no overlapping windows are above it.

rehook(browserTab)

rehook()

This is an advanced function that reloads and re-initializes the parts of Squish for Web that run inside the tab referenced by browserTab. We recommend using the clearObjectCache() function instead of this one whenever possible, since it is slightly faster and safer. The browserTab parameter is optional, in absence of it Squish for Web will rehook the initially loaded tab.

Note: If the browserTab is not specified, the call will always use the initially loaded tab even if another tab is currently active. This can lead to unexpected behavior if the test works with multiple browser tabs or windows so we suggest to always specify the browserTab parameter in new scripts.

JsObject retrieveJSObject(javascriptcode)

This function executes a JavaScript snippet and returns the value resulting from that code snippet. The returned value can be either a primitive, i.e., a string or number, or it can be a reference to a JavaScript object as JsObject.

scrollTo(objectOrName, top)

This function scrolls the browser so that the objectOrName widget is visible. You can use the optional boolean parameter top to have the object align at the top or bottom of the screen (i.e., passing true aligns at top and passing false aligns at bottom).

selectOption(objectOrName, text)

This function selects the option with the given text in the objectOrName 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.

selectOptions(objectOrName, listOfTexts)

This function selects options from the objectOrName 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.

selectOptionByValue(objectOrName, value)

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

selectOptionsByValue(objectOrName, listOfValues)

This function selects options from the objectOrName 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.

sendEvent(eventName, objectOrName, x, y, modifierState, button)

This function sends an event of type eventName to the objectOrName element. The eventName must be one of:

"mouseup"
"mousedown"
"mouseover"
"mouseout"
"mousemove"
"click"
"pointerover"
"pointerenter"
"pointerdown"
"pointermove"
"pointerup"
"pointercancel"
"pointerout"
"pointerleave"

The x and y parameters are the coordinates relative to objectOrName, where the event should occur. The modifierState is currently ignored, but you should always pass a value of 0 for it. The button must be one of 1 (left button), 2 (right button), or 4 (middle button).

Boolean setContext(context)

Note: This function is deprecated unless you disabled tab support. Consider extending existing object names with a container property that refers to the browser tab where you want the lookup to happen. If you've used setContext to select a particular frame in a web page for object lookup, consider using the Boolean setFrameContext(browserTab, frameName) overload taking a browser tab and a context name.

This function makes the specified context the active window. This context is being used as the preferred window to look up object names. This means that all object lookups that follow this command will be executed in the context of the newly active window first and only if no object is found will the lookup continue in the other known contexts. A context string is a page's "base location"—this includes any parent locations necessary to precisely identify the page (for example, if the page is actually a frame or iframe element). The location for a window is created from the HTML (or php, jsp, asp) file that is loaded in the URL. So for example for "http://yourserver.com/path/to/file.html?parameter=value" the context would be just "file.html". If the URL of the window does not have a filename like "http://yourserver.com/path/?parameter=value" then Squish will simply assume the name "index.html" In addition there may be an number added to the context if there are multiple contexts with the same filename. This is done with angle brackets around the number, so if you have two windows open for the "file.html" page in the example above the second window would use "file.html<2>" as the context name. You can easily see what contexts Squish creates and expects for a given window by using HTML_Array contextList() function to access the known windows at any time and String contextOf(window) to retrieve their name. (See also, HTML_Array contextList(), String contextOf(window), String currentContext(), Boolean setFrameContext(browserTab, frameName), waitForContextExists(context).)

This function throws a catchable script error if the context name cannot be found. You can change this behavior using the ThrowErrorOnUnknownContextNames setting in the file etc/webwrapper.ini. If the setting is set to false this function simply returns true if the given frame context name could be found and activated and false otherwise.

setFocus(objectOrName)

This function sets the input focus on the objectOrName element.

Boolean setFrameContext(browserTab, frameName)

Boolean setFrameContext(frameName)

For web pages that use frames or iframes, this function can be used to specify that the frame called frameName should be used as the current context when looking up objects inside the tab referenced by browserTab. This current context defines the preferred window to look up object names and thus all object lookups that follow it will first search for the object in the specified frame. If no object is found the lookup will fall back to search through all other frames as well as the top level page. The frameName uses a dot-separated hierarchy identifying the wanted frame. The name starts with the top-most frame in the webpage, using either the name attribute of that frame or the id attribute. The next step (if necessary) should be the name or id of a frame inside the top-most frame. Continuing this scheme any level of nested frames can be reached. As an example, consider a page which has two frames in it named leftframe and rightframe and the left frame has an iframe inside it with the id maincontent. In order to set the lookup context to this inner iframe you'd use "leftframe.maincontent" as frameName. In addition to this scheme its also possible to use the context information that Squish generates in multi-property and hierarchical names. This context information uses a slightly different format where the name of the frame is the word FRAME followed by a number. The number indicates the number of the given frame in the list of frames in a particular page starting to count at one. Using the example above again, you could use "FRAME1.FRAME1" as name for the iframe inside the left frame. In case the right frame has 2 sub frames itself you would use "FRAME2.FRAME1" and "FRAME2.FRAME2" to access these two sub frames respectively in this scheme. (See also, HTML_Array contextList(), String currentContext(), Boolean setContext(context), and waitForContextExists(context).)

setText(objectOrName, text)

This function sets the text of the objectOrName editable form element (which can be a text or textarea element) to the given text. (Compare this with the typeText(objectOrName, text) function which simulates typing the text into the form element.)

A special use-case of this function is automation of upload fields. Form fields used to select files for uploading them can be automated via setText. The input fields name should be used for the objectOrName and the the absolute path of the file to upload should be passed as the text. The setText invocation will transparently handle the file selection across platforms and browsers.

Recording setText invocations on file upload fields can often not obtain the absolute path to the file on disk as browsers prevent access to this information for security reasons. Please make sure to adjust the parameter for the absolute path accordingly.

startBrowser(url)

startBrowser(url, timeout)

startBrowser()

startBrowser(timeout)

This function starts the browser and - if specified - loads the website identified by the url parameter. If there is an error during the startup or loading of the page an error will be raised. An error will also be raised if the function is called while a browser is already running. You can query whether a browser is already running using the Boolean isBrowserOpen() function.

The function takes an optional timeout, specified in milliseconds. Squish for Web will wait the specified time for the browser to start and load the given url. After the time has elapsed an error is generated. If this parameter is not specified the Maximum Startup Timeout value will be used.

toggleExpandable(objectOrName)

This function clicks the objectOrName expandable section header web element (or raises an exception if the objectOrName isn't of type HTML_ExpandableSectionHeader Class). The click causes the expandable section to change its state to be expanded (if it isn't currently expanded) or to be unexpanded (if it is currently expanded). This function does the equivalent of clicking the mouse on the expandable section header, but without the need for (potentially unreliable) coordinates.

Expandable sections are sometimes called "accordions" or "toolboxes". (See also Expandable Section Header Support.)

typeText(objectOrName, text)

This function types the specified text (as if the user had used the keyboard) into the objectOrName editable element. (Compare this with the setText(objectOrName, text) function which sets the text for text and textarea form elements programmatically.)

waitForContextExists(context)

Note: This function is deprecated unless you disabled tab support. Consider using Object waitForObject(objectOrName) with a realname identifying a particular tab to wait for that tab or use Boolean waitFor(condition) together with Boolean hasFrameContext(browserTab, context) to wait for a particular frame to appear

This function waits until the given context has been loaded and can be accessed. The context is a URL for a particular web page displayed in the browser—the page itself may contain its own hierarchy of pages through the use of frame, iframe, and similar elements. (See also, HTML_Array contextList(), String currentContext(), Boolean setFrameContext(browserTab, frameName), Boolean setContext(context), and waitForContextExists(context).)

This function throws a catchable script error if the context name cannot be found within the given timeout. You can change this behavior using the ThrowErrorOnUnknownContextNames setting in the file etc/webwrapper.ini. If the setting is set to false this function simply returns true if the given frame context name could be found and activated and false otherwise.

waitForObjectItem(objectOrName, row, column)

waitForObjectItem(objectOrName, row, column, timeoutMSec)

Waits until the objectOrName object is accessible (i.e., it exists and is visible and enabled), and contains an item identified by row and column.

The function raises a (catchable) LookupError exception on failure, i.e., if it times out.

The function waits for a maximum of 20000 milliseconds (default), or for the number of milliseconds specified in the timeoutMSec parameter.

This function only applies to objects of these types:

Examples of objects that are supported (handled by HTML_CustomItemView Class) are GWT and SmartGWT tables.

uninstallEventHandler(eventName, handlerFunctionNameOrReference)

This function uninstalls an event handler that has been previously installed using installEventHandler(eventName, handlerFunctionNameOrReference).

Browser Object

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

String Browser.name()

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:

"Browser on Mobile Device" – For browsers on mobile devices
"Firefox" – For Mozilla Firefox
"Google Chrome" – For Google Chrome
"Chromium-based Applications (using CEF, Electron, nw.js etc.)" – For Chromium-based applications
"Microsoft Internet Explorer" – Microsoft InternetExplorer
"Microsoft Edge" – For Microsoft Edge
"Opera" – For Opera
"Other Browser" – For other browsers
"Safari" – For Safari

String Browser.majorVersion()

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

Type Browser.type()

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

Browser.Firefox – Firefox
Browser.InternetExplorer – Internet Explorer (Microsoft)
Browser.Edge – Microsoft Edge
Browser.GoogleChrome – Google Chrome
Browser.ChromiumBased – Chromium-based Applications (using CEF, Electron, nw.js etc.)
Browser.Mozilla – Mozilla
Browser.Safari – Safari (Apple)
Browser.Proxy – Proxy

Example:

function main()
{
    // ...

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

    // ...
}

BrowserTab Class

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.

string BrowserTab.title

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

string BrowserTab.url

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(url, timeout).

BrowserTab.close()

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.

BrowserTab.setUrl(url, timeout)

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.

HTML_Anchor Class

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

HTML_Anchor.click()

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

HTML_Array Class

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

Object HTML_Array.at(index)

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

int HTML_Array.length

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

HTML_Button Class

This class provides the API for HTML button and submit input elements. This class inherits the HTML_ButtonBase Class which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

HTML_Button.submit()

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

HTML_ButtonBase Class

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 which inherits the HTML_Object Class.

HTML_ButtonBase.click()

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

String HTML_ButtonBase.value

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

HTML_CheckBox Class

This class provides the API for HTML checkbox input elements. This class inherits the HTML_ButtonBase Class which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

Boolean HTML_CheckBox.checked

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

HTML_CheckBox.click()

HTML_CheckBox.click(modifierState)

HTML_CheckBox.click(modifierState, x, y)

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.

HTML_CalendarEvent Class

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

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

String HTML_CalendarEvent.description

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

DateTime HTML_CalendarEvent.endDateTime

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

DateTime HTML_CalendarEvent.startDateTime

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

String HTML_CalendarEvent.title

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

HTML_CalendarView Class

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 which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

DateTime HTML_CalendarView.date

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

int HTML_CalendarView.numVisibleEvents()

Returns the number of HTML_CalendarEvent Classs that are visible in the view.

HTML_CalendarEvent HTML_CalendarView.visibleEventAt(index)

Returns the index-th HTML_CalendarEvent Class of those that are visible in the view.

HTML_ColorField Class

This class provides the API for HTML color picker elements. This class inherits the HTML_Object Class.

String HTML_ColorField.fieldName

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

Boolean HTML_ColorField.isEnabled

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

String HTML_ColorField.rgbColor

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

HTML_CustomButton Class

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

String HTML_CustomButton.value

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

HTML_CustomButtonBase Class

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. This class inherits the HTML_Object Class.

Boolean HTML_CustomButtonBase.disabled

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

Boolean HTML_CustomButtonBase.showText

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

String HTML_CustomButtonBase.text

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

Boolean HTML_CustomButtonBase.visible

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

HTML_CustomComboBox Class

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. This class inherits the HTML_FormElement Class which inherits the HTML_Object Class.

See Combobox Support for how to add support for custom comboboxes.

Boolean HTML_CustomComboBox.hasOption(option)

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

String HTML_CustomComboBox.selectedOption

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

HTML_CustomCheckbox Class

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. (See also CheckBox Support.)

Boolean HTML_CustomCheckbox.checked

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

HTML_CustomItem Class

This class provides an abstract item API to access any supported item type contained in a custom item view (HTML_CustomItemView Class.) This item class inherits the HTML_Object Class. (See How to set up Support for Complex Widgets 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:

HTML_CustomItem HTML_CustomItem.childItem()

HTML_CustomItem HTML_CustomItem.childItem(column)

Returns a reference to this item's first child item (of type HTML_CustomItem Class) 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.

int HTML_CustomItem.column

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

HTML_CustomItem HTML_CustomItem.findItem(row, column)

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.

HTML_Object HTML_CustomItem.itemHandle()

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

HTML_CustomItemView HTML_CustomItem.itemView()

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

HTML_CustomItem HTML_CustomItem.nextSibling()

HTML_CustomItem HTML_CustomItem.nextSibling(column)

Returns a reference to this item's next "sibling" item (of type HTML_CustomItem Class); 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.

int HTML_CustomItem.numRows

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.

Boolean HTML_CustomItem.open

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.

HTML_CustomItem HTML_CustomItem.parentItem()

HTML_CustomItem HTML_CustomItem.parentItem(column)

Returns a reference to this item's parent item (of type HTML_CustomItem Class); 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.

String HTML_CustomItem.realType

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.

int HTML_CustomItem.row

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.

Boolean HTML_CustomItem.selected

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.

String HTML_CustomItem.text

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.

HTML_CustomItemView Class

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 which inherits the HTML_Object Class. (See How to set up Support for Complex Widgets 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.

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:

HTML_CustomItem HTML_CustomItemView.childItem()

HTML_CustomItem HTML_CustomItemView.childItem(column)

Returns a reference to the view's first item (of type HTML_CustomItem Class); 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.

HTML_CustomItemView.clickHandle(itemName)

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

HTML_CustomItemView.clickItem(itemName)

HTML_CustomItemView.clickItem(row, column)

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.

String HTML_CustomItemView.columnCaption(column)

Returns the view's caption for the given column.

HTML_CustomItemView.doubleClickItem(itemName)

HTML_CustomItemView.doubleClickItem(itemName, modifierState)

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

HTML_CustomItem HTML_CustomItemView.findItem(itemName)

HTML_CustomItem HTML_CustomItemView.findItem(row, column)

This function returns a reference to the item (of type HTML_CustomItem Class) 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.

Boolean HTML_CustomItemView.hasItem(itemName)

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

Boolean HTML_CustomItemView.isOpen(itemName)

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.

Boolean HTML_CustomItemView.isSelected(itemName)

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

int HTML_CustomItemView.numColumns

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.

int HTML_CustomItemView.numRows

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.

String HTML_CustomItemView.realType

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.

HTML_CustomRadioButton Class

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. (See also RadioButton Support.)

Boolean HTML_CustomRadioButton.selected

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

HTML_CustomSelectList Class

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 which inherits the HTML_Object Class. (See also Select List Support and HTML_Select Class.)

Boolean HTML_CustomSelectList.hasOption(option)

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

String HTML_CustomSelectList.selectedOptions

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.

HTML_CustomText Class

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 which inherits the HTML_Object Class. (See also Text Field Support and HTML_Text Class.)

HTML_CustomText.focus()

This function puts the keyboard focus into the text field.

String HTML_CustomText.value

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

HTML_DateChooser Class

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

DateTime HTML_DateChooser.date

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

See the chooseDate(objectOrName, date) function and also, Date Picker Support.

HTML_Document Class

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

Note: To create a visual verification point covering the whole page, select a child of the document object, such as the BODY element. There is no visual representation of HTML_Document objects available.

HTML_Object HTML_Document.getElementById(id)

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

HTML_Array HTML_Document.getElementsByTagName(tagName)

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

HTML_ExpandableSectionHeader Class

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

Boolean HTML_ExpandableSectionHeader.isEnabled

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

Boolean HTML_ExpandableSectionHeader.isExpanded

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

String HTML_ExpandableSectionHeader.title

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

HTML_Form Class

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

HTML_Form.submit()

Invoke's the form's "submit" action.

HTML_FormElement Class

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.

Boolean HTML_FormElement.disabled

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

HTML_FormElement.focus()

Gives the keyboard focus to this form element.

String HTML_FormElement.type

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

HTML_ImageButton Class

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 which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

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

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

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

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

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

HTML_MenuButton Class

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

This function returns the HTML_Menu Class 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 Boolean isNull(object) function.)

HTML_MenuItem Class

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

String HTML_MenuItem.iconUrl

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.

Boolean HTML_MenuItem.isChecked

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

Boolean HTML_MenuItem.isEnabled

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

Boolean HTML_MenuItem.isSeparator

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

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

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

String HTML_MenuItem.text

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

HTML_Object Class

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 the Object findObject(objectName) function.

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

ScreenRect HTML_Object.boundingClientRect

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.

String HTML_Object.className()

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

HTML_Object.click()

HTML_Object.click(modifierState)

HTML_Object.click(modifierState, x)

HTML_Object.click(modifierState, x, y)

HTML_Object.click(modifierState, x, y, button)

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

HTML_Object.css

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 KeyValueMap object.properties(object) 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 type.

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

pythonjavascriptperlrubytcl

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

String HTML_Object.domClassName

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 String HTML_Object.className() for how to use it in multi property names.

String HTML_Object.domPath

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.

HTML_Object.doubleClick()

HTML_Object.doubleClick(modifierState)

HTML_Object.doubleClick(modifierState, x)

HTML_Object.doubleClick(modifierState, x, y)

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.

HTML_XPathResult HTML_Object.evaluateXPath(statement)

Evaluates the XPath statement and returns an HTML_XPathResult Class 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.

HTML_Object HTML_Object.firstChild()

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 HTML_Object.lastChild(), HTML_Object HTML_Object.nextSibling(), HTML_Object.numChildren, HTML_Object HTML_Object.parentElement(), and HTML_Object HTML_Object.previousSibling().)

bool HTML_Object.hasFocus

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.

int HTML_Object.height

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

String HTML_Object.hierarchicalQualifiedName()

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

Object HTML_Object.id

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

String HTML_Object.innerHTML

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

String HTML_Object.innerText

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

HTML_Object HTML_Object.shadowRoot

This read-only property provides access to the shadow root node of the given object, if there is any. The property returns a HTML_Object instance which can be used to access children inside the Shadow DOM.

This property will only return a shadow root object if the element has a shadow root node attached to it and the shadow root has been created in open mode. See Mozilla Shadow DOM documentation for more details on Shadow DOM.

In order to navigate from the shadow root back to the containing element please use HTML_Object.parentElement().

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

HTML_Object.invoke(methodName)

HTML_Object.invoke(methodName, argument1)

HTML_Object.invoke(methodName, argument1, argument2)

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.

HTML_Object HTML_Object.lastChild()

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 HTML_Object.firstChild(), HTML_Object HTML_Object.nextSibling(), HTML_Object.numChildren, HTML_Object HTML_Object.parentElement(), and HTML_Object HTML_Object.previousSibling().)

String HTML_Object.name()

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

HTML_Object HTML_Object.nextSibling()

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 HTML_Object.firstChild(), HTML_Object HTML_Object.lastChild(), HTML_Object.numChildren, HTML_Object HTML_Object.parentElement(), and HTML_Object HTML_Object.previousSibling().)

int HTML_Object.numChildren

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

HTML_Object.openContextMenu()

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

HTML_Object HTML_Object.parentElement()

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 HTML_Object.firstChild(), HTML_Object HTML_Object.lastChild(), HTML_Object HTML_Object.nextSibling(), HTML_Object.numChildren, and HTML_Object HTML_Object.previousSibling().)

HTML_Object 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 HTML_Object.firstChild(), HTML_Object HTML_Object.lastChild(), HTML_Object HTML_Object.nextSibling(), HTML_Object.numChildren, and HTML_Object HTML_Object.parentElement().)

String HTML_Object.property(name)

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(name, value).)

ScreenRect HTML_Object.screenRect

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.

HTML_Object.scrollTo(top)

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(objectOrName, top) function.)

HTML_Object.setProperty(name, value)

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

HTML_Style HTML_Object.style()

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

String HTML_Object.styleDisplay

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.

String HTML_Object.styleVisibility()

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

This is a synthetic property, see Synthetic Properties in Web Objects for more information.

String HTML_Object.tagName

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

String HTML_Object.title

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

Boolean HTML_Object.visible

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 that reflected the value of a visible attribute on the object instead of reflecting the object's visibility according to CSS. This behavior can be restored by setting the BackwardsCompatibleVisiblePropertyForHTML_Object setting in the file etc/webwrapper.ini to true.

int HTML_Object.width

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

int HTML_Object.x

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

int HTML_Object.y

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

HTML_Option Class

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

Boolean HTML_Option.defaultSelected

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

int HTML_Option.index

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

Boolean HTML_Option.selected

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

String HTML_Option.text

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

String HTML_Option.value

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

HTML_RadioButton Class

This class provides the API for HTML radio button input elements. This class inherits the HTML_ButtonBase Class which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

Boolean HTML_RadioButton.checked

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

HTML_RadioButton.click()

HTML_RadioButton.click(modifierState)

HTML_RadioButton.click(modifierState, x, y)

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.

HTML_Select Class

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

Boolean HTML_Select.isMulti()

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

HTML_Option HTML_Select.optionAt(index)

Returns the option (HTML_Option Class) 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).

HTML_Array HTML_Select.options()

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

listOfTexts HTML_Select.selectedTexts

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.

listOfValues HTML_Select.selectedValues

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.

listOfNumbers HTML_Select.selectedIndexes

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.

listOfNumbers HTML_Select.selectedLabels

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.

HTML_Select.deselectByValues(values)

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

HTML_Select.deselectByTexts(texts)

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

HTML_Select.deselectByIndexes(indexes)

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

int HTML_Select.selectedIndex

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

String HTML_Select.selectedOption

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.

HTML_Select.setSelectedOption(text)

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.

HTML_Select.setSelectedOptions(listOfTexts)

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.

HTML_Select.setSelectedOptionByValue(value)

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

HTML_Select.setSelectedOptionsByValue(listOfValues)

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.

HTML_ProgressBar Class

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

int HTML_ProgressBar.maximum

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

int HTML_ProgressBar.minimum

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

int HTML_ProgressBar.value

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

HTML_Style Class

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

String HTML_Style.value(name)

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

HTML_Table Class

This class provides the API for HTML tables. This class inherits the HTML_Object Class.

Number HTML_Table.rowCount

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.

Number HTML_Table.columnCount

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.

HTML_Object HTML_TabWidget.cellAt(row, column)

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.

HTML_Tab Class

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

Boolean HTML_Tab.enabled

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

String HTML_Tab.icon

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.

String HTML_Tab.title

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

HTML_TabWidget Class

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

HTML_TabWidget.clickTab(tabTitle)

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.

HTML_TabWidget.findTab(tabTitle)

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

HTML_TabWidget.getCurrentTab()

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

HTML_Text Class

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 which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

HTML_TextArea Class

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 which inherits the HTML_FormElement Class which inherits the HTML_Object Class.

HTML_TextBase Class

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 which inherits the HTML_Object Class.

String HTML_TextBase.value

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

HTML_TextBase.selectAll()

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

String HTML_TextBase.selectedText

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.

HTML_XPathResult Class

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

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

Boolean HTML_XPathResult.booleanValue

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

Number HTML_XPathResult.numberValue

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

HTML_Object HTML_XPathResult.singleNodeValue()

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

int HTML_XPathResult.snapshotLength

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.

String HTML_XPathResult.stringValue

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

HTML_Object HTML_XPathResult.snapshotItem(index)

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

JsObject Class

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

String JsObject.property(name)

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.

String JsObject.call(methodname, methodarguments)

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.

CssColor Type

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

CssColor CssColor.fromRgb(red, green, blue)

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:

pythonjavascriptperlrubytcl

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]

CssColor CssColor.fromRgba(red, green, blue, alpha)

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:

pythonjavascriptperlrubytcl

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:

int CssColor.red

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

int CssColor.green

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

int CssColor.blue

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

double CssColor.alpha

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

boolean CssColor.isValid

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.

JavaScript Extension API

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 for Web frameworks that are not currently supported, one can 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, use the Qt Support Center if you want us to implement the extension for your custom widgets or framework for you.

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 an extensive example of how to use the Squish Object see the subsections that follow, starting with Concepts and Setup. See also, Writing HTML Class-Specific Extensions.

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

ObjectName Object

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: Since Squish 3.4 it has been possible for custom wrappers to produce a list of the properties that did not match, so as to provide more 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 whitepace 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.

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.

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.

ObjectName Object

This object's methods provide access to properties that make up an object. It allows adding properties, changing values, getting a list of property names and converting the name to a multiproperty name string.

ObjectName.addProperty(propertyName, propertyValue)

This function adds or replaces the property with the propertyName and the property value given as propertyValue. The property value has to be either a String for strict matching properties, a Squish.WildCardPropertyValue Squish.WildCardPropertyValue(wildcardString) or a Squish.RegExPropertyValue Squish.RegExPropertyValue(regexString).

PropertyValue ObjectName.getPropertyValue(propertyName)

This function returns the value of the property with the propertyName or undefined if the object name does not have that property. The returned value is either a String for strict matching properties, a Squish.WildCardPropertyValue Squish.WildCardPropertyValue(wildcardString) or a Squish.RegExPropertyValue Squish.RegExPropertyValue(regexString).

ObjectName.removeProperty(propertyName)

This function removes the property with the propertyName from this object name.

ListOfStrings ObjectName.getPropertyNames()

This function returns the list of property names currently part of this object name.

Concepts and Setup

This extension is enabled by specifying the location of the JavaScript file that implements it. When Squish hooks into the Web browser, it will evaluate the JavaScript in the extension file inside the browser.

Inside the JavaScript extension file it is possible to use Squish's programming interface to hook into the object recognition, name generation, and other functionality provided by the framework. Also, by implementing certain JavaScript hook-functions, it is possible to expose the APIs of the framework's custom widgets to make them accessible to test scripts.

To specify a JavaScript extension file (and assuming for the sake of example, that the file is called C:\squishext\myextension.js), add a line such as this to the squish.ini file located in your Squish installation's etc subdirectory:

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

If you do distributed testing, this only needs to be done on the machine where squishrunner or the Squish IDE are used.

The API which can be used to implement the extensions is documented in the Squish Object—this object provides methods that support Squish's JavaScript extension. The following sections explain the object's API, and show some examples of its use.

How to set up Support for Simple Widgets

To avoid recording superfluous mouse clicks, Squish only records clicks on DOM elements which are known to respond to clicks. To decide whether an element responds to clicks, Squish checks to see if the element has a mouse event handler set (such as an onClick function), or if the element is a known clickable widget—such as a form input element, a link, and so on.

If your JavaScript library comes with custom clickable widgets such as custom buttons, you can tell Squish about them using the Squish.registerWidget(argumentObject) JavaScript function. This function expects a named argument list (i.e., an object) which specifies the DOM class of the element and the type of events that should be recorded.

For example, let's assume that you have a special button implementation which is represented in the DOM as:

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

To make Squish record mouse click events for this type of widget, add the following line to your extension JavaScript file:

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

Now, when you record a script and click this button, Squish will record mouseClick(objectOrName) statements.

To identify widgets when replaying a test, Squish defaults to using its own built-in name generation algorithm. In this specific example the innerText will be used since no id or name is set, and this is sufficient in this case. So, the generated real name for this object will be, {tagName='SPAN' innerText='Click Me'}.

It is possible to supplement Squish's name generator with your own name generation algorithm—this is particularly useful if you want to make use of custom properties from a web framework's custom elements when names are generated. This is covered in the next section.

How to Extend the Name Generator and Identification

To produce a name for a widget, Squish generates a list of property pairs identifying the object. Squish uses a set of pre-defined properties such as tagName, id, name, title, innerText, and a few others.

If the properties do not uniquely identify the object, an occurrence property is added to the name which specifies which of the objects matching the other properties is supposed to be selected.

With the exception of tagName—which is the one mandatory property that all names must have— the properties are optional and can be chosen freely.

In some cases it might be desirable to use custom properties in the names of certain types of objects. To do this, it is possible to specify your own hook function which will then be called to generate names for your own widgets. And if necessary, a hook function that performs the property matching that is done when objects are searched for can also be installed.

How to Implement a Custom Name Generator

To show how to implement a custom name generator, we will start with an example menu element:

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

First, we must register the menu items as clickable widgets using the Squish.registerWidget(argumentObject) function:

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

(We already saw an example of using this function earlier: How to set up Support for Simple Widgets.)

In this example we are going to use the menuID attribute, along with the DOM class, and the parent element's ID, to give our menu elements (i.e., each menuItem <span> tag), their unique identifying names.

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

We have added this function as a property of a custom myUiExtension object. In the implementation we check if the object is an object of the type we want to handle, that is, menuItem <span> tag. If the type is right we use custom code to create a unique name for it; otherwise we return undefined—this isn't a valid name value, so Squish will try each of the other registered name generation hook functions (if any), and if all of them return undefined (or if there aren't any), Squish will fall back to using its own default name generator.

To determine if the element is one of those we want to handle, we check to see if its tag name is SPAN and if its DOM class is menuItem. For this second check we use the Boolean Squish.hasClassName(objectOrName, className) helper function, which returns a true value if any of the DOM object's DOM classes has the same name as the given class name.

If the element is of the right type we create a name for it using our own custom name generation algorithm. A real (multi-property) name consists of one or more property name–value pairs, all contained in braces. Here we start by using the String Squish.propertiesToName(objectOrName, listOfPropertyNames) function to create a name string containing the given property names and values; then we add two additional property pairs, one for the parent ID and another for the class name. Finally, we use the String Squish.uniquifyName(name, objectOrName) function to ensure that we produce a unique name. This function accepts a real (multi-property) name as a string and the object the name is supposed to identify, and will return the name unchanged if possible, or will return it with the addition of an occurrence property if it is necessary to distinguish the name further to ensure its uniqueness.

So, given the example shown above, if the object was the fileOpen menu item, the String Squish.propertiesToName(objectOrName, listOfPropertyNames) function would give us the string "tagName='SPAN' menuID='fileOpen'", and with the addition of the parent ID and class name, the final name we would end up with is "{tagName='SPAN' menuID='fileOpen' parentID='fileMenu' className='menuItem'}".

We could not use the String Squish.propertiesToName(objectOrName, listOfPropertyNames) function for either the parent ID or for the class name properties. In the case of the parent ID this is because the parentID is not a regular property, but rather a pseudo-property, so we must handle it ourselves. Once part of a real name though, Squish will be able to work with it like any other property. In the case of the class name the only reason we cannot use the String Squish.propertiesToName(objectOrName, listOfPropertyNames) function is because the DOM property name is class while Squish uses the JavaScript className name. Also, a DOM class may contain multiple values while we only want to specify one—menuItem.

At the end we make sure that any special characters are escaped properly—for this we use the standard JavaScript escape function. And then we return the result.

Once our name generator function is ready, we must inform Squish of its existence so that it is used when names are needed. This is done by registering it as a hook function:

Squish.addNameOfHook(myUiExtension.nameOf);

Here we have used the Squish.addNameOfHook(function) function to register the myUiExtension.nameOf function as a name generator function. From now on Squish will use this function whenever it needs to generate a real name, and will fall back to using any other generator function (and its own built-in default name generator function as a last resort), if the function returns undefined.

How to Implement a Custom Name Matcher

When searching for an object by name, Squish iterates over all objects in the DOM tree and queries the specified object properties to see if their values match those of the name.

Using a custom name matcher hook makes it possible to consider a name's pseudo-properties (such as the parentID we saw earlier), when searching for a matching object. Since Squish has no knowledge about any pseudo-properties we have created, we must implement a custom function to perform the lookup and name matching and that accounts for our pseudo-properties.

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

Again, we have implemented this function as a property of our custom myUiExtension object. Squish will pass the object, the property name and the expected value as specified in the name to this function.

If the given property is our pseudo-property, we use the built-in Boolean Squish.matchProperty(valueObject, property) function to determine if there is a match. Otherwise we return undefined; in such cases Squish will try all the other match objects that are registered (if any), and if none of these gives a definitive true or false (or if there aren't any), it falls back on its own internal name matching function. Note that the valueObject is not simply a string but rather an object which contains a string value and a flag denoting whether the matching should be based on a literal string comparison, wildcard matching, or regular expression matching. (See also Improving Object Identification.)

In this example we have chosen to handle the parentID pseudo-property ourselves; and by returning undefined for any other property we pass on the matching work to Squish for anything other than the pseudo-property we are interested in.

The custom name matching setup is completed by installing the hook:

Squish.addMatchObjectHook(myUiExtension.matchObject);

The Squish.addMatchObjectHook(function) function can be used to register as many name matching functions as we want.

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(objectOrName, itemText) function and to the clickTreeHandle(objectOrName, itemText) function will be recorded when interacting with the supported item view widget. In addition, using the HTML_CustomItemView Class and HTML_CustomItem Class abstraction API, the test scripts will be able to access the widget and work with its items, states, and properties.

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.

Hooks for recording high-level GUI operations

Functions to implement in the toolkit's extension object:

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 (treeName, itemName) function call should be recorded. Similarly, a click on a tree item's handle should be recorded as (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.

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:

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 the Boolean Squish.hasClassName(objectOrName, className) 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.

Event Objects

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

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.

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:

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.

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:

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:

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 for more information about creating names.)

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

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 String Squish.nameOf(objectOrName) 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.

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.

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.

Hooks for replaying high-level GUI operations

Functions to implement in the view's extension object:

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.

Find Item

To support replaying clicks on items (clickItem(objectOrName, itemText)), 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:

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.

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:

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.

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.

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:

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 the built-in version returns the innerText anyway.

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:

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.

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:

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.

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

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:

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

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.

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.

Writing HTML Class-Specific Extensions

To make Squish able to record and playback specific objects of custom HTML widget types we can implement extensions (like the one for GWT Trees described earlier) for the particular types we are interested in. Each type has its own specific requirements. Here are some quick links to the supported types:

Button Support

To make Squish recognize a custom button widget a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "custom_button_name" (e.g., "custom_button_CustomButton").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomButtonExtension). This object must provide the following methods:

click(buttonElement) — emulate a click on the button; this should use the Squish.mouseClick(objectOrName) function or the Squish.clickButton(buttonElement) function as appropriate.
getText(buttonElement) — returns the button's text
getTooltip(buttonElement) — returns the button's tool tip text (which may be empty)
getValue(buttonElement) — return the button element's data value
isDisabled(buttonElement) — return true if the button element is disabled; otherwise (i.e., if the button element is enabled), return false
isTextShown(buttonElement) — returns true if the button is showing text or false if the button is showing an image
setDisabled(buttonElement, disable) — enable the button element if disable is false; otherwise disable it
setText(buttonElement, text) — sets the button's text to the given text
setTextShown(buttonElement, showText) — sets the button to show text (taken from its text property) if showText is true; otherwise sets the button to show an image
setTooltip(buttonElement, tip) — sets the button's tool tip to the given tip text
setValue(buttonElement, value) — change the button element's data value to the given value

In addition to the above, extensions could also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should make sure that the value parameter is added to the returned string and contains the value of the text field.

See also the Squish.clickButton(buttonElement) function and the HTML_CustomButtonBase Class and the HTML_CustomButton Class.

Combobox Support

To make Squish recognize a custom combobox a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "custom_combobox_name" (e.g., "custom_combobox_CustomComboBox").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomComboBoxExtension). This object must provide the following methods:

hasOption(comboboxElement, optionValue) — returns true if the given combobox element has an entry with the given optionValue
getSelectedOption(comboboxElement) — returns the combobox element's currently selected entry
setSelectedOption(comboboxElement, optionValue) — selects the given optionValue in the given combobox element

In addition to the above, extensions should also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should ensure that the option value parameter is added to the returned string and that it contains the value of the combobox's currently selected entry.

Furthermore, extensions should also implement an event type hook using the Squish.addEventTypeHook(function) function if the combobox doesn't generate "change" events. For such comboboxes, the extension can hook into mouse events or similar and return "change" from the hook function. This is important for recording, since when Squish sees a change-event with a value parameter it will record a call to the selectOption(objectOrName, text) function rather than generic mouse clicks.

Calendar Event Support

To make Squish recognize a custom calendar event a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "calendarevent_name" (e.g., "calendarevent_CustomCalendarEvent").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomCalendarEventExtension). This object must provide the following methods:

getDescription(calendarEventElement) — return the calendar event's description text or undefined if it doesn't have any.
getEndDateTime(calendarEventElement) — return a JavaScript Date object with the calendar event's end date/time.
getStartDateTime(calendarEventElement) — return a JavaScript Date object with the calendar event's start date/time.
getTitle(calendarEventElement) — return the calendar event's title text.
setDescription(calendarEventElement, text) — set the calendar event's description to the given text.
setEndDateTime(calendarEventElement, jsDate) — set the calendar event's end date/time to the given jsDate (which must be a JavaScript Date object).
setStartDateTime(calendarEventElement, jsDate) — set the calendar event's start date/time to the given jsDate (which must be a JavaScript Date object).
setTitle(calendarEventElement, text) — set the calendar event's title to the given text.

Calendar View Support

To make Squish recognize a custom calendar view widget a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "calendarview_name" (e.g., "calendarview_CustomCalendarView").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomCalendarViewExtension). This object must provide the following methods:

getVisibleEventCount(calendarViewElement) — return the number of HTML_CalendarEvent Class's that are visible in the calendar view.
getVisibleEventAt(calendarViewElement, index) — return the calendar view's index-th visible HTML_CalendarEvent Class.
getDate(calendarViewElement) — return the calendar view's currently selected date/time as a JavaScript Date object.
setDate(calendarViewElement, jsDate) — set the calendar view's current date/time (i.e., the date/time that is shown) to the given jsDate which must be a JavaScript Date object.

CheckBox Support

To make Squish recognize a custom checkbox a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "custom_checkbox_name" (e.g., "custom_checkbox_CustomCheckBox").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomCheckBoxExtension). This object must provide the following methods:

isChecked(checkboxElement) — return whether the element is checked or not.
setChecked(checkboxElement, checked) — check the element if checked is true; otherwise uncheck it.

Color Picker Support

To make Squish recognize a custom color picker widget a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "colorfield_name" (e.g., "colorfield_CustomColorPicker").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomColorPickerExtension). This object must provide the following methods:

getFieldName(colorFieldElement, fieldName) — returns the color field element's label or an empty string if it hasn't got one
getRgbColor(colorFieldElement) — returns the color field element's color in HTML format (i.e., "#RRGGBB")
isEnabled(colorFieldElement) — returns whether the color field element is enabled
setEnabled(colorFieldElement, enabled) — enable the color field element if enabled is true; otherwise disable it
setFieldName(colorFieldElement, fieldName) — set the color field's label to the given fieldName
setRgbColor(colorFieldElement, htmlRGBvalue) — set the color field's color to the given htmlRGBvalue (which must be an HTML color string of the form "#RRGGBB")

In addition to the above, extensions should also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should return the information necessary to record a call to the chooseColor(objectOrName, htmlRGBvalue) function, so should at least provide the color itself (in HTML form, i.e., "#RRGGBB"), and optionally a label. Specifying a label is useful if the object on which the event occurred isn't a color field but something else such as a color picker's OK button; this allows interactions with the color dialog to be ignored.

Furthermore, extensions should also implement an event type hook using the Squish.addEventTypeHook(function) function. This function should return a chooseColor event type (e.g., if the choosing of a color was done by typing or by clicking a color or by clicking a color picker's OK button), or a chooseColorIncomplete event type if interactions with the color picker should not be recorded.

See also the chooseColor(objectOrName, htmlRGBvalue) function and the HTML_ColorField Class.

Date Picker Support

To make Squish recognize a custom date picker widget a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "datechooser_name" (e.g., "datechooser_CustomDatePicker").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomDatePickerExtension). This object must provide the following methods:

getDate(dateChooserElement) — return the date chooser element's current date as a JavaScript Date object.
setDate(dateChooserElement, jsDate) — set the date chooser element's current date to the given date. The jsDate is a JavaScript Date object.

In addition to the above, extensions should also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should return the information necessary to record a call to the chooseDate(objectOrName, date) function as returned by the String Squish.createChooseDateInformation(jsDate) function.

It may also be useful to implement an event type hook using the Squish.addEventTypeHook(function) function. This hook should return the special "ignoreEvent" type when clicks on the date picker are being used for navigation (e.g., changing the year or month), rather than actually picking a date.

See also the chooseDate(objectOrName, date) function and the HTML_DateChooser Class.

Expandable Section Header Support

Expandable sections are sometimes called "accordions" or "toolboxes".

To make Squish recognize a custom expandable section header widget, a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "expandablesectionheader_name" (e.g., "expandablesectionheader_CustomAccordion").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomAccordionExtension). This object must provide the following methods for expandable section header widgets:

click(headerElement) — click on the header element and toggle its state (i.e., expand an unexpanded header, or unexpand an expanded header)
getTitle(headerElement) — return the header element's title text
isEnabled(headerElement) — return whether the header element is enabled
isExpanded(headerElement) — return whether the header element is expanded
setEnabled(headerElement, enable) — enable the header element if enabled is true; otherwise disable it
setExpanded(headerElement, expand) — expand the header element if expand is true; otherwise unexpand it
setTitle(headerElement, title) — set the header element's title text to the given title text

See also, the toggleExpandable(objectOrName) function and the HTML_ExpandableSectionHeader Class .

To make Squish recognize a menu or menu bar widget, a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "menu_name" (e.g., "menu_CustomMenu").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomMenuExtension). This object must provide the following methods for menu widgets:

findItemByIconUrl(menuElement, iconUrl) — return the HTML menu item element for the menu item that has the given iconUrl.
findItemByText(menuElement, text) — return the HTML menu item element for the menu item that has the given text.
getMenuItemAt(menuElement, index) — return the HTML menu item element at the given index position.
getMenuItemCount(menuElement) — return the number of HTML menu item elements in the given menuElement.

In addition to the above, extensions should also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should return the information necessary to record a call to the clickItem(objectOrName, itemText) function as returned by the String Squish.createClickItemInformationForMenuItem(menuElement, menuText) function. (Without the hook function, no calls to the clickItem(objectOrName, itemText) function will be recorded.)

To make Squish recognize a menu button widget, a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "menubutton_name" (e.g., "menubutton_CustomMenuButton").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomMenuButtonExtension). This object must provide the following method for menu button widgets:

getMenu(menuButtonElement) — return the HTML menu element associated with the given menuButtonElement, or undefined if there isn't one.

Progress Bar Support

To make Squish recognize a progress bar widget, a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "progressbar_name" (e.g., "progressbar_CustomProgressBar").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomProgressBarExtension). This object must provide the following methods for progress bar widgets:

getMaximum(progressBarElement) — return an integer that corresponds to the progress bar's maximum value
getMinimum(progressBarElement) — return an integer that corresponds to the progress bar's minimum value
getValue(progressBarElement) — return an integer that corresponds the amount of progress shown by the progress bar
setValue(progressBarElement, value) — set the progress bar's value to the given value which should be between the progress bar's minimum and maximum values inclusive

RadioButton Support

To make Squish recognize a custom radiobutton a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "custom_radiobutton_name" (e.g., "custom_radiobutton_CustomRadioButton").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomRadioButtonExtension). This object must provide the following methods:

isSelected(radiobuttonElement) — return whether the element is selected (checked) or not.
setSelected(radiobuttonElement, selected) — select (check) the element if selected is true; otherwise unselect (uncheck) it.

See also the HTML_CustomRadioButton Class.

Select List Support

To make Squish recognize a custom select list a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "custom_selectlist_name" (e.g., "custom_selectlist_CustomSelectList").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomSelectListExtension). This object must provide the following methods:

hasOption(selectlistElement, optionValue) — returns true if the given select list element has an entry with the given optionValue
getSelectedOptions(selectlistElement) — returns the select list element's currently selected entries using the format described in the the HTML_CustomSelectList.selectedOptions property.
setSelectedOption(selectlistElement, multioptionString) — replaces the current option string with the given multioptionString which must be in the format described in the HTML_CustomSelectList.selectedOptions property.

In addition to the above, extensions should also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should make sure that the "value" parameter is added to the returned string and contains the value of the currently selected entry in the select list or a string with the values of all the selected entries. For the latter the ArrayOfStrings Squish.getSelectedOptionTexts(selectElement) function can be used.

Furthermore, extensions should also implement an event type hook using the Squish.addEventTypeHook(function) function if the select list doesn't generate "change" events. For such select lists, the extension can hook into mouse events or similar and return "change" from the hook function. This is important for recording, since when Squish sees a change-event with a value parameter it will record a call to the selectOption(objectOrName, text) function rather than generic mouse clicks.

See also the HTML_CustomSelectList Class.

To make Squish recognize a custom tab widget a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "tabwidget_name" (e.g., "tabwidget_CustomWidgets") for the tab widget itself and of the form "tabitem_name" for individual tabs.

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomWidgetsExtension). This object must provide the following methods for tab widgets:

clickTab(tabWidgetElement, tabTitle) — click on the given tab widget's tab with the given title text if there is one.
getCurrentTab(tabWidgetElement) — return the currently selected (i.e., top-most) tab element in the given tab widget
findTab(tabWidgetElement, tabTitle) — return the given tab widget's tab with the given tab title if there is one

The tab elements returned by the getCurrentTab and findTab methods must provide the following methods:

getIcon(tabElement) — return the URL of the tab element's icon or an empty string if it hasn't got one
getTitle(tabElement) — return the tab element's title text
isEnabled(tabElement) — return whether the tab element is enabled
setEnabled(tabElement, enabled) — enable the tab element if enabled is true; otherwise disable it
setIcon(tabElement, iconUrl) — set the tab element's icon URL to the given iconUrl
setTitle(tabElement, tabTitle) — set the tab element's title text to the given tabTitle text

In addition to the above, extensions should also implement an event to string hook using the Squish.addEventToStringHook(function) function. This function should return the information necessary to record a call to the clickTab(objectOrName, tabTitle) function as returned by the String Squish.createClickTabInformation(tabWidgeElement, tabTitle) function. (Without the hook function, no calls to the clickTab(objectOrName, tabTitle) function will be recorded.)

See also, the clickTab(objectOrName, tabTitle) function and the String Squish.createClickTabInformation(tabWidgeElement, tabTitle) function, and the HTML_Tab Class and HTML_TabWidget Class classes.

Text Field Support

To make Squish recognize a custom text field a suitable custom typeOf function must be defined and registered in an extension using the Squish.addTypeOfHook(function) function. The registered function should return a string of the form "customtext_name" (e.g., "customtext_CustomTextField").

In addition to registering the hook function, the extension must provide a JavaScript object called nameExtension (e.g., CustomTextFieldExtension). This object must provide the following methods:

getValue(textFieldElement) — return the element's current text.
setFocus(textFieldElement) — move the keyboard focus to the given textFieldElement.
setValue(textFieldElement, text) — set the text field element's current text to the given text.