QML Extension API

QML Extension API

Qt applications that utilize QtQuick can dynamically load QML code, including custom QML objects, so it is quite possible that AUTs that use QML will have QML objects that are unknown to Squish. This isn't a problem since Squish can still record and playback interactions with such objects, but will do so in terms of the primitives they are built from (e.g. Rectangle or Text items), rather than with the actual (logical) item types (e.g., CustomButton).

The QML Extension API makes it possible to make Squish treat certain custom QML object types as "black boxes" so that recording and playback can work at a higher level (i.e., in terms of the custom objects themselves rather than with the primitives that they are built from). Squish comes with a small example that makes use of some of the QML Extension APIs and that shows how to implement a SquishHook for a custom Calculator Button type: <SQUISHDIR>/examples/qt5/calqlatr/extension/Calqlatr.qml.

Squish also includes a more substantial QML Extension for support of QtQuick Controls, located in <SQUISHDIR>/lib/extensions/qt/qtquick/ControlsExt.qml.

The Format of a QML Extension

QML Extensions are standard QML scripts in .qml files (using the UTF-8 encoding), and using some additional functionality provided by Squish. For QtQuick 1.x the structure of a Squish QML extension looks like this:

import Qt 4.7
import com.froglogic.squish.qml 0.1

SquishHook {
    // extension code...
}

For QtQuick 2.x the basic structure of a QML extension is:

import QtQuick 2.0
import com.froglogic.squish.qtquick 0.1

SquishHook {
    // extension code...
}

Installing QML Extensions

Squish automatically looks in the <SQUISHDIR>/lib/extensions/qt/qml directory for extension files targeting QtQuick 1.x and into the <SQUISHDIR>/lib/extensions/qt/qtquick directory for QtQuick 2.x extension files. All that is needed to "install" a new QML extension is to move or copy it into one of these directories. It is also possible add an additional directory for Squish to search for QML extensions: Set the SQUISH_QML_EXTENSION_PATH environment variable (which you may need to create) to the directory where you want to keep your QtQuick 1.x QML extensions. For QtQuick 2.x rather set the SQUISH_QTQUICK_EXTENSION_PATH environment variable to the directory where you keep your QML extensions.

QML Extension API Documentation

Squish's QML Extension API consists of a single item of type SquishHook. This item provides various properties and functions which are listed below. A custom QML extension can make use of these properties and functions—and in some cases override them. In addition, Squish provides some helper functions to make writing QML extensions easier.

The QtQuick 1.x API uses the QML basic types and elements specified in the Qt 4.8 Reference Documentation.

The QtQuick 2.x API uses the QML basic types and items specified in the Qt 5.x Reference Documentation.

bool isCustomQmlType(item)

This function returns whether the given item of type Item is a custom type. (Every QML item that introduces new properties is considered to be a custom QML type by Qt—and by this function.)

bool isQmlType(item, className)

This function returns whether the given item of type Item inherits the class specified by the className string.

bool itemHasContents(item)

This function returns whether the given item of type Item has the QQuickItem::ItemHasContents flag set. This is a helper function to access this particular flag from within QML. It can serve as a hint whether an item should be ignored by default. See also Flag enum.

String qmlId(item)

This function returns the id for the given item or an empty string if item has no id set.

String qmlType(item)

This function returns the given item of type Item's class name if it is a declarative type; otherwise it returns an empty string.

String source(item)

This function returns the given item of type Item's URL if the item was loaded from a local file or remotely; otherwise it returns the item's containing component's URL (which might be an empty string).

SquishHook

The SquishHook class is an abstract class for extending in custom QML Extensions.

readonly property var SquishHook.blacklistedTypes

This variable can contain a list of strings, which are QML types you wish to have ignored by this extension.

readonly property var SquishHook.containerTypes

Some types can serve as containers for others. If you are interacting with a child of a container type, you should see a container= in the real name generated by Squish for that child, pointing to its container.

In this property, you can specify a list of strings, containing type names of classes which can be containers for all of their children.

This property is used in simple cases where a given class can always be a container type based on its class name.

If you need to look at properties to determine whether something is a container for a particular item, you should override the containerFor() function instead of using this property.

Item SquishHook.containerFor(item)

This function returns the container the given item of type Item is in (itself of type Item, e.g., a ListView or a GridView) which is normally also the item's parent; otherwise it returns null if the item isn't in a container.

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: An Item (possibly of your own custom type) which contains the given item. Or null, if you don't want the given item to have a container (in which case the view will be considered to be the item's container). Or, the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

StringList SquishHook.extraPropertiesFor(item)

This function returns a list of the property names for the given item of type Item that should be taken into account when generating a Squish object name for the item. (This function can be used to achieve the same kind of control over Squish's naming as editing the Qt wrapper descriptor file—for which see, Object Name Generation—but with finer control possible since property names can be considered on a per-item basis, not just on a per-type basis.)

You can implement your own version of this function in your QML extension, in which case for any given item you must return either: A list of property names (as an array of strings) whose values should be used to create the Squish object name for the given item. Or, the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

bool SquishHook.isIgnored(item)

This function returns false if the given item of type Item should be taken notice of by Squish — for example, visible and available for picking in the Spy and recorded.

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: The value false if you want Squish to take notice of the given item, or true if you want Squish to ignore the item, or the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

bool SquishHook.isItemReady(item)

This function returns true if the given item of type Item is ready to be interacted with, that is, is visible, enabled, and is in a stable state (e.g., it is not being or about to be animated).

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: The value true if the given item is ready for interaction, or false the item isn't ready, or the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

readonly property var SquishHook.objectNameProperties

This variable is expected to be a {dictionary} of key:value pairs, where the key is a "string", the QML type name, and the value is a [list] of "strings", property names of that type, that should be used to form the real name when it is added to the object map (at record time).

This QML-only functionality is similar to the qtwrapper_descriptors.xml which works on all Qt types.

int SquishHook.priority

This property holds a priority value for the QML extension and has a default value of 0. Squish accesses QML extensions in priority order from highest to lowest.

You can implement your own version of this property in your QML extension to give your extension a priority value higher than 0, e.g., to increase its priority.

String SquishHook.propertyFor(item, property)

This function returns a property value (as a string) for the given item of type Item's property (specified as a string).

You can implement your own version of this function in your QML extension, in which case for any given item and property you must return either: A string property value, or the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

Note that this function is not called when the object.property("propertyName") function is used inside a test script.

readonly property var SquishHook.whitelistedTypes

This variable can contain a list of strings, which are QML types you wish Squish to prefer (over its more primitive children), when it is picking objects.