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