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