X11::GUITest - Provides GUI testing/interaction facilities.
Developed by Dennis K. Paulsen
0.17
Please consult 'docs/Changes' for the list of changes between module revisions.
This Perl package is intended to facilitate the testing of GUI applications by means of user emulation. It can be used to test/interact with GUI applications; which have been built upon the X library or toolkits (i.e., GTK+, Xt, Qt, Motif, etc.) that ``wrap'' the X library's functionality.
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).
Also, 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. 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.
perl Makefile.PL make make test make install
For additional examples, please look under the 'eg/' sub-directory.
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)');
}
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.
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.
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');
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.
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!");
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.
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.
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.
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
zero is returned for false, non-zero for true.
Returns the quoted string, undef is returned on error.
# Quote ~, %, etc. as {~}, {%}, etc for literal use in SendKeys.
SendKeys( QuoteStringForSendKeys('Hello: ~%^(){}+') );
zero is returned on failure, non-zero for success
StartApp('gedit');
Return value will be application specific, however -1 is returned to indicate a failure in starting the program.
RunApp('/work/myapp');
zero is returned on failure, non-zero for success.
Please note that this delay will also affect SendKeys.
Returns the old delay amount in milliseconds.
Returns the old delay amount in milliseconds.
# Return the name of the window that has the input focus. my $WinName = GetWindowName(GetInputFocus());
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
my ($x, $y) = GetMousePos();
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
The keystrokes to send are those specified in KEYS. Some characters have special meaning, they are:
Modifier Keys:
^ CTRL
% ALT
+ SHIFT
Other Keys:
~ ENTER
\n ENTER
\t TAB
( and ) MODIFIER USAGE
{ and } QUOTE CHARACTERS
Simply, one can send a text string like so:
SendKeys('Hello, how are you today?');
Parenthesis allow a modifier to work on one or more characters. For example:
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 used to quote special characters, for utilizing aliased key names, or for special functionality. Multiple characters can be specified in a brace by space delimiting the entries. Characters can be repeated using a number that is space delimited after the preceeding key.
Quote Special Characters
SendKeys('{{}'); # {
SendKeys('{+}'); # +
You can also use QuoteStringForSendKeys to perform quoting.
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
The following abbreviated key names are currently recognized within a brace set. If you don't see the desired key, you can still use the unabbreviated name for the key. If you are unsure of this name, utilize the xev (X event view) tool, press the button you need and look at the tools output for the name of the key. Names that are in the list below can be utilized regardless of case. Ones that aren't in this list are going to be case sensitive and also not abbreviated. For example, using 'xev' you will find that the name of the backspace key is BackSpace, so you could use {BackSpace} in place of {bac} if you really wanted to.
Name Action
-------------------
BAC BackSpace
BS BackSpace
BKS BackSpace
BRE Break
CAN Cancel
CAP Caps_Lock
DEL Delete
DOW Down
END End
ENT Return
ESC Escape
F1 F1
... ...
F12 F12
HEL Help
HOM Home
INS Insert
LAL Alt_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
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.
One can utilize the abbreviated key names from the table listed above as outlined in the following example:
# Alt-n
PressKey('LAL'); # Left Alt
PressKey('n');
ReleaseKey('n');
ReleaseKey('LAL');
# Uppercase a
PressKey('LSH'); # Left Shift
PressKey('a');
ReleaseKey('a');
ReleaseKey('LSH');
The ReleaseKey calls in the above example are there to set both key states back.
zero is returned on failure, non-zero for success.
One can utilize the abbreviated key names from the table listed above.
ReleaseKey('n');
zero is returned on failure, non-zero for success.
One can utilize the abbreviated key names from the table listed above.
PressReleaseKey('n');
This function is effected by the key send delay.
zero is returned on failure, non-zero for success.
You can specify such things as 'bac' or the unabbreviated form 'BackSpace' as covered in the SendKeys information. Brace forms such as '{bac}' are unsupported. A '{' is 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.
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.
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
zero is returned on failure, non-zero for success.
my ($x, $y, $width, $height) = GetWindowPos(GetRootWindow());
my ($x, $y) = GetScreenRes();
Value is represented as bits, i.e. 16.
my $depth = GetScreenDepth();
Copyright(c) 2003 Dennis K. Paulsen, All Rights Reserved. This
program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License.
Dennis K. Paulsen <ctrondlp@users.sourceforge.net> (Anthon, Iowa USA)
Thanks to the following people for patches, suggestions, etc.:
Richard Clamp