GUITest(3pm)

📦

version 0.28 · 6 versions

💖 X11::GUITest — the manual, but make it cute 💖

okay bestie, listen up — this is the GUITest(3pm) page, aka X11::GUITest, a Perl thing that lets you poke at GUI apps like a little gremlin with a mouse and keyboard you don't actually have. It's living in the User Contributed Perl Documentation section. Buckle up, it's a long one. 🦋

✨ VERSION ✨

0.28 — that's the tea. 🫖

Updates are made available at the following sites:

Please consult docs/Changes for the list of changes between module revisions. (yes, the changelog is where the lore lives, go read it)

🌸 DESCRIPTION 🌸

So this Perl package is literally built to make testing GUI applications easier by emulating a whole user. You know, the fake little human clicking around.

It can be used to test / interact with GUI applications that have been built upon the X library, or toolkits (like GTK+, Xt, Qt, Motif, etc.) that "wrap" the X library's functionality. Toolkit-agnostic queen behavior. 👑

A basic recorder (x11guirecord) is also available, and can be found in the source code repository. It's giving "screen recording but for your clicks". 🎀

🧚 DEPENDENCIES 🧚

vibe check first, bestie, or nothing will work

You need an X server with the XTest extensions enabled. This seems to be the norm. 🙏 If it is not enabled, it usually can be by modifying the X server configuration (i.e., XF86Config).

The standard DISPLAY environment variable is utilized to determine the host, display, and screen to work with. By default it is usually set to :0.0 for the localhost. However, by altering this variable one can interact with applications under a remote host's X server. Remote chaos, but consensual.

To change this from a terminal window, one can utilize the following basic syntax:

export DISPLAY=<hostname-or-ipaddress>:<display>.<screen>

Please note that under most circumstances, xhost will need to be executed properly on the remote host as well. Don't skip this step, she will simply not let you in. 💀

There is a known incompatibility between the XTest and Xinerama extensions, which causes the XTestFakeMotionEvent() function to misbehave. 😭 When the Xinerama (X server) extension is turned on, this (Perl) extension has been modified to allow one to invoke an alternative function. See Makefile.PL for details.

🎀 INSTALLATION 🎀

perl Makefile.PL
make
make test
make install

# If the build has errors, you may need to install the following dependencies:
#    libxt-dev, libxtst-dev

# If you'd like to install the recorder, use these steps:
cd recorder
./autogen.sh
./configure
make
make install
x11guirecord --help

Copy. Paste. Slay. ✨ (And if it explodes, those two libxt packages are your besties.)

🌈 SYNOPSIS 🌈

For additional examples, please look under the eg/ sub-directory from the installation folder. there's lore in there, fr fr

use X11::GUITest qw/
  StartApp
  WaitWindowViewable
  SendKeys
/;

# Start gedit application
StartApp('gedit');

# Wait for application window to come up and become viewable.
my ($GEditWinId) = WaitWindowViewable('gedit');
if (!$GEditWinId) {
  die("Couldn't find gedit window in time!");
}

# Send text to it
SendKeys("Hello, how are you?\n");

# Close Application (Alt-f, q).
SendKeys('%(f)q');

# Handle gedit's Question window if it comes up when closing.  Wait
# at most 5 seconds for it.
if (WaitWindowViewable('Question', undef, 5)) {
  # DoN't Save (Alt-n)
  SendKeys('%(n)');
}

Look at her go. Opening gedit, typing, closing it, handling the little "do you want to save" popup like a pro. 👑

💅 FUNCTIONS 💅

housekeeping, real quick:

Parameters enclosed within [] are optional.

If there are multiple optional parameters available for a function and you would like to specify the last one, for example, you can utilize undef for those parameters you don't specify. (yes, undef is the "no thoughts head empty" placeholder, use it)

REGEX in the documentation below denotes an item that is treated as a regular expression. For example, the regex "^OK$" would look for an exact match for the word OK.

🌟 `FindWindowLike`

FindWindowLike TITLEREGEX [, WINDOWIDSTARTUNDER]

Finds the window Ids of the windows matching the specified title regex. 🔍 Optionally one can specify the window to start under; which would allow one to constrain the search to child windows of that window. Narrow the search, narrow the chaos.

An array of window Ids is returned for the matches found. An empty array is returned if no matches were found.

my @WindowIds = FindWindowLike('gedit');
# Only worry about first window found
my ($WindowId) = FindWindowLike('gedit');

🌟 `WaitWindowLike`

WaitWindowLike TITLEREGEX [, WINDOWIDSTARTUNDER] [, MAXWAITINSECONDS]

Waits for a window to come up that matches the specified title regex. ⏳ Optionally one can specify the window to start under; which would allow one to constrain the search to child windows of that window.

One can optionally specify an alternative wait amount in seconds. A window will keep being looked for that matches the specified title regex until this amount of time has been reached. The default amount is defined in the DEF_WAIT constant available through the :CONST export tag.

If a window is going to be manipulated by input, WaitWindowViewable is the more robust solution to utilize. (translation: use the viewable one if you're about to type at it, bestie)

An array of window Ids is returned for the matches found. An empty array is returned if no matches were found.

my @WindowIds = WaitWindowLike('gedit');
# Only worry about first window found
my ($WindowId) = WaitWindowLike('gedit');

WaitWindowLike('gedit') or die("gedit window not found!");

🌟 `WaitWindowViewable`

WaitWindowViewable TITLEREGEX [, WINDOWIDSTARTUNDER] [, MAXWAITINSECONDS]

Similar to WaitWindow, but only recognizes windows that are viewable. 👀 When GUI applications are started, their window isn't necessarily viewable yet, let alone available for input, so this function is very useful. It's the "wait until she's actually ready" function. Respect.

Likewise, this function will only return an array of the matching window Ids for those windows that are viewable. An empty array is returned if no matches were found.

🌟 `WaitWindowClose`

WaitWindowClose WINDOWID [, MAXWAITINSECONDS]

Waits for the specified window to close. 🚪💨

One can optionally specify an alternative wait amount in seconds. The window will keep being checked to see if it has closed until this amount of time has been reached. The default amount is defined in the DEF_WAIT constant available through the :CONST export tag.

zero is returned if window is not gone, non-zero if it is gone.

🌟 `WaitSeconds`

WaitSeconds SECONDS

Pauses execution for the specified amount of seconds. nap break 😴

WaitSeconds(0.5); # Wait 1/2 second
WaitSeconds(3); # Wait 3 seconds

🌟 `ClickWindow`

ClickWindow WINDOWID [, X Offset] [, Y Offset] [, Button]

Clicks on the specified window with the mouse. 🖱️

Optionally one can specify the X offset and Y offset. By default, the top left corner of the window is clicked on; with these two parameters one can specify a different position to be clicked on. aim your click, don't just spam it

One can also specify an alternative button. The default button is M_LEFT, but M_MIDDLE and M_RIGHT may be specified too. Also, you could use the logical Id for the button: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. These are all available through the :CONST export tag.

zero is returned on failure, non-zero for success.

🌟 `GetWindowsFromPid`

Returns a list of window ids discovered for the specified process id (pid). 🫶

undef is returned on error.

🌟 `GetWindowFromPoint`

GetWindowFromPoint X, Y [, SCREEN]

Returns the window that is at the specified point. 📍 If no screen is given, it is taken from the value given when opening the X display.

zero is returned if there are no matches (i.e., off screen). girl is not there, nothing to find

🌟 `IsChild`

IsChild PARENTWINDOWID, WINDOWID

Determines if the specified window is a child of the specified parent. 👶

zero is returned for false, non-zero for true.

🌟 `QuoteStringForSendKeys`

QuoteStringForSendKeys STRING

Quotes {} characters in the specified string that would be interpreted as having special meaning if sent to SendKeys directly. It's the escape-the-scary-characters function. This function would be useful if you had a text file in which you wanted to use each line of the file as input to the SendKeys function, but didn't want any special interpretation of the characters in the file. 📄✨

Returns the quoted string, undef is returned on error.

# Quote  ~, %, etc.  as  {~}, {%}, etc for literal use in SendKeys.
SendKeys( QuoteStringForSendKeys('Hello: ~%^(){}+#') );
SendKeys( QSfSK('#+#') );

The international AltGr key - modifier character (&) is not escaped by this function. Escape this character manually ("{&}"), if used/needed. She's not doing it for you. Do it yourself. 💀

🌟 `StartApp`

StartApp COMMANDLINE

Uses the shell to execute a program. This function returns as soon as the program is called. 🏃♀️💨 Useful for starting GUI applications and then going on to work with them. fire it off and keep moving, periodt

zero is returned on failure, non-zero for success.

StartApp('gedit');

🌟 `RunApp`

RunApp COMMANDLINE

Uses the shell to execute a program until its completion. ⏱️

Return value will be application specific, however -1 is returned to indicate a failure in starting the program.

RunApp('/work/myapp');

🌟 `ClickMouseButton`

ClickMouseButton BUTTON

Clicks the specified mouse button. Available mouse buttons are: M_LEFT, M_MIDDLE, M_RIGHT, M_DOWN, M_UP. 🖱️ Also, you could use the logical Id for the button: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. These are all available through the :CONST export tag.

zero is returned on failure, non-zero for success.

🌟 `DefaultScreen`

Returns the screen number specified in the X display value used to open the display. 🖥️

Leverages the Xlib macro of the same name.

🌟 `ScreenCount`

Returns the number of screens in the X display specified when opening it. 🔢

Leverages the Xlib macro of the same name.

🌟 `SetEventSendDelay`

SetEventSendDelay DELAYINMILLISECONDS

Sets the milliseconds of delay between events being sent to the X display. ⏲️ It is usually not a good idea to set this to 0. (read that again, bestie — zero is not the vibe)

Please note that this delay will also affect SendKeys.

Returns the old delay amount in milliseconds. 🎁

🌟 `GetEventSendDelay`

Returns the current event sending delay amount in milliseconds. ⏲️

🌟 `SetKeySendDelay`

SetKeySendDelay DELAYINMILLISECONDS

Sets the milliseconds of delay between keystrokes. ⌨️

Returns the old delay amount in milliseconds. 🎁

🌟 `GetKeySendDelay`

Returns the current keystroke sending delay amount in milliseconds. ⌨️

🌟 `GetWindowName`

GetWindowName WINDOWID

Returns the window name for the specified window Id. 🏷️ undef is returned if name could not be obtained.

# Return the name of the window that has the input focus.
my $WinName = GetWindowName(GetInputFocus());

okay that's part one, bestie — there is so much more coming, do not go anywhere 🌸🦋💖

`GetWindowPid` WINDOWID

Hands you back the process id (pid) of the window you point at. And if that pid just isn't a thing that exists? You get 0. That's it, that's the whole vibe. 💅

# Return the pid of the window that has the input focus.
my $pid = GetWindowPid(GetInputFocus());

`SetWindowName` WINDOWID, NAME

Renames a window, bestie. You say which window Id, you say the new name, done.

Returns zero if it flops, non-zero if it slays. ✨

`GetRootWindow` [SCREEN]

Gives you the Id of the root window of the screen — that's the top / root level window that every single other window is chillin' under. the literal main character of the hierarchy 👑

No screen passed in? No worries, it just uses whatever value you gave when you opened the X display.

`GetChildWindows` WINDOWID

Returns an array of the child windows belonging to the window Id you gave it.

Heads up: if it catches the window hierarchy mid-transition (chaotic era 😭), it'll wait half a second and then try the whole thing again. Patience is a virtue, fr fr.

`MoveMouseAbs` X, Y [, SCREEN]

Physically relocates the mouse cursor to that exact absolute position, on the optionally-given screen. If you don't give it a screen, it takes the value from when you opened the X display. Defaults, we love her. 🦋

Zero on failure, non-zero for success.

`GetMousePos`

Returns an array holding the position and the screen (number) of your mouse cursor. Two-for-one, obsessed. 🎀

my ($x, $y, $scr_num) = GetMousePos();

`PressMouseButton` BUTTON

Presses down the mouse button you name. The available buttons are: M_LEFT, M_MIDDLE, M_RIGHT, M_DOWN, M_UP. And you can also use the logical Id instead: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. All of these are available through the :CONST export tag. 🫶

zero is returned on failure, non-zero for success.

`ReleaseMouseButton` BUTTON

Lets go of the mouse button you name — the press's other half. Available buttons: M_LEFT, M_MIDDLE, M_RIGHT, M_DOWN, M_UP. Logical Id option too: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. All available through the :CONST export tag. 💅

zero on failure, non-zero for success.

`SendKeys` KEYS

Sends keystrokes to whichever window currently holds the input focus. Like typing, but you're doing it from orbit. 🚀

The keystrokes you send are whatever you put in the KEYS parameter, but bestie — some characters are special. Here they are:

Modifier Keys:

^ — CTRL
% — ALT
+ — SHIFT
# — META
& — ALTGR

Other Keys:

~ — ENTER
\n — ENTER
\t — TAB
( and ) — MODIFIER GROUPING
{ and } — QUOTE / ESCAPE CHARACTERS

The simplest serve is just sending a whole text string, like so:

SendKeys('Hello, how are you today?');

A parenthesis lets a modifier do its thing on one or more characters. Watch:

SendKeys('%(f)q'); # Alt-f, then press q
SendKeys('%(fa)^(m)'); # Alt-f, Alt-a, Ctrl-m
SendKeys('+(abc)'); # Uppercase ABC using shift modifier
SendKeys('^(+(l))'); # Ctrl-Shift-l
SendKeys('+'); # Press shift

Braces are for quoting special characters, for using aliased key names, or for special functionality. You can put multiple characters inside one brace set by space delimiting the entries. And characters can be repeated by sticking a number after the preceding key, space delimited. Repeat queen 👑

Quote Special Characters

SendKeys('{{}'); # {
SendKeys('{+}'); # +
SendKeys('{#}'); # #

You can also use QuoteStringForSendKeys (QSfSK) to perform the quoting for you. Very delegation-core of you ✨

Aliased Key Names

SendKeys('{BAC}'); # Backspace
SendKeys('{F1 F2 F3}'); # F1, F2, F3
SendKeys('{TAB 3}'); # Press TAB 3 times
SendKeys('{SPC 3 a b c}'); # Space 3 times, a, b, c

Special Functionality

# Pause execution for 500 milliseconds
SendKeys('{PAUSE 500}');

Combinations

SendKeys('abc+(abc){TAB PAUSE 500}'); # a, b, c, A, B, C, Tab, Pause 500
SendKeys('+({a b c})'); # A, B, C

Now, the abbreviated key names that are currently recognized inside a brace set are listed below. If your key isn't in there, no stress — you can still use the unabbreviated name for it. Not sure what that name is? Grab the xev (X event view) tool, press the key you want, and peek at the tool's output for the name of that key. 🕵️‍♀️

The names in the list below can be used regardless of case. Names that aren't in this list are case sensitive and not abbreviated. For example, with xev you'll find that the backspace key's name is BackSpace, so you could totally use {BackSpace} in place of {bac} if you really wanted to. You do you.

BAC — BackSpace
BS — BackSpace
BKS — BackSpace
BRE — Break
CAN — Cancel
CAP — Caps_Lock
DEL — Delete
DOWN — Down
END — End
ENT — Return
ESC — Escape
F1 — F1
... — ...
F12 — F12
HEL — Help
HOM — Home
INS — Insert
LAL — Alt_L
LMA — Meta_L
LCT — Control_L
LEF — Left
LSH — Shift_L
LSK — Super_L
MNU — Menu
NUM — Num_Lock
PGD — Page_Down
PGU — Page_Up
PRT — Print
RAL — Alt_R
RMA — Meta_R
RCT — Control_R
RIG — Right
RSH — Shift_R
RSK — Super_R
SCR — Scroll_Lock
SPA — Space
SPC — Space
TAB — Tab
UP — Up

zero is returned on failure, non-zero for success. And one lil note for the setups out there (Xvfb) that don't support Alt_Left: Meta_Left gets automatically used in its place. It's giving adaptive 💀✨

`PressKey` KEY

Presses the key you name. Held down. Like a keyboard girlie who committed.

You can absolutely use the abbreviated key names from that big table above, exactly like this:

# Alt-n
PressKey('LAL'); # Left Alt
PressKey('n');
ReleaseKey('n');
ReleaseKey('LAL');

# Uppercase a
PressKey('LSH'); # Left Shift
PressKey('a');
ReleaseKey('a');
ReleaseKey('LSH');

Those ReleaseKey calls in the example are there to set both key states back, btw — otherwise you leave the keyboard in a weird lil situation 😭

zero on failure, non-zero for success.

`ReleaseKey` KEY

Releases the key you name. Normally it follows a PressKey call, because that's the natural order of things 🌸

You can use the abbreviated key names from the table listed above.

ReleaseKey('n');

zero on failure, non-zero for success.

`PressReleaseKey` KEY

Presses the specified key and releases it. The whole saga, start to finish, one call. Iconic efficiency. 💅

You can use the abbreviated key names from the table listed above.

PressReleaseKey('n');

This function is affected by the key send delay.

zero on failure, non-zero for success.

`IsKeyPressed` KEY

Checks whether the key you name is currently being pressed right this second. Vibe check, but for keys 👀

You can specify stuff like 'bac' or the unabbreviated form 'BackSpace', just like we covered in the SendKeys info. Brace forms like '{bac}' are unsupported. A '{' gets taken literally, and letters are case sensitive.

if (IsKeyPressed('esc')) {  # Is Escape pressed?
if (IsKeyPressed('a')) { # Is a pressed?
if (IsKeyPressed('A')) { # Is A pressed?

Returns non-zero for true, zero for false.

`IsMouseButtonPressed` BUTTON

Checks whether the mouse button you named is currently being pressed. Peak "is it down or not" energy 🖱️

Available mouse buttons are: M_LEFT, M_MIDDLE, M_RIGHT. Also, you could use the logical Id for the button: M_BTN1, M_BTN2, M_BTN3, M_BTN4, M_BTN5. These are all available through the :CONST export tag.

if (IsMouseButtonPressed(M_LEFT)) { # Is left button pressed?

Returns non-zero for true, zero for false.

`IsWindow` WINDOWID

zero is returned if the window Id you gave isn't for something recognizable as a window. non-zero comes back if it looks like a window. It's a sniff test, bestie 🐾

`IsWindowViewable` WINDOWID

zero is returned if the specified window Id belongs to a window that isn't viewable. non-zero is returned if the window is viewable. Simple as that ✨

`IsWindowCursor` WINDOWID CURSOR

Figures out whether the specified window has the specified cursor.

zero is returned for false, non-zero for true.

The following cursors are available through the :CONST export tag.

✨ Name ✨

Bestie, here's the entire cursor-constant lineup — every single XC_* glyph name, exactly as listed. No skips, no cuts, all 78 of them. 💅

XC_NUM_GLYPHS
XC_X_CURSOR
XC_ARROW
XC_BASED_ARROW_DOWN
XC_BASED_ARROW_UP
XC_BOAT
XC_BOGOSITY
XC_BOTTOM_LEFT_CORNER
XC_BOTTOM_RIGHT_CORNER
XC_BOTTOM_SIDE
XC_BOTTOM_TEE
XC_BOX_SPIRAL
XC_CENTER_PTR
XC_CIRCLE
XC_CLOCK
XC_COFFEE_MUG
XC_CROSS
XC_CROSS_REVERSE
XC_CROSSHAIR
XC_DIAMOND_CROSS
XC_DOT
XC_DOTBOX
XC_DOUBLE_ARROW
XC_DRAFT_LARGE
XC_DRAFT_SMALL
XC_DRAPED_BOX
XC_EXCHANGE
XC_FLEUR
XC_GOBBLER
XC_GUMBY
XC_HAND1
XC_HAND2
XC_HEART
XC_ICON
XC_IRON_CROSS
XC_LEFT_PTR
XC_LEFT_SIDE
XC_LEFT_TEE
XC_LEFTBUTTON
XC_LL_ANGLE
XC_LR_ANGLE
XC_MAN
XC_MIDDLEBUTTON
XC_MOUSE
XC_PENCIL
XC_PIRATE
XC_PLUS
XC_QUESTION_ARROW
XC_RIGHT_PTR
XC_RIGHT_SIDE
XC_RIGHT_TEE
XC_RIGHTBUTTON
XC_RTL_LOGO
XC_SAILBOAT
XC_SB_DOWN_ARROW
XC_SB_H_DOUBLE_ARROW
XC_SB_LEFT_ARROW
XC_SB_RIGHT_ARROW
XC_SB_UP_ARROW
XC_SB_V_DOUBLE_ARROW
XC_SHUTTLE
XC_SIZING
XC_SPIDER
XC_SPRAYCAN
XC_STAR
XC_TARGET
XC_TCROSS
XC_TOP_LEFT_ARROW
XC_TOP_LEFT_CORNER
XC_TOP_RIGHT_CORNER
XC_TOP_SIDE
XC_TOP_TEE
XC_TREK
XC_UL_ANGLE
XC_UMBRELLA
XC_UR_ANGLE
XC_WATCH
XC_XTERM

That's the whole set. Iconic. 🎀

`MoveWindow WINDOWID, X, Y`

Moves the window to the specified location. ✨

Returns zero on failure, non-zero for success. So if you get a zero, it's not a slay moment, bestie. 😭