NAME
X11::GUITest - Provides GUI testing/interaction facilities.
Developed by Dennis K. Paulsen
VERSION
0.21
Updates are made available at the following sites:
http://sourceforge.net/projects/x11guitest (Primary)
http://www.freshmeat.net (Linked)
http://www.cpan.org (Secondary)Please consult 'docs/Changes' for the list of changes between module revisions.
DESCRIPTION
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.
DEPENDENCIES
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. 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.
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 installSYNOPSIS
For additional examples, please look under the 'eg/' sub-directory from the installation folder.
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)');
}FUNCTIONS
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.
- 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.
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 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.
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 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.
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 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.
- 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.
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
- 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).
- 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 STRING
-
Quotes {} characters in the specified string that would be interpreted as having special meaning if sent to SendKeys directly. 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: ~%^(){}+#') );
- 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.
zero is returned on failure, non-zero for success
StartApp('gedit');
- 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 BUTTON
-
Clicks the specified mouse button. 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.
zero is returned on failure, non-zero for success.