Automating Qt Applications on Wayland-based Systems (Linux)

Last edited on


In general, automation on Wayland-based systems is supported in case of specific Wayland compositors. (See below for more information on supported compositors.)

Use of XWayland (X11 compatibility mode)

While some Linux distributions have moved to Wayland as default display server, most GUI software running on these distributions still uses X11 by default, via way XWayland (including, for example, Qt 5.12).

This makes Squish and the AUT (Application Under Test) appear to be running on X11. With this, most things work, but grabbing screenshots ( object.grabScreenshot() ) for some GUI control types does not.

Enforcing pure Wayland mode is possible through the use of environment variables. But this can cause problems, because currently Squish uses native X11 APIs in some places to make some of its AUT interactions possible.

Pure Wayland Mode

Without Squish's specific support for Wayland compositors (see below), the following restrictions exist for Squish on Linux systems without the XWayland compatibility layer (because of Wayland's design and intended lack of respective features:

Support for Wayland Compositor "Weston"

The Weston compositor is supported via an extension that is shipping with the Squish for Qt embedded source package:

Embedded Extension for Weston (Wayland Compositor)

Installing Squish Embedded Extension for Weston

Support for Wayland Compositor "Qt Application Manager" ("appman")

The Qt Application Manager can optionally act as a Wayland compositor. (This functionality is based on Qt Wayland Compositor . Also see Wayland and Qt .)

Squish for Qt supports Qt Wayland Compositor based compositors via an extension. To make this extension available, Squish's Qt support must be built from the Squish for Qt source package. (See section Support for Wayland Compositor "Qt Wayland Compositor" .)

QML Applications launched by appman's QML Launcher

(This chapter is not strictly about Wayland, but appman tends to be used with Wayland very often, so the topic fits into this context.)

The Squish for Qt source package contains an extension (in source code form) for appman to support QML based applications launched via appman's own QML launcher.

The Squish extension, for automatically making QML application launched by appman's QML launcher attachable , is contained in this file of the Squish source build for the target system/device:


For more information please see src/wrappers/qt/appman/README in the Squish for Qt source package.

Support for Wayland Compositor "Qt Wayland Compositor"

The Qt Wayland Compositor is supported by Squish. Squish for Qt binary packages include this extension. However, in the more typical use case for its use on embedded systems, it must be built as part of building Squish's Qt support from the Squish for Qt embedded source package for the target system.

Building support for Qt Wayland Compositor

The Qt Wayland Compositor support in the Squish for Qt source package (src/wrappers/qt/extensions/qtwaylandcompositor) is only built when its dependencies are met when configuring the Squish for Qt source build. (See Installing Squish for Qt from Embedded Source Packages and Installing Squish for Qt from Desktop Source Packages .)

Related output in Squish configure call (example):

Checking whether support for QtWaylandCompositor can be enabled ......... no, missing Qt modules: WaylandCompositor

After building the Squish Qt support for the target system, the Squish Qt Wayland Compositor extension must exist in the Squish build for the device. The resulting file is:


Using Squish's Qt Wayland Compositor support

Note that this is an extension of Squish's Qt support. As such, it only gets loaded when Squish connects to the application:

This is automatically the case when launching the application with the startApplication() function, and when attaching to the application with the attachToApplication() function.