macOS Convenience API

The Squish documentation uses the term widget when referring to GUI objects. macOS developers may be more familiar with the term view for this concept.

macOS Convenience Function Parameters

Some of the macOS convenience functions can take a modifierState argument which indicates which special keys are pressed at the time of a mouse click. And some of the functions can also take a button argument which indicates which mouse button was clicked.

The modifierState is an integer used as a bit-flag. Its value can be 0 (no modifiers) or one or more of: 1 (Shift), 2 (Control), 4 (Command), 8 (Option), with multiple modifiers or-ed together (e.g., 1|2 for Shift+Control).

The button is an integer: 0 signifies the "primary" mouse button (most commonly the left button), and 1 signifies the right button.

macOS Convenience Functions

Here are some quick links to the macOS Convenience API's functions:

activateItem(objectOrName)

This function activates the objectOrName menu item. This menu item must be a reference to (or a name that identifies) an NSMenuItem. The menu item can be part of the application menu or a menu item inside an NSPopUpButton.

macOS Universal Access

To replay menu activations on macOS as well as use the nativeType(keys) and nativeMouseClick(x, y, button) functions, you have to enable accessibility support in the System Preferences for certain processes. The system will open up a popup dialog when starting the squishide the first time that allows you to directly go the preferences dialog to enable accessibility support for the squishide.

To open the dialog, select System Preferences and choose Security & Privacy. Then choose the Privacy tab and select Accessibility on the left side.

To make changes, click the lock symbol in the lower left and enter the credentials of an administrative user. Then check the Squishide or Terminal app which needs permissions, from the list.

At any given time, there will be only one squishide instance that has access to the accessibility API and hence can run scripts that automate menus, use the nativeType(keys) or the nativeMouseClick(x, y, button) function. In order to use another squishide, for example from another Squish installation on the same system, you need to remove the existing entry completely from the list and then start the other instance of the squishide. Then enable accessibility support again when the dialog pops up.

Finally, it may sometimes happen that macOS always asks for enabling the accessibility support during the startup of the squishide. In such cases it helps to completely reset the database for Accessibility-enablement and clear out the whole list. This can be done using the tccutil from macOS:

tccutil reset Accessibility

After executing the command, restart the squishide to trigger the Accessibility-enablement popup again.

chooseFile([filePath, filePath, ...])

Automates operating the Cocoa file chooser dialog (NSOpenPanel) during test replay. It must be called immediately after the mouseClick that opens the file chooser. The list of strings given as a parameter will be fed to the AUT as the selected files. Use it to avoid error-prone automation of the NSOpenPanel through native input. The file dialog can be cancelled by passing an empty array to this function.

The test script is responsible for making sure that the given paths are plausible to the AUT, e.g. they could actually be selected in the file chooser.

If chooseFile is not invoked after an NSOpenPanel was triggered, the NSOpenPanel will open normally after a delay. The delay can be configured in SQUISH_DIR/etc/macwrapper.ini.

chooseFile(filePath)

A convenience overload for chooseFile that takes just one filePath string.

clearWebObjectCache()

This function clears the cache for hierarchical names for objects in a WebView. This can be useful in cases where a web application removes some elements of a web page after interacting with it and then the same hierarchical name used before should find a different object. Without clearing the cache in this situation the old object will be retrieved from the cache when searching for the hierarchical name after the website has changed its content. The cache however is necessary to keep lookup for hierarchical performant and scalable for deeper hierarchies.

—deprecated— clickButton(objectOrName)

This function is identical to mouseClick(objectOrName). It is included only for compatibility with old scripts. It should not be used in new scripts since it may eventually be removed from Squish.

—deprecated— clickTab(objectOrName)

This function is identical to mouseClick(objectOrName). It is included only for compatibility with old scripts. It should not be used in new scripts since it may eventually be removed from Squish.

doubleClick(objectOrName)

doubleClick(objectOrName, x, y)

doubleClick(objectOrName, x, y, modifierState, button)

This function double-clicks the mouse on the specified objectOrName widget.

By default the object is clicked in the middle, but this can be changed by passing object-relative coordinates, x and y. By default button 0 (the primary button) is used, but this can be changed by specifying the optional button argument. Similarly a default modifier state of 0 (no modifiers) is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified, and to specify the modifier, the position must be specified. See macOS Convenience Function Parameters for which values are valid for the modifierState and for the button arguments.

installEventHandler(eventName, handlerFunctionName)

This function installs a global event handler. The script function named in handlerFunctionName (which must be passed as a string, not as a function reference, except for Python, which supports passing a function reference, too), will be called when an event of the eventName type occurs.

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

• "Crash" – occurs if the AUT crashes
• "SheetOpened" – occurs when a macOS sheet is shown (note that this only applies to Cocoa applications)
• "WindowOpened" – occurs when a macOS toplevel window is shown (note that this only applies to Cocoa applications)
• "Timeout" – occurs when the Squish response timeout is reached

When the SheetOpened event occurs, the function named in handlerFunctionName is called. The function is passed one argument—the window object that opened the sheet. If you want to access the sheet itself, call the attachedSheet function on the NSWindow object.

When the WindowOpened event occurs, the function named in handlerFunctionName is called. The function is passed one argument—the window object that was opened. The event occurs only for toplevel windows (NSWindow and NSPanel objects), but it does not occur for windows that are shown as sheets. Use the SheetOpened event if you are interested in sheets.

For examples, see How to Use Event Handlers.

mouseClick(objectOrName)

mouseClick(objectOrName, x, y)

mouseClick(objectOrName, x, y, modifierState, button)

This function clicks the mouse on the specified objectOrName widget.

By default the object is clicked in the middle, but this can be changed by passing object-relative coordinates, x and y. By default button 0 (the primary button) is used, but this can be changed by specifying the optional button argument. Similarly a default modifier state of 0 (no modifiers) is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified, and to specify the modifier, the position must be specified. See macOS Convenience Function Parameters for which values are valid for the modifierState and for the button arguments.

mouseDrag(objectOrName, x, y, dx, dy)

mouseDrag(objectOrName, x, y, dx, dy, modifierState, button)

This function performs a mouse drag from the objectOrName widget to a position that is horizontally offset by dx pixels and vertically offset by dy pixels from position x, y in the objectOrName widget's coordinates.

By default button 0 (the primary button) is used, but this can be changed by specifying the optional button argument. Similarly a default modifier state of 0 (no modifiers) is used, but this can be changed by specifying the modifierState argument. Note that to specify the modifier, the button must also be specified, and to specify the modifier, the position must be specified. See macOS Convenience Function Parameters for which values are valid for the modifierState and for the button arguments.

scrollToObject(objectOrName)

This function ensures that the objectOrName widget is visible in the scroll widget that contains it, by scrolling if necessary.

If there are nested scroll widgets, the innermost one that contains the objectOrName widget is the one that will be scrolled.

Currently this function only works for NSView subclasses and for items in a NSTableView and NSOutlineView. If you need support for other classes, contact froglogic support.

type(objectOrName, text)

This function types the specified text (as if the user had used the keyboard) into the objectOrName editable widget. If the text is surrounded by angle brackets (<>), it is interpreted as a key combination, e.g "<Ctrl+Return>". The input is case-sensitive, so type(object, "R") is different from type(object, "r").

The following non-printable keys are supported in key combinations: <Ctrl>, <Command>, <Shift>, <Option>, <Up>, <Down>, <Left>, <Right>, <Del>, <Return>, <Tab>, <Backtab>, <Esc>, and <Backspace>.

uninstallEventHandler(eventName, handlerFunctionName)

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