Web Object API

Squish for Web provides a comprehensive API for Web Objects, which is documented here in its entirety. Some of these APIs are also available when testing embedded web browsers in other Squish editions.

Testing custom AJAX/DHTML/JavaScript widgets

The Web Object Extension API explains how to support testing of custom AJAX/DHTML/JavaScript widgets.

Web Object API Functions

activateBrowserTab

Changes the active tab in the browser

activeBrowserTab

Returns the active browser tab.

attachToBrowser

Connects Squish to an already running web browser instance.

automateLogin

Automates interaction with a native browser's authentication dialog.

browserTabs

Returns a list of active BrowserTab.

cancelPrompt

Cancels the JavaScript 'prompt' dialog.

chooseColor (Web)

Simulates choosing an HTML color from a color picker.

chooseDate

Simulates user interaction with a date picker.

chooseFile (Web)

Automates interaction with a file chooser.

clearObjectCache

Forces a refresh of Squish's internal object cache.

clickButton (Web)

Clicks a button.

clickItem (Web)

Clicks on an item in a view widget.

clickLink

Clicks on an anchor (hyperlink).

clickTab (Web)

Clicks on a tab in a tab widget.

clickTreeHandle

Clicks expand/collapse on a tree item.

closeAlert

Clicks 'Ok' in a JavaScript alert dialog.

closeConfirm

Clicks 'Yes' on a JavaScript 'confirm' dialog.

closePrompt

Types text into a JavaScript 'prompt' dialog.

closeWindow (Web)

Closes the browser window.

doubleClick (Web)

Double-clicks the mouse on a widget.

dragAndDrop (Web)

Performs a drag and drop operation.

evalJS

Evaluates a string of JavaScript code.

hasFrameContext

Returns true if a browser tab accessible to Squish has a matching context.

installEventHandler (Web)

Installs a global event handler.

isBrowserDialogOpen

Returns true if a native browser dialog is open.

isBrowserOpen

Returns true if a browser is running and hooked to Squish.

isPageLoaded

Returns true if the page has been completely loaded.

lastAlertText

Returns the text reported by the last 'alert' function.

lastConfirmText

Returns the text reported by the last 'confirm' function.

lastPromptDefault

Returns the default text from the last 'prompt' dialog.

lastPromptText

Returns the text from the last 'prompt' dialog.

mouseClick (Web)

Clicks the mouse on the specified widget.

nativeMouseClick (Web)

Simulates a native mouse click on a given widget/position.

openNewTab

Opens a new tab in the browser, loading a given URL.

raiseWindow

Tries to raise the browser window to the top of the stack.

rehook

Reconnects Squish to a web browser.

retrieveJSObject

Returns a JsObject which has the result of evaluating a JavaScript snippet.

scrollTo (Web)

Scrolls the browser so that a given widget is visible.

selectOption(s)(ByValue)

Selects options in form elements.

sendEvent (Web)

Sends an event to an object.

setFocus (Web)

Sets input focus on a particular element.

setFrameContext

Sets the current frame in a webpage with frames.

setText

Sets the text of an editable form element.

startBrowser

Starts the browser and loads a URL.

startDrag and dropOn

Functions to support separate drag and drop operations.

toggleExpandable

Clicks to toggle an expandable section header.

typeText

Types text into an editable form element.

uninstallEventHandler (Web)

Uninstalls an event handler.

waitForObjectItem (Web)

Waits for an item to be visible, enabled in a CalendarView or CustomItemView.

Web Object API Classes and Objects

Browser Object

Provides information about the currently-used browser.

BrowserTab Class

Provides operations on/information about a browser tab.

CssColor Type

Represents an RGB color + alpha value.

HTML_Anchor Class

HTML Anchor (hyperlink) element

HTML_Array Class

A JavaScript Array

HTML_Button Class

API for HTML Buttons and submit input elements.

HTML_ButtonBase Class

Base class for all HTML input button types.

HTML_CalendarEvent Class

API to support calendar events.

HTML_CalendarView Class

API to support web calendar widgets.

HTML_CheckBox Class

API for HTML CheckBox buttons.

HTML_ColorField Class

API for HTML color picker elements.

HTML_CustomButton Class

API for supporting highly customized HTML buttons.

HTML_CustomButtonBase Class

Abstract base class for highly-customized HTML buttons.

HTML_CustomCheckbox Class

API to support customized checkboxes.

HTML_CustomComboBox Class

API to support custom combo boxes.

HTML_CustomItem Class

Abstract API for accessing items in views.

HTML_CustomItemView Class

Abstract item view API.

HTML_CustomRadioButton Class

A customized radio button.

HTML_CustomSelectList Class

A customized multi-selection list.

HTML_CustomText Class

A customized text editor field.

HTML_DateChooser Class

An HTML date picker.

HTML_Document Class

Represents a web page's HTML document.

HTML_ExpandableSectionHeader Class

An HTML expandable section header element.

HTML_Form Class

API for HTML form elements.

HTML_FormElement Class

Base class for HTML form elements.

HTML_ImageButton Class

API for HTML image input elements.

HTML_Menu Class

API for HTML menus and menubars.

HTML_MenuButton Class

API for HTML menu buttons.

HTML_MenuItem Class

API for HTML menu items.

HTML_Object Class

Ultimate base class for HTML elements.

HTML_Option Class

API for HTML option elements.

HTML_ProgressBar Class

API for HTML progress bars.

HTML_RadioButton Class

API for HTML radio buttons input elements.

HTML_Select Class

API for HTML selection input elements.

HTML_Style Class

API for accessing an element's CSS.

HTML_Tab Class

API for HTML tab widget tabs.

HTML_TabWidget Class

API for HTML tab widgets.

HTML_Table Class

API for HTML tables.

HTML_Text Class

API for HTML text input elements.

HTML_TextArea Class

API for HTML textarea input elements

HTML_TextBase Class

Base class for HTML text input elements.

HTML_XPathResult Class

When an XPath expression is evaluated, this is returned.

JsObject Class

API for accessing references to JavaScript objects.

Web Object API Function Parameters

In all the functions listed here 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 HTML elements according to HTML standards. In addition to that, they may provide Synthetic Properties for convenience. Most Synthetic Properties in Squish for Web can not be used as part of realnames for looking up web objects, as Squish provides them through a mechanism that is not available directly for 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 Classes and Objects (Tree)

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

Deprecated Functions

contextList

Returns an HTML_Array of references to hooked browser windows.

contextOf

Returns the context string of a given window.

currentContext

Returns the currently active browser window.

hasContext

Returns true if an window with matching URL can be accessed by Squish.

loadUrl

Opens a web browser and loads a given URL.

setContext

Changes the active Window.

waitForContextExists

Waits for context to be loaded.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.

Search Results