class: gtktest

[67:14] static extends: object

Provides GTK4 UI testing helpers for Aussom applications. The gtktest module is the GTK counterpart to testfx. It targets one GtkApplication or GtkWindow, walks the widget tree for selector-based lookup, performs semantic user actions such as click, focus, and text entry, pumps the GLib main loop, and exposes assertion helpers for common UI state. The public API is intentionally small and test-oriented:

• setup and cleanup for choosing the target window or application
• lookup helpers by id, css class, text, role, or type name
• semantic click, focus, write, erase, and key-combo helpers
• pump and wait helpers for GTK draw and event-loop synchronization
• verify helpers for visibility, enabled state, text, focus, and a11y role
• widget and window screenshot capture

Members

• targetApp
• targetWindow
• robotEnabled
• gtkApi
• glibApi
• recording
• recordingDir
• recordingFps
• recordingFrame
• recordingNextAt
• capturingFrame
• robotChecked
• robotCache
• widgetComputePointFn

Methods

• getGtkApi ()

  Returns the generated GtkApi helper.

  • @r A GtkApi object.

• getGLibApi ()

  Returns the generated GLibApi helper.

  • @r A GLibApi object.

• nowMillis ()

  Returns the current system time in milliseconds.

  • @r An int with epoch milliseconds.

• setup (object AppObj)

  Targets one GTK application or window for all subsequent test actions. When passed a GtkApplication, setup waits briefly for the active window to become available and then uses it as the default lookup root.

  • @p AppObj is a GtkApplication, GtkWindow, GtkDialog, or GtkApplicationWindow.
  • @r None.

• cleanup ()

  Clears the current target application/window and recording state.

  • @r None.

• releaseRobotKeys ()

  Releases any robot-held keys or buttons. Called from cleanup so a stray modifier from a failed test does not leak to the next test.

  • @r None.

• useRobot (bool Enabled)

  Toggles the optional robot mode flag. The current implementation keeps semantic actions as the default path, even when robot mode is enabled.

  • @p Enabled is true to request robot mode.
  • @r None.

• robotAvailable ()

  Returns true when native robot input is available on the current backend. The probe caches its result. The v1 robot backend supports Linux with an X11 or XWayland display. Wayland-only and macOS / Windows backends report false so robot-only tests can gate cleanly.

  • @r A bool.

• probeRobot ()

  Probes the environment to detect whether robot input is usable.

  • @r A map describing the probe result.

• x11KeycodeFromName (string Name)

  Returns the X11 keycode for a keysym name such as "Return" or "a".

  • @p Name is the X11 keysym name.
  • @r A keycode, or 0 when the lookup fails.

• lookup (string Query)

  Returns the first widget matching the selector query, or null.

  • @p Query is a selector string using id, class, text, role, or type prefixes.
  • @r A generated GTK wrapper object or null.

• lookupAll (string Query)

  Returns all widgets matching the selector query.

  • @p Query is a selector string using id, class, text, role, or type prefixes.
  • @r A list of generated GTK wrapper objects.

• exists (string Query)

  Returns true when at least one widget matches the selector query.

  • @p Query is a selector string using id, class, text, role, or type prefixes.
  • @r A bool.

• clickOn (string Query)

  Clicks the matched widget using the semantic GTK path. For GtkButton the runtime emits the "clicked" signal through glib.signalEmitByName so any Aussom-side click handler fires exactly as it would for a real user click. Other widget types route through gtk_widget_activate, which covers GtkEntry activate-on-enter, GtkCheckButton toggle, and most action widgets.

  • @p Query is the selector string for the target widget.
  • @r None.

• doubleClickOn (string Query)

  Clicks the matched widget twice with a short pump between activations.

  • @p Query is the selector string for the target widget.
  • @r None.

• rightClickOn (string Query)

  Performs a secondary-button action on the matched widget. When robot mode is active this injects a real right-click through AWT Robot. Otherwise the semantic path looks for a GtkGestureClick controller on the widget with button 3 or 0 and emits its pressed and released signals. When no secondary gesture is attached and robot mode is unavailable the call throws.

  • @p Query is the selector string for the target widget.
  • @r None.

• moveTo (string Query)

  Moves the mouse cursor to the matched widget. In robot mode this injects a real AWT Robot mouse move. In semantic mode this is a no-op since GTK does not deliver synthetic motion without a real pointer.

  • @p Query is the selector string for the target widget.
  • @r None.

• focus (string Query)

  Grabs focus on the matched widget.

  • @p Query is the selector string for the target widget.
  • @r None.

• write (string Text)

  Writes text into the currently focused editable widget.

  • @p Text is the text to append.
  • @r None.

• push (string KeyCombo)

  Simulates one key combo on the focused widget. The v1 semantic implementation maps common test shortcuts directly to GTK editable operations and widget activation. Supported combos are: ENTER, RETURN, ESCAPE, TAB, BACK_SPACE, DELETE, HOME, END, CONTROL+A, CONTROL+HOME, CONTROL+END. Unknown combos are no-ops.

  • @p KeyCombo is the combo string.
  • @r None.

• requireEditableFocus (string MethodName)

  Returns a fresh Editable wrapper for the focused widget or throws when nothing editable has focus.

  • @p MethodName is used for error messages.
  • @r An Editable wrapper.

• eraseText (int Count)

  Removes characters from the end of the focused editable widget.

  • @p Count is the number of characters to remove.
  • @r None.

• pump ()

  Drains pending events from the default GLib main context.

  • @r None.

• pumpUntil (callback Predicate, int TimeoutMs = 5000)

  Pumps the event loop until the predicate returns true or the timeout elapses.

  • @p Predicate is the callback checked after each pump cycle.
  • @p TimeoutMs is the maximum wait in milliseconds.
  • @r None.

• sleep (int Millis)

  Waits for the provided duration while continuing to pump the GTK loop.

  • @p Millis is the duration in milliseconds.
  • @r None.

• robotModeActive ()

  Returns true when robot mode is currently active for an action. Robot mode is active when the caller has requested it through useRobot(true) and the current backend supports AWT Robot input.

  • @r A bool.

• widgetScreenCenter (object WidgetObj)

  Computes the screen coordinates of the center of a widget. The math sums three parts: the widget center in widget coordinates, the widget origin relative to the native window obtained through gtk_widget_compute_point, and the native-window origin on screen obtained through XTranslateCoordinates. The native offset is scaled by the surface scale factor before the screen origin is added.

  • @p WidgetObj is the widget to locate.
  • @r A map with x and y integer pixel coordinates.

• widgetToNativePoint (object Widget, object Target, double Cx, double Cy)

  Wraps gtk_widget_compute_point to translate a widget-local point into coordinates relative to a target widget.

  • @p Widget is the source widget.
  • @p Target is the reference widget.
  • @p Cx is the widget-local x coordinate.
  • @p Cy is the widget-local y coordinate.
  • @r A map with x and y doubles in target coordinates.

• surfaceScreenPosition (object Surface)

  Returns the screen origin of a GdkSurface. The v1 implementation uses X11 via gdk_x11_surface_get_xid and XTranslateCoordinates. Non-X11 backends throw because robotAvailable would have returned false for them already.

  • @p Surface is a GdkSurface wrapper.
  • @r A map with x and y integer pixel coordinates.

• roundInt (double Value)

  Rounds a double to a signed int using java.lang.Math.round.

  • @p Value is the value to round.
  • @r An int.

• robotClick (object WidgetObj, int Button)

  Injects a mouse click through the X11 XTest extension at the widget's screen center.

  • @p WidgetObj is the target widget.
  • @p Button is the X11 button number (1=left, 2=middle, 3=right).
  • @r None.

• robotMove (object WidgetObj)

  Moves the robot cursor to the widget's screen center without pressing.

  • @p WidgetObj is the target widget.
  • @r None.

• robotPushCombo (string KeyCombo)

  Injects a key combo through the X11 XTest extension. Returns true when the combo is recognized and delivered.

  • @p KeyCombo is the combo string, upper-cased.
  • @r A bool.

• x11KeyCodeForCombo (string Name)

  Maps a combo key name to an X11 keycode via keysym lookup.

  • @p Name is the upper-cased key name.
  • @r A keycode, or 0 when the name is unknown.

• x11ModifierKeyCode (string Name)

  Maps a modifier name to an X11 keycode.

  • @p Name is the upper-cased modifier name.
  • @r A keycode, or 0 when the name is unknown.

• findGestureClick (object WidgetObj, int Button)

  Walks a widget's event controllers to find a GtkGestureClick whose button matches the target. Returns null when no matching gesture exists.

  • @p WidgetObj is the widget to inspect.
  • @p Button is the button number (1=primary, 2=middle, 3=secondary, 0 matches any).
  • @r A GtkGestureClick wrapper or null.

• emitGestureClick (object WidgetObj, object Gesture)

  Emits pressed and released signals on a GtkGestureClick at the widget's local center.

  • @p WidgetObj is the widget owning the gesture.
  • @p Gesture is the GtkGestureClick wrapper to drive.
  • @r None.

• waitForDraw (object WidgetObj, int TimeoutMs = 2000)

  Waits for the widget to complete a draw cycle. The v1 implementation used gtk_test_widget_wait_for_draw, which blocks inside the GLib main loop until the widget's frame clock dispatches a draw. On Wayland and some XWayland compositor states that never happens for windows without focus, so the call hangs forever. This replacement iterates the main context with a bounded wall-clock deadline, exits as soon as the widget reports mapped with a non-zero allocation, and returns quietly when the deadline elapses. Callers that need a drawn widget (for example capture()) still check get_allocated_width/height themselves and fail with a clear error, so a timeout does not silently produce a broken screenshot.

  • @p WidgetObj is the target widget.
  • @p TimeoutMs is the maximum wall-clock wait in milliseconds.
  • @r None.

• verifyExists (string Query)

  Asserts that at least one widget matches the selector.

  • @p Query is the selector string.
  • @r None.

• verifyNotExists (string Query)

  Asserts that no widgets match the selector.

  • @p Query is the selector string.
  • @r None.

• verifyVisible (string Query)

  Asserts that the matched widget is visible and mapped.

  • @p Query is the selector string.
  • @r None.

• verifyInvisible (string Query)

  Asserts that the matched widget is not visible.

  • @p Query is the selector string.
  • @r None.

• verifyEnabled (string Query)

  Asserts that the matched widget is enabled.

  • @p Query is the selector string.
  • @r None.

• verifyDisabled (string Query)

  Asserts that the matched widget is disabled.

  • @p Query is the selector string.
  • @r None.

• verifyHasText (string Query, string Text)

  Asserts that the matched widget text equals the expected value.

  • @p Query is the selector string.
  • @p Text is the expected text.
  • @r None.

• verifyFocused (string Query)

  Asserts that the matched widget currently has focus.

  • @p Query is the selector string.
  • @r None.

• verifyAccessibleRole (string Query, Role)

  Asserts that the matched widget reports the requested accessible role.

  • @p Query is the selector string.
  • @p Role is the expected AccessibleRole enum value (a string like "button" or the equivalent AccessibleRole.button reference).
  • @r None.

• verifyAccessibleProperty (string Query, Prop)

  Asserts that the matched widget reports the requested accessible property.

  • @p Query is the selector string.
  • @p Prop is the expected AccessibleProperty enum value (a string like "label" or the equivalent AccessibleProperty.label reference).
  • @r None.

• capture (object WidgetObj, string Path)

  Captures a PNG of the provided widget. The capture path wraps the widget in a GtkWidgetPaintable, snapshots it at the widget's current allocated size, converts the resulting GskRenderNode to a GdkTexture through the widget's native renderer, and writes the texture as a PNG. GtkWidgetPaintable caches whatever the widget painted during its last frame-clock cycle. In test scenarios the compositor can take several frame intervals to deliver the first frame event, so the snapshot attempt is wrapped in a bounded retry loop that pumps the main loop between attempts until a populated render tree appears or a wall-clock deadline elapses.

  • @p WidgetObj is the widget to capture.
  • @p Path is the output PNG path.
  • @r The output path.

• captureWindow (object WindowObj, string Path)

  Captures a PNG of the provided window.

  • @p WindowObj is the window or dialog to capture.
  • @p Path is the output PNG path.
  • @r The output path.

• captureScreen (string Path)

  Captures the current target screen state. The v1 implementation captures the active target window, which covers the common single-window test case.

  • @p Path is the output PNG path.
  • @r The output path.

• startRecording (string Dir, int Fps = 30)

  Starts recording frame snapshots into the provided directory. Frames are captured opportunistically during pump, sleep, and action calls, which keeps the implementation thread-safe and toolkit-aligned.

  • @p Dir is the output directory.
  • @p Fps is the requested frame rate.
  • @r None.

• stopRecording ()

  Stops recording and optionally stitches the captured frames with ffmpeg.

  • @r The mp4 path when ffmpeg succeeds, otherwise the frame directory path.

• captureRecordingFrameIfDue ()

  Captures one recording frame when the next frame deadline has been reached.

  • @r None.

• padFrame (int Number)

  Returns one zero-padded frame number for recording output.

  • @p Number is the frame index.
  • @r A string like 00001.

• targetAppHasWindow ()

  Returns true when the targeted application has an active window.

  • @r A bool.

• ensureSetup (string MethodName)

  Throws when the module has not been set up yet.

  • @p MethodName is the calling public method.
  • @r None.

• requireWidget (string Query, string MethodName)

  Returns the first matching widget, throwing a clear error when none exists.

  • @p Query is the selector string.
  • @p MethodName is the calling public method.
  • @r A Gtk.Widget wrapper.

• lookupWidget (string Query)

  Returns the first raw Gtk.Widget match for the query.

  • @p Query is the selector string.
  • @r A Gtk.Widget wrapper or null.

• lookupWidgetAll (string Query)

  Returns all raw Gtk.Widget matches for the query.

  • @p Query is the selector string.
  • @r A list of Gtk.Widget wrappers.

• walk (object RootWidget)

  Walks one widget subtree depth-first.

  • @p RootWidget is the subtree root.
  • @r A list of Gtk.Widget wrappers.

• walkInto (object WidgetObj, list Out)

  Recursively appends one widget subtree into the provided output list.

  • @p WidgetObj is the subtree root.
  • @p Out is the result list.
  • @r None.

• matchesToken (object WidgetObj, string Token)

  Returns true when the widget matches the selector token.

  • @p WidgetObj is the widget to inspect.
  • @p Token is the selector token.
  • @r A bool.

• typeName (object Obj)

  Returns the current native GObject type name for the wrapper.

  • @p Obj is a GTK wrapper object.
  • @r A string like GtkButton.

• isEditableType (string TypeName)

  Returns true when the native widget type is editable.

  • @p TypeName is the native GType name.
  • @r A bool.

• getWidgetText (object WidgetObj)

  Returns the user-facing text for a widget when a meaningful text accessor exists.

  • @p WidgetObj is the widget to inspect.
  • @r A string or null.

• focusWidget (object WidgetObj)

  Focuses one widget and throws clearly when the request fails.

  • @p WidgetObj is the widget to focus.
  • @r None.

• getFocusedWindowWidget ()

  Returns the widget GTK currently considers focused for the target window.

  • @r A Gtk.Widget wrapper or null.

• sameWidget (object Left, object Right)

  Returns true when both wrapper objects refer to the same GTK widget.

  • @p Left is the first widget.
  • @p Right is the second widget.
  • @r A bool.

• findFocusedWidget ()

  Returns the currently focused widget in the target subtree.

  • @r A Gtk.Widget wrapper or null.

• wrapWidget (object WidgetObj)

  Wraps one raw widget handle in the most specific common generated wrapper used by the v1 tests.

  • @p WidgetObj is the widget to wrap.
  • @r A generated GTK wrapper object.

• stripPrefix (string Text)

  Removes the first selector prefix character.

  • @p Text is the selector token.
  • @r A string without the first character.

• stripQuotes (string Text)

  Removes the leading and trailing double quote from a text selector.

  • @p Text is the quoted selector token.
  • @r An unquoted string.