Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GUITest(3)	      User Contributed Perl Documentation	    GUITest(3)

NAME
       X11::GUITest - Provides GUI testing/interaction routines.

VERSION
       0.28

       Updates are made	available at the following sites:

	 http://sourceforge.net/projects/x11guitest
	 http://www.cpan.org

       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.

       A basic recorder	(x11guirecord) is also available, and can be found in
       the source code repository.

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 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

SYNOPSIS
       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.

       WaitSeconds SECONDS
	       Pauses execution	for the	specified amount of seconds.

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

       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

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

	       undef is	returned on error.

       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: ~%^(){}+#') );
		 SendKeys( QSfSK('#+#')	);

	       The international AltGr key - modifier character	(&) is not
	       escaped by this function.  Escape this character	manually
	       ("{&}"),	if used/needed.

       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, 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 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.

	       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 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 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());

       GetWindowPid WINDOWID
	       Returns the process id (pid) associated with the	specified
	       window.	0 is returned if the pid is not	available.

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

       SetWindowName WINDOWID, NAME
	       Sets the	window name for	the specified window Id.

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

       GetRootWindow [SCREEN]
	       Returns the Id of the root window of the	screen.	 This is the
	       top/root	level window that all other windows are	under.	If no
	       screen is given,	it is taken from the value given when opening
	       the X display.

       GetChildWindows WINDOWID
	       Returns an array	of the child windows for the specified window
	       Id.  If it detects that the window hierarchy is in transition,
	       it will wait half a second and try again.

       MoveMouseAbs X, Y [, SCREEN]
	       Moves the mouse cursor to the specified absolute	position in
	       the optionally given screen.  If	no screen is given, it is
	       taken from the value given when opening the X display.

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

       GetMousePos
	       Returns an array	containing the position	and the	screen
	       (number)	of the mouse cursor.

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

       PressMouseButton	BUTTON
	       Presses 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.

       ReleaseMouseButton BUTTON
	       Releases	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.

       SendKeys	KEYS
	       Sends keystrokes	to the window that has the input focus.

	       The keystrokes to send are those	specified in KEYS parameter.
	       Some characters have special meaning, they are:

		       Modifier	Keys:
		       ^       CTRL
		       %       ALT
		       +       SHIFT
		       #       META
		       &       ALTGR

		       Other Keys:
		       ~       ENTER
		       \n      ENTER
		       \t      TAB
		       ( and ) MODIFIER	GROUPING
		       { and } QUOTE / ESCAPE 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 preceding key.

	       Quote Special Characters

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

		       You can also use	QuoteStringForSendKeys (QSfSK) 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 key you want	and look at the	tools output for the name of
	       that 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
		       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.  For
	       configurations (Xvfb) that don't	support	Alt_Left, Meta_Left is
	       automatically used in its place.

       PressKey	KEY
	       Presses the specified key.

	       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.

       ReleaseKey KEY
	       Releases	the specified key.  Normally follows a PressKey	call.

	       One can utilize the abbreviated key names from the table	listed
	       above.

		 ReleaseKey('n');

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

       PressReleaseKey KEY
	       Presses and releases the	specified key.

	       One can utilize the abbreviated key names from the table	listed
	       above.

		 PressReleaseKey('n');

	       This function is	affected by the	key send delay.

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

       IsKeyPressed KEY
	       Determines if the specified key is currently being pressed.

	       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.

       IsMouseButtonPressed BUTTON
	       Determines if the specified mouse button	is currently being
	       pressed.

	       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 specified window	Id is not for
	       something that can be recognized	as a window.  non-zero is
	       returned	if it looks like a window.

       IsWindowViewable	WINDOWID
	       zero is returned	if the specified window	Id is for a window
	       that isn't viewable.  non-zero is returned if the window	is
	       viewable.

       IsWindowCursor WINDOWID CURSOR
	       Determines if 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
		   -------------------
		       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

       MoveWindow WINDOWID, X, Y
	       Moves the window	to the specified location.

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

       ResizeWindow WINDOWID, WIDTH, HEIGHT
	       Resizes the window to the specified size.

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

       IconifyWindow WINDOWID
	       Minimizes (Iconifies) the specified window.

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

       UnIconifyWindow WINDOWID
	       Unminimizes (UnIconifies) the specified window.

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

       RaiseWindow WINDOWID
	       Raises the specified window to the top of the stack, so that no
	       other windows cover it.

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

       LowerWindow WINDOWID
	       Lowers the specified window to the bottom of the	stack, so
	       other existing windows will cover it.

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

       GetInputFocus
	       Returns the window that currently has the input focus.

       SetInputFocus WINDOWID
	       Sets the	specified window to be the one that has	the input
	       focus.

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

       GetWindowPos WINDOWID
	       Returns an array	containing the position	information for	the
	       specified window.  It also returns size information (including
	       border width) and the number of the screen where	the window
	       resides.

		 my ($x, $y, $width, $height, $borderWidth, $screen) =
		       GetWindowPos(GetRootWindow());

       GetParentWindow WINDOWID
	       Returns the parent of the specified window.

	       zero is returned	if parent couldn't be determined (i.e.,	root
	       window).

       GetScreenDepth [SCREEN]
	       Returns the color depth for the screen.	If no screen is
	       specified, it is	taken from the value given when	opening	the X
	       display.	 If the	screen (number)	is invalid, -1 will be
	       returned.

	       Value is	represented as bits, i.e. 16.

		 my $depth = GetScreenDepth();

       GetScreenRes [SCREEN]
	       Returns the screen resolution.  If no screen is specified, it
	       is taken	from the value given when opening the X	display.  If
	       the screen (number) is invalid, the returned list will be
	       empty.

		 my ($x, $y) = GetScreenRes();

OTHER DOCUMENTATION
       Not installed.

COPYRIGHT
       Copyright(c) 2003-2014 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.

AUTHOR
       Dennis K. Paulsen <ctrondlp@cpan.org> (Iowa USA)

CONTRIBUTORS
       Paulo E.	Castro <pauloedgarcastro tata gmail.com>

CREDITS
       Thanks to everyone; including those specifically	mentioned below	for
       patches,	suggestions, etc.:

	 David Dick
	 Alexey	Tourbin
	 Richard Clamp
	 Gustav	Larsson
	 Nelson	D. Caro

perl v5.32.1			  2014-03-17			    GUITest(3)

NAME | VERSION | DESCRIPTION | DEPENDENCIES | INSTALLATION | SYNOPSIS | FUNCTIONS | OTHER DOCUMENTATION | COPYRIGHT | AUTHOR | CONTRIBUTORS | CREDITS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=X11::GUITest&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help