1GUITest(3) User Contributed Perl Documentation GUITest(3)
2
6 X11::GUITest - Provides GUI testing/interaction routines.
7
9 0.28
10 Updates are made available at the following sites:
12 http://sourceforge.net/projects/x11guitest
14 http://www.cpan.org
15 Please consult 'docs/Changes' for the list of changes between module
17 revisions.
18
20 This Perl package is intended to facilitate the testing of GUI
21 applications by means of user emulation. It can be used to
22 test/interact with GUI applications; which have been built upon the X
23 library or toolkits (i.e., GTK+, Xt, Qt, Motif, etc.) that "wrap" the X
24 library's functionality.
25 A basic recorder (x11guirecord) is also available, and can be found in
27 the source code repository.
28
30 An X server with the XTest extensions enabled. This seems to be the
31 norm. If it is not enabled, it usually can be by modifying the X
32 server configuration (i.e., XF86Config).
33 The standard DISPLAY environment variable is utilized to determine the
35 host, display, and screen to work with. By default it is usually set
36 to ":0.0" for the localhost. However, by altering this variable one
37 can interact with applications under a remote host's X server. To
38 change this from a terminal window, one can utilize the following basic
39 syntax: export DISPLAY=<hostname-or-ipaddress>:<display>.<screen>
40 Please note that under most circumstances, xhost will need to be
41 executed properly on the remote host as well.
42 There is a known incompatibility between the XTest and Xinerama
44 extensions, which causes the XTestFakeMotionEvent() function to
45 misbehave. When the Xinerama (X server) extension is turned on, this
46 (Perl) extension has been modified to allow one to invoke an
47 alternative function. See Makefile.PL for details.
48
50 perl Makefile.PL
51 make
52 make test
53 make install
54 # If the build has errors, you may need to install the following dependencies:
56 # libxt-dev, libxtst-dev
57 # If you'd like to install the recorder, use these steps:
59 cd recorder
60 ./autogen.sh
61 ./configure
62 make
63 make install
64 x11guirecord --help
65
67 For additional examples, please look under the 'eg/' sub-directory from
68 the installation folder.
69 use X11::GUITest qw/
71 StartApp
72 WaitWindowViewable
73 SendKeys
74 /;
75 # Start gedit application
77 StartApp('gedit');
78 # Wait for application window to come up and become viewable.
80 my ($GEditWinId) = WaitWindowViewable('gedit');
81 if (!$GEditWinId) {
82 die("Couldn't find gedit window in time!");
83 }
84 # Send text to it
86 SendKeys("Hello, how are you?\n");
87 # Close Application (Alt-f, q).
89 SendKeys('%(f)q');
90 # Handle gedit's Question window if it comes up when closing. Wait
92 # at most 5 seconds for it.
93 if (WaitWindowViewable('Question', undef, 5)) {
94 # DoN't Save (Alt-n)
95 SendKeys('%(n)');
96 }
97
99 Parameters enclosed within [] are optional.
100 If there are multiple optional parameters available for a function and
102 you would like to specify the last one, for example, you can utilize
103 undef for those parameters you don't specify.
104 REGEX in the documentation below denotes an item that is treated as a
106 regular expression. For example, the regex "^OK$" would look for an
107 exact match for the word OK.
108 FindWindowLike TITLEREGEX [, WINDOWIDSTARTUNDER]
110 Finds the window Ids of the windows matching the specified
111 title regex. Optionally one can specify the window to start
112 under; which would allow one to constrain the search to child
113 windows of that window.
114 An array of window Ids is returned for the matches found. An
116 empty array is returned if no matches were found.
117 my @WindowIds = FindWindowLike('gedit');
119 # Only worry about first window found
120 my ($WindowId) = FindWindowLike('gedit');
121 WaitWindowLike TITLEREGEX [, WINDOWIDSTARTUNDER] [, MAXWAITINSECONDS]
123 Waits for a window to come up that matches the specified title
124 regex. Optionally one can specify the window to start under;
125 which would allow one to constrain the search to child windows
126 of that window.
127 One can optionally specify an alternative wait amount in
129 seconds. A window will keep being looked for that matches the
130 specified title regex until this amount of time has been
131 reached. The default amount is defined in the DEF_WAIT
132 constant available through the :CONST export tag.
133 If a window is going to be manipulated by input,
135 WaitWindowViewable is the more robust solution to utilize.
136 An array of window Ids is returned for the matches found. An
138 empty array is returned if no matches were found.
139 my @WindowIds = WaitWindowLike('gedit');
141 # Only worry about first window found
142 my ($WindowId) = WaitWindowLike('gedit');
143 WaitWindowLike('gedit') or die("gedit window not found!");
145 WaitWindowViewable TITLEREGEX [, WINDOWIDSTARTUNDER] [,
147 MAXWAITINSECONDS]
148 Similar to WaitWindow, but only recognizes windows that are
149 viewable. When GUI applications are started, their window
150 isn't necessarily viewable yet, let alone available for input,
151 so this function is very useful.
152 Likewise, this function will only return an array of the
154 matching window Ids for those windows that are viewable. An
155 empty array is returned if no matches were found.
156 WaitWindowClose WINDOWID [, MAXWAITINSECONDS]
158 Waits for the specified window to close.
159 One can optionally specify an alternative wait amount in
161 seconds. The window will keep being checked to see if it has
162 closed until this amount of time has been reached. The default
163 amount is defined in the DEF_WAIT constant available through
164 the :CONST export tag.
165 zero is returned if window is not gone, non-zero if it is gone.
167 WaitSeconds SECONDS
169 Pauses execution for the specified amount of seconds.
170 WaitSeconds(0.5); # Wait 1/2 second
172 WaitSeconds(3); # Wait 3 seconds
173 ClickWindow WINDOWID [, X Offset] [, Y Offset] [, Button]
175 Clicks on the specified window with the mouse.
176 Optionally one can specify the X offset and Y offset. By
178 default, the top left corner of the window is clicked on, with
179 these two parameters one can specify a different position to be
180 clicked on.
181 One can also specify an alternative button. The default button
183 is M_LEFT, but M_MIDDLE and M_RIGHT may be specified too.
184 Also, you could use the logical Id for the button: M_BTN1,
185 M_BTN2, M_BTN3, M_BTN4, M_BTN5. These are all available
186 through the :CONST export tag.
187 zero is returned on failure, non-zero for success
189 GetWindowsFromPid
191 Returns a list of window ids discovered for the specified
192 process id (pid).
193 undef is returned on error.
195 GetWindowFromPoint X, Y [, SCREEN]
197 Returns the window that is at the specified point. If no
198 screen is given, it is taken from the value given when opening
199 the X display.
200 zero is returned if there are no matches (i.e., off screen).
202 IsChild PARENTWINDOWID, WINDOWID
204 Determines if the specified window is a child of the specified
205 parent.
206 zero is returned for false, non-zero for true.
208 QuoteStringForSendKeys STRING
210 Quotes {} characters in the specified string that would be
211 interpreted as having special meaning if sent to SendKeys
212 directly. This function would be useful if you had a text file
213 in which you wanted to use each line of the file as input to
214 the SendKeys function, but didn't want any special
215 interpretation of the characters in the file.
216 Returns the quoted string, undef is returned on error.
218 # Quote ~, %, etc. as {~}, {%}, etc for literal use in SendKeys.
220 SendKeys( QuoteStringForSendKeys('Hello: ~%^(){}+#') );
221 SendKeys( QSfSK('#+#') );
222 The international AltGr key - modifier character (&) is not
224 escaped by this function. Escape this character manually
225 ("{&}"), if used/needed.
226 StartApp COMMANDLINE
228 Uses the shell to execute a program. This function returns as
229 soon as the program is called. Useful for starting GUI
230 /applications and then going on to work with them.
231 zero is returned on failure, non-zero for success
233 StartApp('gedit');
235 RunApp COMMANDLINE
237 Uses the shell to execute a program until its completion.
238 Return value will be application specific, however -1 is
240 returned to indicate a failure in starting the program.
241 RunApp('/work/myapp');
243 ClickMouseButton BUTTON
245 Clicks the specified mouse button. Available mouse buttons
246 are: M_LEFT, M_MIDDLE, M_RIGHT, M_DOWN, M_UP. Also, you could
247 use the logical Id for the button: M_BTN1, M_BTN2, M_BTN3,
248 M_BTN4, M_BTN5. These are all available through the :CONST
249 export tag.
250 zero is returned on failure, non-zero for success.
252 DefaultScreen
254 Returns the screen number specified in the X display value used
255 to open the display.
256 Leverages the Xlib macro of the same name.
258 ScreenCount
260 Returns the number of screens in the X display specified when
261 opening it.
262 Leverages the Xlib macro of the same name.
264 SetEventSendDelay DELAYINMILLISECONDS
266 Sets the milliseconds of delay between events being sent to the
267 X display. It is usually not a good idea to set this to 0.
268 Please note that this delay will also affect SendKeys.
270 Returns the old delay amount in milliseconds.
272 GetEventSendDelay
274 Returns the current event sending delay amount in milliseconds.
275 SetKeySendDelay DELAYINMILLISECONDS
277 Sets the milliseconds of delay between keystrokes.
278 Returns the old delay amount in milliseconds.
280 GetKeySendDelay
282 Returns the current keystroke sending delay amount in
283 milliseconds.
284 GetWindowName WINDOWID
286 Returns the window name for the specified window Id. undef is
287 returned if name could not be obtained.
288 # Return the name of the window that has the input focus.
290 my $WinName = GetWindowName(GetInputFocus());
291 GetWindowPid WINDOWID
293 Returns the process id (pid) associated with the specified
294 window. 0 is returned if the pid is not available.
295 # Return the pid of the window that has the input focus.
297 my $pid = GetWindowPid(GetInputFocus());
298 SetWindowName WINDOWID, NAME
300 Sets the window name for the specified window Id.
301 zero is returned on failure, non-zero for success.
303 GetRootWindow [SCREEN]
305 Returns the Id of the root window of the screen. This is the
306 top/root level window that all other windows are under. If no
307 screen is given, it is taken from the value given when opening
308 the X display.
309 GetChildWindows WINDOWID
311 Returns an array of the child windows for the specified window
312 Id. If it detects that the window hierarchy is in transition,
313 it will wait half a second and try again.
314 MoveMouseAbs X, Y [, SCREEN]
316 Moves the mouse cursor to the specified absolute position in
317 the optionally given screen. If no screen is given, it is
318 taken from the value given when opening the X display.
319 Zero is returned on failure, non-zero for success.
321 GetMousePos
323 Returns an array containing the position and the screen
324 (number) of the mouse cursor.
325 my ($x, $y, $scr_num) = GetMousePos();
327 PressMouseButton BUTTON
329 Presses the specified mouse button. Available mouse buttons
330 are: M_LEFT, M_MIDDLE, M_RIGHT, M_DOWN, M_UP. Also, you could
331 use the logical Id for the button: M_BTN1, M_BTN2, M_BTN3,
332 M_BTN4, M_BTN5. These are all available through the :CONST
333 export tag.
334 zero is returned on failure, non-zero for success.
336 ReleaseMouseButton BUTTON
338 Releases the specified mouse button. Available mouse buttons
339 are: M_LEFT, M_MIDDLE, M_RIGHT, M_DOWN, M_UP. Also, you could
340 use the logical Id for the button: M_BTN1, M_BTN2, M_BTN3,
341 M_BTN4, M_BTN5. These are all available through the :CONST
342 export tag.
343 zero is returned on failure, non-zero for success.
345 SendKeys KEYS
347 Sends keystrokes to the window that has the input focus.
348 The keystrokes to send are those specified in KEYS parameter.
350 Some characters have special meaning, they are:
351 Modifier Keys:
353 ^ CTRL
354 % ALT
355 + SHIFT
356 # META
357 & ALTGR
358 Other Keys:
360 ~ ENTER
361 \n ENTER
362 \t TAB
363 ( and ) MODIFIER GROUPING
364 { and } QUOTE / ESCAPE CHARACTERS
365 Simply, one can send a text string like so:
367 SendKeys('Hello, how are you today?');
369 Parenthesis allow a modifier to work on one or more characters.
371 For example:
372 SendKeys('%(f)q'); # Alt-f, then press q
374 SendKeys('%(fa)^(m)'); # Alt-f, Alt-a, Ctrl-m
375 SendKeys('+(abc)'); # Uppercase ABC using shift modifier
376 SendKeys('^(+(l))'); # Ctrl-Shift-l
377 SendKeys('+'); # Press shift
378 Braces are used to quote special characters, for utilizing
380 aliased key names, or for special functionality. Multiple
381 characters can be specified in a brace by space delimiting the
382 entries. Characters can be repeated using a number that is
383 space delimited after the preceding key.
384 Quote Special Characters
386 SendKeys('{{}'); # {
388 SendKeys('{+}'); # +
389 SendKeys('{#}'); # #
390 You can also use QuoteStringForSendKeys (QSfSK) to perform quoting.
392 Aliased Key Names
394 SendKeys('{BAC}'); # Backspace
396 SendKeys('{F1 F2 F3}'); # F1, F2, F3
397 SendKeys('{TAB 3}'); # Press TAB 3 times
398 SendKeys('{SPC 3 a b c}'); # Space 3 times, a, b, c
399 Special Functionality
401 # Pause execution for 500 milliseconds
403 SendKeys('{PAUSE 500}');
404 Combinations
406 SendKeys('abc+(abc){TAB PAUSE 500}'); # a, b, c, A, B, C, Tab, Pause 500
408 SendKeys('+({a b c})'); # A, B, C
409 The following abbreviated key names are currently recognized
411 within a brace set. If you don't see the desired key, you can
412 still use the unabbreviated name for the key. If you are
413 unsure of this name, utilize the xev (X event view) tool, press
414 the key you want and look at the tools output for the name of
415 that key. Names that are in the list below can be utilized
416 regardless of case. Ones that aren't in this list are going to
417 be case sensitive and also not abbreviated. For example, using
418 'xev' you will find that the name of the backspace key is
419 BackSpace, so you could use {BackSpace} in place of {bac} if
420 you really wanted to.
421 Name Action
423 -------------------
424 BAC BackSpace
425 BS BackSpace
426 BKS BackSpace
427 BRE Break
428 CAN Cancel
429 CAP Caps_Lock
430 DEL Delete
431 DOWN Down
432 END End
433 ENT Return
434 ESC Escape
435 F1 F1
436 ... ...
437 F12 F12
438 HEL Help
439 HOM Home
440 INS Insert
441 LAL Alt_L
442 LMA Meta_L
443 LCT Control_L
444 LEF Left
445 LSH Shift_L
446 LSK Super_L
447 MNU Menu
448 NUM Num_Lock
449 PGD Page_Down
450 PGU Page_Up
451 PRT Print
452 RAL Alt_R
453 RMA Meta_R
454 RCT Control_R
455 RIG Right
456 RSH Shift_R
457 RSK Super_R
458 SCR Scroll_Lock
459 SPA Space
460 SPC Space
461 TAB Tab
462 UP Up
463 zero is returned on failure, non-zero for success. For
465 configurations (Xvfb) that don't support Alt_Left, Meta_Left is
466 automatically used in its place.
467 PressKey KEY
469 Presses the specified key.
470 One can utilize the abbreviated key names from the table listed
472 above as outlined in the following example:
473 # Alt-n
475 PressKey('LAL'); # Left Alt
476 PressKey('n');
477 ReleaseKey('n');
478 ReleaseKey('LAL');
479 # Uppercase a
481 PressKey('LSH'); # Left Shift
482 PressKey('a');
483 ReleaseKey('a');
484 ReleaseKey('LSH');
485 The ReleaseKey calls in the above example are there to set both
487 key states back.
488 zero is returned on failure, non-zero for success.
490 ReleaseKey KEY
492 Releases the specified key. Normally follows a PressKey call.
493 One can utilize the abbreviated key names from the table listed
495 above.
496 ReleaseKey('n');
498 zero is returned on failure, non-zero for success.
500 PressReleaseKey KEY
502 Presses and releases the specified key.
503 One can utilize the abbreviated key names from the table listed
505 above.
506 PressReleaseKey('n');
508 This function is affected by the key send delay.
510 zero is returned on failure, non-zero for success.
512 IsKeyPressed KEY
514 Determines if the specified key is currently being pressed.
515 You can specify such things as 'bac' or the unabbreviated form
517 'BackSpace' as covered in the SendKeys information. Brace
518 forms such as '{bac}' are unsupported. A '{' is taken
519 literally and letters are case sensitive.
520 if (IsKeyPressed('esc')) { # Is Escape pressed?
522 if (IsKeyPressed('a')) { # Is a pressed?
523 if (IsKeyPressed('A')) { # Is A pressed?
524 Returns non-zero for true, zero for false.
526 IsMouseButtonPressed BUTTON
528 Determines if the specified mouse button is currently being
529 pressed.
530 Available mouse buttons are: M_LEFT, M_MIDDLE, M_RIGHT. Also,
532 you could use the logical Id for the button: M_BTN1, M_BTN2,
533 M_BTN3, M_BTN4, M_BTN5. These are all available through the
534 :CONST export tag.
535 if (IsMouseButtonPressed(M_LEFT)) { # Is left button pressed?
537 Returns non-zero for true, zero for false.
539 IsWindow WINDOWID
541 zero is returned if the specified window Id is not for
542 something that can be recognized as a window. non-zero is
543 returned if it looks like a window.
544 IsWindowViewable WINDOWID
546 zero is returned if the specified window Id is for a window
547 that isn't viewable. non-zero is returned if the window is
548 viewable.
549 IsWindowCursor WINDOWID CURSOR
551 Determines if the specified window has the specified cursor.
552 zero is returned for false, non-zero for true.
554 The following cursors are available through the :CONST export
556 tag.
557 Name
559 -------------------
560 XC_NUM_GLYPHS
561 XC_X_CURSOR
562 XC_ARROW
563 XC_BASED_ARROW_DOWN
564 XC_BASED_ARROW_UP
565 XC_BOAT
566 XC_BOGOSITY
567 XC_BOTTOM_LEFT_CORNER
568 XC_BOTTOM_RIGHT_CORNER
569 XC_BOTTOM_SIDE
570 XC_BOTTOM_TEE
571 XC_BOX_SPIRAL
572 XC_CENTER_PTR
573 XC_CIRCLE
574 XC_CLOCK
575 XC_COFFEE_MUG
576 XC_CROSS
577 XC_CROSS_REVERSE
578 XC_CROSSHAIR
579 XC_DIAMOND_CROSS
580 XC_DOT
581 XC_DOTBOX
582 XC_DOUBLE_ARROW
583 XC_DRAFT_LARGE
584 XC_DRAFT_SMALL
585 XC_DRAPED_BOX
586 XC_EXCHANGE
587 XC_FLEUR
588 XC_GOBBLER
589 XC_GUMBY
590 XC_HAND1
591 XC_HAND2
592 XC_HEART
593 XC_ICON
594 XC_IRON_CROSS
595 XC_LEFT_PTR
596 XC_LEFT_SIDE
597 XC_LEFT_TEE
598 XC_LEFTBUTTON
599 XC_LL_ANGLE
600 XC_LR_ANGLE
601 XC_MAN
602 XC_MIDDLEBUTTON
603 XC_MOUSE
604 XC_PENCIL
605 XC_PIRATE
606 XC_PLUS
607 XC_QUESTION_ARROW
608 XC_RIGHT_PTR
609 XC_RIGHT_SIDE
610 XC_RIGHT_TEE
611 XC_RIGHTBUTTON
612 XC_RTL_LOGO
613 XC_SAILBOAT
614 XC_SB_DOWN_ARROW
615 XC_SB_H_DOUBLE_ARROW
616 XC_SB_LEFT_ARROW
617 XC_SB_RIGHT_ARROW
618 XC_SB_UP_ARROW
619 XC_SB_V_DOUBLE_ARROW
620 XC_SHUTTLE
621 XC_SIZING
622 XC_SPIDER
623 XC_SPRAYCAN
624 XC_STAR
625 XC_TARGET
626 XC_TCROSS
627 XC_TOP_LEFT_ARROW
628 XC_TOP_LEFT_CORNER
629 XC_TOP_RIGHT_CORNER
630 XC_TOP_SIDE
631 XC_TOP_TEE
632 XC_TREK
633 XC_UL_ANGLE
634 XC_UMBRELLA
635 XC_UR_ANGLE
636 XC_WATCH
637 XC_XTERM
638 MoveWindow WINDOWID, X, Y
640 Moves the window to the specified location.
641 zero is returned on failure, non-zero for success.
643 ResizeWindow WINDOWID, WIDTH, HEIGHT
645 Resizes the window to the specified size.
646 zero is returned on failure, non-zero for success.
648 IconifyWindow WINDOWID
650 Minimizes (Iconifies) the specified window.
651 zero is returned on failure, non-zero for success.
653 UnIconifyWindow WINDOWID
655 Unminimizes (UnIconifies) the specified window.
656 zero is returned on failure, non-zero for success.
658 RaiseWindow WINDOWID
660 Raises the specified window to the top of the stack, so that no
661 other windows cover it.
662 zero is returned on failure, non-zero for success.
664 LowerWindow WINDOWID
666 Lowers the specified window to the bottom of the stack, so
667 other existing windows will cover it.
668 zero is returned on failure, non-zero for success.
670 GetInputFocus
672 Returns the window that currently has the input focus.
673 SetInputFocus WINDOWID
675 Sets the specified window to be the one that has the input
676 focus.
677 zero is returned on failure, non-zero for success.
679 GetWindowPos WINDOWID
681 Returns an array containing the position information for the
682 specified window. It also returns size information (including
683 border width) and the number of the screen where the window
684 resides.
685 my ($x, $y, $width, $height, $borderWidth, $screen) =
687 GetWindowPos(GetRootWindow());
688 GetParentWindow WINDOWID
690 Returns the parent of the specified window.
691 zero is returned if parent couldn't be determined (i.e., root
693 window).
694 GetScreenDepth [SCREEN]
696 Returns the color depth for the screen. If no screen is
697 specified, it is taken from the value given when opening the X
698 display. If the screen (number) is invalid, -1 will be
699 returned.
700 Value is represented as bits, i.e. 16.
702 my $depth = GetScreenDepth();
704 GetScreenRes [SCREEN]
706 Returns the screen resolution. If no screen is specified, it
707 is taken from the value given when opening the X display. If
708 the screen (number) is invalid, the returned list will be
709 empty.
710 my ($x, $y) = GetScreenRes();
712
714 Not installed.
715
717 Copyright(c) 2003-2014 Dennis K. Paulsen, All Rights Reserved. This
718 program is free software; you can redistribute it and/or modify it
719 under the terms of the GNU General Public License.
720
722 Dennis K. Paulsen <ctrondlp@cpan.org> (Iowa USA)
723
725 Paulo E. Castro <pauloedgarcastro tata gmail.com>
726
728 Thanks to everyone; including those specifically mentioned below for
729 patches, suggestions, etc.:
730 David Dick
732 Alexey Tourbin
733 Richard Clamp
734 Gustav Larsson
735 Nelson D. Caro
736perl v5.30.0 2019-07-26 GUITest(3)