1<?php 2/** Copyright 2006 ThoughtWorks, Inc 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 * 16 * ----------------- 17 * This file has been automatically generated via XSL 18 * ----------------- 19 * 20 * 21 * 22 * @category Testing 23 * @package Selenium 24 * @author Shin Ohno <ganchiku at gmail dot com> 25 * @author Bjoern Schotte <schotte at mayflower dot de> 26 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0 27 * @version @package_version@ 28 * @see http://www.openqa.org/selenium-rc/ 29 * @since 0.1 30 */ 31 32/** 33 * Selenium exception class 34 */ 35require_once 'Testing/Selenium/Exception.php'; 36 37/** 38 * Defines an object that runs Selenium commands. 39 * 40 * 41 * <p> 42 * <b>Element Locators</b> 43 * </p><p> 44 * 45 * Element Locators tell Selenium which HTML element a command refers to. 46 * The format of a locator is: 47 * </p><p> 48 * 49 * <i>locatorType</i><b>=</b><i>argument</i> 50 * </p> 51 * <p> 52 * 53 * We support the following strategies for locating elements: 54 * 55 * </p> 56 * <ul> 57 * 58 * <li> 59 * <b>identifier</b>=<i>id</i>: 60 * Select the element with the specified @id attribute. If no match is 61 * found, select the first element whose @name attribute is <i>id</i>. 62 * (This is normally the default; see below.) 63 * </li> 64 * <li> 65 * <b>id</b>=<i>id</i>: 66 * Select the element with the specified @id attribute. 67 * </li> 68 * <li> 69 * <b>name</b>=<i>name</i>: 70 * Select the first element with the specified @name attribute. 71 * 72 * <ul> 73 * 74 * <li> 75 * username 76 * </li> 77 * <li> 78 * name=username 79 * </li> 80 * </ul> 81<p> 82 * The name may optionally be followed by one or more <i>element-filters</i>, separated from the name by whitespace. If the <i>filterType</i> is not specified, <b>value</b> is assumed. 83 * </p> 84 * <ul> 85 * 86 * <li> 87 * name=flavour value=chocolate 88 * </li> 89 * </ul> 90 * </li> 91 * <li> 92 * <b>dom</b>=<i>javascriptExpression</i>: 93 * 94 * Find an element by evaluating the specified string. This allows you to traverse the HTML Document Object 95 * Model using JavaScript. Note that you must not return a value in this string; simply make it the last expression in the block. 96 * 97 * <ul> 98 * 99 * <li> 100 * dom=document.forms['myForm'].myDropdown 101 * </li> 102 * <li> 103 * dom=document.images[56] 104 * </li> 105 * <li> 106 * dom=function foo() { return document.links[1]; }; foo(); 107 * </li> 108 * </ul> 109 * </li> 110 * <li> 111 * <b>xpath</b>=<i>xpathExpression</i>: 112 * Locate an element using an XPath expression. 113 * 114 * <ul> 115 * 116 * <li> 117 * xpath=//img[@alt='The image alt text'] 118 * </li> 119 * <li> 120 * xpath=//table[@id='table1']//tr[4]/td[2] 121 * </li> 122 * <li> 123 * xpath=//a[contains(@href,'#id1')] 124 * </li> 125 * <li> 126 * xpath=//a[contains(@href,'#id1')]/@class 127 * </li> 128 * <li> 129 * xpath=(//table[@class='stylee'])//th[text()='theHeaderText']/../td 130 * </li> 131 * <li> 132 * xpath=//input[@name='name2' and @value='yes'] 133 * </li> 134 * <li> 135 * xpath=//*[text()="right"] 136 * </li> 137 * </ul> 138 * </li> 139 * <li> 140 * <b>link</b>=<i>textPattern</i>: 141 * Select the link (anchor) element which contains text matching the 142 * specified <i>pattern</i>. 143 * 144 * <ul> 145 * 146 * <li> 147 * link=The link text 148 * </li> 149 * </ul> 150 * </li> 151 * <li> 152 * <b>css</b>=<i>cssSelectorSyntax</i>: 153 * Select the element using css selectors. Please refer to CSS2 selectors, CSS3 selectors for more information. You can also check the TestCssLocators test in the selenium test suite for an example of usage, which is included in the downloaded selenium core package. 154 * 155 * <ul> 156 * 157 * <li> 158 * css=a[href="#id3"] 159 * </li> 160 * <li> 161 * css=span#firstChild + span 162 * </li> 163 * </ul> 164<p> 165 * Currently the css selector locator supports all css1, css2 and css3 selectors except namespace in css3, some pseudo classes(:nth-of-type, :nth-last-of-type, :first-of-type, :last-of-type, :only-of-type, :visited, :hover, :active, :focus, :indeterminate) and pseudo elements(::first-line, ::first-letter, ::selection, ::before, ::after). 166 * </p> 167 * </li> 168 * </ul><p> 169 * 170 * Without an explicit locator prefix, Selenium uses the following default 171 * strategies: 172 * 173 * </p> 174 * <ul> 175 * 176 * <li> 177 * <b>dom</b>, for locators starting with "document." 178 * </li> 179 * <li> 180 * <b>xpath</b>, for locators starting with "//" 181 * </li> 182 * <li> 183 * <b>identifier</b>, otherwise 184 * </li> 185 * </ul> 186 * <p> 187 * <b>Element Filters</b> 188 * </p><p> 189 * 190 * <p> 191 * Element filters can be used with a locator to refine a list of candidate elements. They are currently used only in the 'name' element-locator. 192 * </p> 193<p> 194 * Filters look much like locators, ie. 195 * </p> 196<p> 197 * 198 * <i>filterType</i><b>=</b><i>argument</i> 199 * </p> 200 * <p> 201 * Supported element-filters are: 202 * </p> 203<p> 204 * <b>value=</b><i>valuePattern</i> 205 * </p> 206<p> 207 * 208 * 209 * Matches elements based on their values. This is particularly useful for refining a list of similarly-named toggle-buttons. 210 * </p> 211 * <p> 212 * <b>index=</b><i>index</i> 213 * </p> 214<p> 215 * 216 * 217 * Selects a single element based on its position in the list (offset from zero). 218 * </p> 219 * 220 * </p> 221 * 222 * <p> 223 * <b>String-match Patterns</b> 224 * </p><p> 225 * 226 * Various Pattern syntaxes are available for matching string values: 227 * 228 * </p> 229 * <ul> 230 * 231 * <li> 232 * <b>glob:</b><i>pattern</i>: 233 * Match a string against a "glob" (aka "wildmat") pattern. "Glob" is a 234 * kind of limited regular-expression syntax typically used in command-line 235 * shells. In a glob pattern, "*" represents any sequence of characters, and "?" 236 * represents any single character. Glob patterns match against the entire 237 * string. 238 * </li> 239 * <li> 240 * <b>regexp:</b><i>regexp</i>: 241 * Match a string using a regular-expression. The full power of JavaScript 242 * regular-expressions is available. 243 * </li> 244 * <li> 245 * <b>exact:</b><i>string</i>: 246 * 247 * Match a string exactly, verbatim, without any of that fancy wildcard 248 * stuff. 249 * </li> 250 * </ul><p> 251 * 252 * If no pattern prefix is specified, Selenium assumes that it's a "glob" 253 * pattern. 254 * 255 * </p> 256 * 257 * @package Selenium 258 * @author Shin Ohno <ganchiku at gmail dot com> 259 * @author Bjoern Schotte <schotte at mayflower dot de> 260 */ 261class Testing_Selenium 262{ 263 /** 264 * @var string 265 * @access private 266 */ 267 private $browser; 268 269 /** 270 * @var string 271 * @access private 272 */ 273 private $browserUrl; 274 275 /** 276 * @var string 277 * @access private 278 */ 279 private $host; 280 281 /** 282 * @var int 283 * @access private 284 */ 285 private $port; 286 287 /** 288 * @var string 289 * @access private 290 */ 291 private $sessionId; 292 293 /** 294 * @var string 295 * @access private 296 */ 297 private $timeout; 298 299 /** 300 * Constructor 301 * 302 * @param string $browser 303 * @param string $browserUrl 304 * @param string $host 305 * @param int $port 306 * @param int $timeout 307 * @access public 308 * @throws Testing_Selenium_Exception 309 */ 310 public function __construct($browser, $browserUrl, $host = 'localhost', $port = 4444, $timeout = 30000) 311 { 312 $this->browser = $browser; 313 $this->browserUrl = $browserUrl; 314 $this->host = $host; 315 $this->port = $port; 316 $this->timeout = $timeout; 317 } 318 319 /** 320 * Run the browser and set session id. 321 * 322 * @access public 323 * @return void 324 */ 325 public function start() 326 { 327 $this->sessionId = $this->getString("getNewBrowserSession", array($this->browser, $this->browserUrl)); 328 return $this->sessionId; 329 } 330 331 /** 332 * Close the browser and set session id null 333 * 334 * @access public 335 * @return void 336 */ 337 public function stop() 338 { 339 $this->doCommand("testComplete"); 340 $this->sessionId = null; 341 } 342 343 /** 344 * Clicks on a link, button, checkbox or radio button. If the click action 345 * causes a new page to load (like a link usually does), call 346 * waitForPageToLoad. 347 * 348 * @access public 349 * @param string $locator an element locator 350 */ 351 public function click($locator) 352 { 353 $this->doCommand("click", array($locator)); 354 } 355 356 357 /** 358 * Double clicks on a link, button, checkbox or radio button. If the double click action 359 * causes a new page to load (like a link usually does), call 360 * waitForPageToLoad. 361 * 362 * @access public 363 * @param string $locator an element locator 364 */ 365 public function doubleClick($locator) 366 { 367 $this->doCommand("doubleClick", array($locator)); 368 } 369 370 371 /** 372 * Clicks on a link, button, checkbox or radio button. If the click action 373 * causes a new page to load (like a link usually does), call 374 * waitForPageToLoad. 375 * 376 * @access public 377 * @param string $locator an element locator 378 * @param string $coordString specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator. 379 */ 380 public function clickAt($locator, $coordString) 381 { 382 $this->doCommand("clickAt", array($locator, $coordString)); 383 } 384 385 386 /** 387 * Doubleclicks on a link, button, checkbox or radio button. If the action 388 * causes a new page to load (like a link usually does), call 389 * waitForPageToLoad. 390 * 391 * @access public 392 * @param string $locator an element locator 393 * @param string $coordString specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator. 394 */ 395 public function doubleClickAt($locator, $coordString) 396 { 397 $this->doCommand("doubleClickAt", array($locator, $coordString)); 398 } 399 400 401 /** 402 * Explicitly simulate an event, to trigger the corresponding "on<i>event</i>" 403 * handler. 404 * 405 * @access public 406 * @param string $locator an element locator 407 * @param string $eventName the event name, e.g. "focus" or "blur" 408 */ 409 public function fireEvent($locator, $eventName) 410 { 411 $this->doCommand("fireEvent", array($locator, $eventName)); 412 } 413 414 415 /** 416 * Simulates a user pressing and releasing a key. 417 * 418 * @access public 419 * @param string $locator an element locator 420 * @param string $keySequence Either be a string("\" followed by the numeric keycode of the key to be pressed, normally the ASCII value of that key), or a single character. For example: "w", "\119". 421 */ 422 public function keyPress($locator, $keySequence) 423 { 424 $this->doCommand("keyPress", array($locator, $keySequence)); 425 } 426 427 428 /** 429 * Press the shift key and hold it down until doShiftUp() is called or a new page is loaded. 430 * 431 * @access public 432 */ 433 public function shiftKeyDown() 434 { 435 $this->doCommand("shiftKeyDown", array()); 436 } 437 438 439 /** 440 * Release the shift key. 441 * 442 * @access public 443 */ 444 public function shiftKeyUp() 445 { 446 $this->doCommand("shiftKeyUp", array()); 447 } 448 449 450 /** 451 * Press the meta key and hold it down until doMetaUp() is called or a new page is loaded. 452 * 453 * @access public 454 */ 455 public function metaKeyDown() 456 { 457 $this->doCommand("metaKeyDown", array()); 458 } 459 460 461 /** 462 * Release the meta key. 463 * 464 * @access public 465 */ 466 public function metaKeyUp() 467 { 468 $this->doCommand("metaKeyUp", array()); 469 } 470 471 472 /** 473 * Press the alt key and hold it down until doAltUp() is called or a new page is loaded. 474 * 475 * @access public 476 */ 477 public function altKeyDown() 478 { 479 $this->doCommand("altKeyDown", array()); 480 } 481 482 483 /** 484 * Release the alt key. 485 * 486 * @access public 487 */ 488 public function altKeyUp() 489 { 490 $this->doCommand("altKeyUp", array()); 491 } 492 493 494 /** 495 * Press the control key and hold it down until doControlUp() is called or a new page is loaded. 496 * 497 * @access public 498 */ 499 public function controlKeyDown() 500 { 501 $this->doCommand("controlKeyDown", array()); 502 } 503 504 505 /** 506 * Release the control key. 507 * 508 * @access public 509 */ 510 public function controlKeyUp() 511 { 512 $this->doCommand("controlKeyUp", array()); 513 } 514 515 516 /** 517 * Simulates a user pressing a key (without releasing it yet). 518 * 519 * @access public 520 * @param string $locator an element locator 521 * @param string $keySequence Either be a string("\" followed by the numeric keycode of the key to be pressed, normally the ASCII value of that key), or a single character. For example: "w", "\119". 522 */ 523 public function keyDown($locator, $keySequence) 524 { 525 $this->doCommand("keyDown", array($locator, $keySequence)); 526 } 527 528 529 /** 530 * Simulates a user releasing a key. 531 * 532 * @access public 533 * @param string $locator an element locator 534 * @param string $keySequence Either be a string("\" followed by the numeric keycode of the key to be pressed, normally the ASCII value of that key), or a single character. For example: "w", "\119". 535 */ 536 public function keyUp($locator, $keySequence) 537 { 538 $this->doCommand("keyUp", array($locator, $keySequence)); 539 } 540 541 542 /** 543 * Simulates a user hovering a mouse over the specified element. 544 * 545 * @access public 546 * @param string $locator an element locator 547 */ 548 public function mouseOver($locator) 549 { 550 $this->doCommand("mouseOver", array($locator)); 551 } 552 553 554 /** 555 * Simulates a user moving the mouse pointer away from the specified element. 556 * 557 * @access public 558 * @param string $locator an element locator 559 */ 560 public function mouseOut($locator) 561 { 562 $this->doCommand("mouseOut", array($locator)); 563 } 564 565 566 /** 567 * Simulates a user pressing the mouse button (without releasing it yet) on 568 * the specified element. 569 * 570 * @access public 571 * @param string $locator an element locator 572 */ 573 public function mouseDown($locator) 574 { 575 $this->doCommand("mouseDown", array($locator)); 576 } 577 578 579 /** 580 * Simulates a user pressing the mouse button (without releasing it yet) at 581 * the specified location. 582 * 583 * @access public 584 * @param string $locator an element locator 585 * @param string $coordString specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator. 586 */ 587 public function mouseDownAt($locator, $coordString) 588 { 589 $this->doCommand("mouseDownAt", array($locator, $coordString)); 590 } 591 592 593 /** 594 * Simulates the event that occurs when the user releases the mouse button (i.e., stops 595 * holding the button down) on the specified element. 596 * 597 * @access public 598 * @param string $locator an element locator 599 */ 600 public function mouseUp($locator) 601 { 602 $this->doCommand("mouseUp", array($locator)); 603 } 604 605 606 /** 607 * Simulates the event that occurs when the user releases the mouse button (i.e., stops 608 * holding the button down) at the specified location. 609 * 610 * @access public 611 * @param string $locator an element locator 612 * @param string $coordString specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator. 613 */ 614 public function mouseUpAt($locator, $coordString) 615 { 616 $this->doCommand("mouseUpAt", array($locator, $coordString)); 617 } 618 619 620 /** 621 * Simulates a user pressing the mouse button (without releasing it yet) on 622 * the specified element. 623 * 624 * @access public 625 * @param string $locator an element locator 626 */ 627 public function mouseMove($locator) 628 { 629 $this->doCommand("mouseMove", array($locator)); 630 } 631 632 633 /** 634 * Simulates a user pressing the mouse button (without releasing it yet) on 635 * the specified element. 636 * 637 * @access public 638 * @param string $locator an element locator 639 * @param string $coordString specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator. 640 */ 641 public function mouseMoveAt($locator, $coordString) 642 { 643 $this->doCommand("mouseMoveAt", array($locator, $coordString)); 644 } 645 646 647 /** 648 * Sets the value of an input field, as though you typed it in. 649 * 650 * <p> 651 * Can also be used to set the value of combo boxes, check boxes, etc. In these cases, 652 * value should be the value of the option selected, not the visible text. 653 * </p> 654 * 655 * @access public 656 * @param string $locator an element locator 657 * @param string $value the value to type 658 */ 659 public function type($locator, $value) 660 { 661 $this->doCommand("type", array($locator, $value)); 662 } 663 664 665 /** 666 * Simulates keystroke events on the specified element, as though you typed the value key-by-key. 667 * 668 * <p> 669 * This is a convenience method for calling keyDown, keyUp, keyPress for every character in the specified string; 670 * this is useful for dynamic UI widgets (like auto-completing combo boxes) that require explicit key events. 671 * </p><p> 672 * Unlike the simple "type" command, which forces the specified value into the page directly, this command 673 * may or may not have any visible effect, even in cases where typing keys would normally have a visible effect. 674 * For example, if you use "typeKeys" on a form element, you may or may not see the results of what you typed in 675 * the field. 676 * </p><p> 677 * In some cases, you may need to use the simple "type" command to set the value of the field and then the "typeKeys" command to 678 * send the keystroke events corresponding to what you just typed. 679 * </p> 680 * 681 * @access public 682 * @param string $locator an element locator 683 * @param string $value the value to type 684 */ 685 public function typeKeys($locator, $value) 686 { 687 $this->doCommand("typeKeys", array($locator, $value)); 688 } 689 690 691 /** 692 * Set execution speed (i.e., set the millisecond length of a delay which will follow each selenium operation). By default, there is no such delay, i.e., 693 * the delay is 0 milliseconds. 694 * 695 * @access public 696 * @param string $value the number of milliseconds to pause after operation 697 */ 698 public function setSpeed($value) 699 { 700 $this->doCommand("setSpeed", array($value)); 701 } 702 703 704 /** 705 * Get execution speed (i.e., get the millisecond length of the delay following each selenium operation). By default, there is no such delay, i.e., 706 * the delay is 0 milliseconds. 707 * 708 * See also setSpeed. 709 * 710 * @access public 711 */ 712 public function getSpeed() 713 { 714 $this->doCommand("getSpeed", array()); 715 } 716 717 718 /** 719 * Check a toggle-button (checkbox/radio) 720 * 721 * @access public 722 * @param string $locator an element locator 723 */ 724 public function check($locator) 725 { 726 $this->doCommand("check", array($locator)); 727 } 728 729 730 /** 731 * Uncheck a toggle-button (checkbox/radio) 732 * 733 * @access public 734 * @param string $locator an element locator 735 */ 736 public function uncheck($locator) 737 { 738 $this->doCommand("uncheck", array($locator)); 739 } 740 741 742 /** 743 * Select an option from a drop-down using an option locator. 744 * 745 * <p> 746 * 747 * Option locators provide different ways of specifying options of an HTML 748 * Select element (e.g. for selecting a specific option, or for asserting 749 * that the selected option satisfies a specification). There are several 750 * forms of Select Option Locator. 751 * 752 * </p> 753 * <ul> 754 * 755 * <li> 756 * <b>label</b>=<i>labelPattern</i>: 757 * matches options based on their labels, i.e. the visible text. (This 758 * is the default.) 759 * 760 * <ul> 761 * 762 * <li> 763 * label=regexp:^[Oo]ther 764 * </li> 765 * </ul> 766 * </li> 767 * <li> 768 * <b>value</b>=<i>valuePattern</i>: 769 * matches options based on their values. 770 * 771 * <ul> 772 * 773 * <li> 774 * value=other 775 * </li> 776 * </ul> 777 * </li> 778 * <li> 779 * <b>id</b>=<i>id</i>: 780 * 781 * matches options based on their ids. 782 * 783 * <ul> 784 * 785 * <li> 786 * id=option1 787 * </li> 788 * </ul> 789 * </li> 790 * <li> 791 * <b>index</b>=<i>index</i>: 792 * matches an option based on its index (offset from zero). 793 * 794 * <ul> 795 * 796 * <li> 797 * index=2 798 * </li> 799 * </ul> 800 * </li> 801 * </ul><p> 802 * 803 * If no option locator prefix is provided, the default behaviour is to match on <b>label</b>. 804 * 805 * </p> 806 * 807 * @access public 808 * @param string $selectLocator an element locator identifying a drop-down menu 809 * @param string $optionLocator an option locator (a label by default) 810 */ 811 public function select($selectLocator, $optionLocator) 812 { 813 $this->doCommand("select", array($selectLocator, $optionLocator)); 814 } 815 816 817 /** 818 * Add a selection to the set of selected options in a multi-select element using an option locator. 819 * 820 * @see #doSelect for details of option locators 821 * 822 * @access public 823 * @param string $locator an element locator identifying a multi-select box 824 * @param string $optionLocator an option locator (a label by default) 825 */ 826 public function addSelection($locator, $optionLocator) 827 { 828 $this->doCommand("addSelection", array($locator, $optionLocator)); 829 } 830 831 832 /** 833 * Remove a selection from the set of selected options in a multi-select element using an option locator. 834 * 835 * @see #doSelect for details of option locators 836 * 837 * @access public 838 * @param string $locator an element locator identifying a multi-select box 839 * @param string $optionLocator an option locator (a label by default) 840 */ 841 public function removeSelection($locator, $optionLocator) 842 { 843 $this->doCommand("removeSelection", array($locator, $optionLocator)); 844 } 845 846 847 /** 848 * Unselects all of the selected options in a multi-select element. 849 * 850 * @access public 851 * @param string $locator an element locator identifying a multi-select box 852 */ 853 public function removeAllSelections($locator) 854 { 855 $this->doCommand("removeAllSelections", array($locator)); 856 } 857 858 859 /** 860 * Submit the specified form. This is particularly useful for forms without 861 * submit buttons, e.g. single-input "Search" forms. 862 * 863 * @access public 864 * @param string $formLocator an element locator for the form you want to submit 865 */ 866 public function submit($formLocator) 867 { 868 $this->doCommand("submit", array($formLocator)); 869 } 870 871 872 /** 873 * Opens an URL in the test frame. This accepts both relative and absolute 874 * URLs. 875 * 876 * The "open" command waits for the page to load before proceeding, 877 * ie. the "AndWait" suffix is implicit. 878 * 879 * <i>Note</i>: The URL must be on the same domain as the runner HTML 880 * due to security restrictions in the browser (Same Origin Policy). If you 881 * need to open an URL on another domain, use the Selenium Server to start a 882 * new browser session on that domain. 883 * 884 * @access public 885 * @param string $url the URL to open; may be relative or absolute 886 */ 887 public function open($url) 888 { 889 $this->doCommand("open", array($url)); 890 } 891 892 893 /** 894 * Opens a popup window (if a window with that ID isn't already open). 895 * After opening the window, you'll need to select it using the selectWindow 896 * command. 897 * 898 * <p> 899 * This command can also be a useful workaround for bug SEL-339. In some cases, Selenium will be unable to intercept a call to window.open (if the call occurs during or before the "onLoad" event, for example). 900 * In those cases, you can force Selenium to notice the open window's name by using the Selenium openWindow command, using 901 * an empty (blank) url, like this: openWindow("", "myFunnyWindow"). 902 * </p> 903 * 904 * @access public 905 * @param string $url the URL to open, which can be blank 906 * @param string $windowID the JavaScript window ID of the window to select 907 */ 908 public function openWindow($url, $windowID) 909 { 910 $this->doCommand("openWindow", array($url, $windowID)); 911 } 912 913 914 /** 915 * Selects a popup window; once a popup window has been selected, all 916 * commands go to that window. To select the main window again, use null 917 * as the target. 918 * 919 * <p> 920 * Note that there is a big difference between a window's internal JavaScript "name" property 921 * and the "title" of a given window's document (which is normally what you actually see, as an end user, 922 * in the title bar of the window). The "name" is normally invisible to the end-user; it's the second 923 * parameter "windowName" passed to the JavaScript method window.open(url, windowName, windowFeatures, replaceFlag) 924 * (which selenium intercepts). 925 * </p><p> 926 * Selenium has several strategies for finding the window object referred to by the "windowID" parameter. 927 * </p><p> 928 * 1.) if windowID is null, (or the string "null") then it is assumed the user is referring to the original window instantiated by the browser). 929 * </p><p> 930 * 2.) if the value of the "windowID" parameter is a JavaScript variable name in the current application window, then it is assumed 931 * that this variable contains the return value from a call to the JavaScript window.open() method. 932 * </p><p> 933 * 3.) Otherwise, selenium looks in a hash it maintains that maps string names to window "names". 934 * </p><p> 935 * 4.) If <i>that</i> fails, we'll try looping over all of the known windows to try to find the appropriate "title". 936 * Since "title" is not necessarily unique, this may have unexpected behavior. 937 * </p><p> 938 * If you're having trouble figuring out what is the name of a window that you want to manipulate, look at the selenium log messages 939 * which identify the names of windows created via window.open (and therefore intercepted by selenium). You will see messages 940 * like the following for each window as it is opened: 941 * </p><p> 942 * <code>debug: window.open call intercepted; window ID (which you can use with selectWindow()) is "myNewWindow"</code> 943 * </p><p> 944 * In some cases, Selenium will be unable to intercept a call to window.open (if the call occurs during or before the "onLoad" event, for example). 945 * (This is bug SEL-339.) In those cases, you can force Selenium to notice the open window's name by using the Selenium openWindow command, using 946 * an empty (blank) url, like this: openWindow("", "myFunnyWindow"). 947 * </p> 948 * 949 * @access public 950 * @param string $windowID the JavaScript window ID of the window to select 951 */ 952 public function selectWindow($windowID) 953 { 954 $this->doCommand("selectWindow", array($windowID)); 955 } 956 957 958 /** 959 * Selects a frame within the current window. (You may invoke this command 960 * multiple times to select nested frames.) To select the parent frame, use 961 * "relative=parent" as a locator; to select the top frame, use "relative=top". 962 * You can also select a frame by its 0-based index number; select the first frame with 963 * "index=0", or the third frame with "index=2". 964 * 965 * <p> 966 * You may also use a DOM expression to identify the frame you want directly, 967 * like this: <code>dom=frames["main"].frames["subframe"]</code> 968 * </p> 969 * 970 * @access public 971 * @param string $locator an element locator identifying a frame or iframe 972 */ 973 public function selectFrame($locator) 974 { 975 $this->doCommand("selectFrame", array($locator)); 976 } 977 978 979 /** 980 * Determine whether current/locator identify the frame containing this running code. 981 * 982 * <p> 983 * This is useful in proxy injection mode, where this code runs in every 984 * browser frame and window, and sometimes the selenium server needs to identify 985 * the "current" frame. In this case, when the test calls selectFrame, this 986 * routine is called for each frame to figure out which one has been selected. 987 * The selected frame will return true, while all others will return false. 988 * </p> 989 * 990 * @access public 991 * @param string $currentFrameString starting frame 992 * @param string $target new frame (which might be relative to the current one) 993 * @return boolean true if the new frame is this code's window 994 */ 995 public function getWhetherThisFrameMatchFrameExpression($currentFrameString, $target) 996 { 997 return $this->getBoolean("getWhetherThisFrameMatchFrameExpression", array($currentFrameString, $target)); 998 } 999 1000 1001 /** 1002 * Determine whether currentWindowString plus target identify the window containing this running code. 1003 * 1004 * <p> 1005 * This is useful in proxy injection mode, where this code runs in every 1006 * browser frame and window, and sometimes the selenium server needs to identify 1007 * the "current" window. In this case, when the test calls selectWindow, this 1008 * routine is called for each window to figure out which one has been selected. 1009 * The selected window will return true, while all others will return false. 1010 * </p> 1011 * 1012 * @access public 1013 * @param string $currentWindowString starting window 1014 * @param string $target new window (which might be relative to the current one, e.g., "_parent") 1015 * @return boolean true if the new window is this code's window 1016 */ 1017 public function getWhetherThisWindowMatchWindowExpression($currentWindowString, $target) 1018 { 1019 return $this->getBoolean("getWhetherThisWindowMatchWindowExpression", array($currentWindowString, $target)); 1020 } 1021 1022 1023 /** 1024 * Waits for a popup window to appear and load up. 1025 * 1026 * @access public 1027 * @param string $windowID the JavaScript window ID of the window that will appear 1028 * @param string $timeout a timeout in milliseconds, after which the action will return with an error 1029 */ 1030 public function waitForPopUp($windowID, $timeout) 1031 { 1032 $this->doCommand("waitForPopUp", array($windowID, $timeout)); 1033 } 1034 1035 1036 /** 1037 * By default, Selenium's overridden window.confirm() function will 1038 * return true, as if the user had manually clicked OK; after running 1039 * this command, the next call to confirm() will return false, as if 1040 * the user had clicked Cancel. Selenium will then resume using the 1041 * default behavior for future confirmations, automatically returning 1042 * true (OK) unless/until you explicitly call this command for each 1043 * confirmation. 1044 * 1045 * @access public 1046 */ 1047 public function chooseCancelOnNextConfirmation() 1048 { 1049 $this->doCommand("chooseCancelOnNextConfirmation", array()); 1050 } 1051 1052 1053 /** 1054 * Undo the effect of calling chooseCancelOnNextConfirmation. Note 1055 * that Selenium's overridden window.confirm() function will normally automatically 1056 * return true, as if the user had manually clicked OK, so you shouldn't 1057 * need to use this command unless for some reason you need to change 1058 * your mind prior to the next confirmation. After any confirmation, Selenium will resume using the 1059 * default behavior for future confirmations, automatically returning 1060 * true (OK) unless/until you explicitly call chooseCancelOnNextConfirmation for each 1061 * confirmation. 1062 * 1063 * @access public 1064 */ 1065 public function chooseOkOnNextConfirmation() 1066 { 1067 $this->doCommand("chooseOkOnNextConfirmation", array()); 1068 } 1069 1070 1071 /** 1072 * Instructs Selenium to return the specified answer string in response to 1073 * the next JavaScript prompt [window.prompt()]. 1074 * 1075 * @access public 1076 * @param string $answer the answer to give in response to the prompt pop-up 1077 */ 1078 public function answerOnNextPrompt($answer) 1079 { 1080 $this->doCommand("answerOnNextPrompt", array($answer)); 1081 } 1082 1083 1084 /** 1085 * Simulates the user clicking the "back" button on their browser. 1086 * 1087 * @access public 1088 */ 1089 public function goBack() 1090 { 1091 $this->doCommand("goBack", array()); 1092 } 1093 1094 1095 /** 1096 * Simulates the user clicking the "Refresh" button on their browser. 1097 * 1098 * @access public 1099 */ 1100 public function refresh() 1101 { 1102 $this->doCommand("refresh", array()); 1103 } 1104 1105 1106 /** 1107 * Simulates the user clicking the "close" button in the titlebar of a popup 1108 * window or tab. 1109 * 1110 * @access public 1111 */ 1112 public function close() 1113 { 1114 $this->doCommand("close", array()); 1115 } 1116 1117 1118 /** 1119 * Has an alert occurred? 1120 * 1121 * <p> 1122 * 1123 * This function never throws an exception 1124 * 1125 * </p> 1126 * 1127 * @access public 1128 * @return boolean true if there is an alert 1129 */ 1130 public function isAlertPresent() 1131 { 1132 return $this->getBoolean("isAlertPresent", array()); 1133 } 1134 1135 1136 /** 1137 * Has a prompt occurred? 1138 * 1139 * <p> 1140 * 1141 * This function never throws an exception 1142 * 1143 * </p> 1144 * 1145 * @access public 1146 * @return boolean true if there is a pending prompt 1147 */ 1148 public function isPromptPresent() 1149 { 1150 return $this->getBoolean("isPromptPresent", array()); 1151 } 1152 1153 1154 /** 1155 * Has confirm() been called? 1156 * 1157 * <p> 1158 * 1159 * This function never throws an exception 1160 * 1161 * </p> 1162 * 1163 * @access public 1164 * @return boolean true if there is a pending confirmation 1165 */ 1166 public function isConfirmationPresent() 1167 { 1168 return $this->getBoolean("isConfirmationPresent", array()); 1169 } 1170 1171 1172 /** 1173 * Retrieves the message of a JavaScript alert generated during the previous action, or fail if there were no alerts. 1174 * 1175 * <p> 1176 * Getting an alert has the same effect as manually clicking OK. If an 1177 * alert is generated but you do not get/verify it, the next Selenium action 1178 * will fail. 1179 * </p><p> 1180 * NOTE: under Selenium, JavaScript alerts will NOT pop up a visible alert 1181 * dialog. 1182 * </p><p> 1183 * NOTE: Selenium does NOT support JavaScript alerts that are generated in a 1184 * page's onload() event handler. In this case a visible dialog WILL be 1185 * generated and Selenium will hang until someone manually clicks OK. 1186 * </p> 1187 * 1188 * @access public 1189 * @return string The message of the most recent JavaScript alert 1190 */ 1191 public function getAlert() 1192 { 1193 return $this->getString("getAlert", array()); 1194 } 1195 1196 1197 /** 1198 * Retrieves the message of a JavaScript confirmation dialog generated during 1199 * the previous action. 1200 * 1201 * <p> 1202 * 1203 * By default, the confirm function will return true, having the same effect 1204 * as manually clicking OK. This can be changed by prior execution of the 1205 * chooseCancelOnNextConfirmation command. If an confirmation is generated 1206 * but you do not get/verify it, the next Selenium action will fail. 1207 * 1208 * </p><p> 1209 * 1210 * NOTE: under Selenium, JavaScript confirmations will NOT pop up a visible 1211 * dialog. 1212 * 1213 * </p><p> 1214 * 1215 * NOTE: Selenium does NOT support JavaScript confirmations that are 1216 * generated in a page's onload() event handler. In this case a visible 1217 * dialog WILL be generated and Selenium will hang until you manually click 1218 * OK. 1219 * 1220 * </p> 1221 * 1222 * @access public 1223 * @return string the message of the most recent JavaScript confirmation dialog 1224 */ 1225 public function getConfirmation() 1226 { 1227 return $this->getString("getConfirmation", array()); 1228 } 1229 1230 1231 /** 1232 * Retrieves the message of a JavaScript question prompt dialog generated during 1233 * the previous action. 1234 * 1235 * <p> 1236 * Successful handling of the prompt requires prior execution of the 1237 * answerOnNextPrompt command. If a prompt is generated but you 1238 * do not get/verify it, the next Selenium action will fail. 1239 * </p><p> 1240 * NOTE: under Selenium, JavaScript prompts will NOT pop up a visible 1241 * dialog. 1242 * </p><p> 1243 * NOTE: Selenium does NOT support JavaScript prompts that are generated in a 1244 * page's onload() event handler. In this case a visible dialog WILL be 1245 * generated and Selenium will hang until someone manually clicks OK. 1246 * </p> 1247 * 1248 * @access public 1249 * @return string the message of the most recent JavaScript question prompt 1250 */ 1251 public function getPrompt() 1252 { 1253 return $this->getString("getPrompt", array()); 1254 } 1255 1256 1257 /** 1258 * Gets the absolute URL of the current page. 1259 * 1260 * @access public 1261 * @return string the absolute URL of the current page 1262 */ 1263 public function getLocation() 1264 { 1265 return $this->getString("getLocation", array()); 1266 } 1267 1268 1269 /** 1270 * Gets the title of the current page. 1271 * 1272 * @access public 1273 * @return string the title of the current page 1274 */ 1275 public function getTitle() 1276 { 1277 return $this->getString("getTitle", array()); 1278 } 1279 1280 1281 /** 1282 * Gets the entire text of the page. 1283 * 1284 * @access public 1285 * @return string the entire text of the page 1286 */ 1287 public function getBodyText() 1288 { 1289 return $this->getString("getBodyText", array()); 1290 } 1291 1292 1293 /** 1294 * Gets the (whitespace-trimmed) value of an input field (or anything else with a value parameter). 1295 * For checkbox/radio elements, the value will be "on" or "off" depending on 1296 * whether the element is checked or not. 1297 * 1298 * @access public 1299 * @param string $locator an element locator 1300 * @return string the element value, or "on/off" for checkbox/radio elements 1301 */ 1302 public function getValue($locator) 1303 { 1304 return $this->getString("getValue", array($locator)); 1305 } 1306 1307 1308 /** 1309 * Gets the text of an element. This works for any element that contains 1310 * text. This command uses either the textContent (Mozilla-like browsers) or 1311 * the innerText (IE-like browsers) of the element, which is the rendered 1312 * text shown to the user. 1313 * 1314 * @access public 1315 * @param string $locator an element locator 1316 * @return string the text of the element 1317 */ 1318 public function getText($locator) 1319 { 1320 return $this->getString("getText", array($locator)); 1321 } 1322 1323 1324 /** 1325 * Briefly changes the backgroundColor of the specified element yellow. Useful for debugging. 1326 * 1327 * @access public 1328 * @param string $locator an element locator 1329 */ 1330 public function highlight($locator) 1331 { 1332 $this->doCommand("highlight", array($locator)); 1333 } 1334 1335 1336 /** 1337 * Gets the result of evaluating the specified JavaScript snippet. The snippet may 1338 * have multiple lines, but only the result of the last line will be returned. 1339 * 1340 * <p> 1341 * Note that, by default, the snippet will run in the context of the "selenium" 1342 * object itself, so <code>this</code> will refer to the Selenium object. Use <code>window</code> to 1343 * refer to the window of your application, e.g. <code>window.document.getElementById('foo')</code> 1344 * </p><p> 1345 * If you need to use 1346 * a locator to refer to a single element in your application page, you can 1347 * use <code>this.browserbot.findElement("id=foo")</code> where "id=foo" is your locator. 1348 * </p> 1349 * 1350 * @access public 1351 * @param string $script the JavaScript snippet to run 1352 * @return string the results of evaluating the snippet 1353 */ 1354 public function getEval($script) 1355 { 1356 return $this->getString("getEval", array($script)); 1357 } 1358 1359 1360 /** 1361 * Gets whether a toggle-button (checkbox/radio) is checked. Fails if the specified element doesn't exist or isn't a toggle-button. 1362 * 1363 * @access public 1364 * @param string $locator an element locator pointing to a checkbox or radio button 1365 * @return boolean true if the checkbox is checked, false otherwise 1366 */ 1367 public function isChecked($locator) 1368 { 1369 return $this->getBoolean("isChecked", array($locator)); 1370 } 1371 1372 1373 /** 1374 * Gets the text from a cell of a table. The cellAddress syntax 1375 * tableLocator.row.column, where row and column start at 0. 1376 * 1377 * @access public 1378 * @param string $tableCellAddress a cell address, e.g. "foo.1.4" 1379 * @return string the text from the specified cell 1380 */ 1381 public function getTable($tableCellAddress) 1382 { 1383 return $this->getString("getTable", array($tableCellAddress)); 1384 } 1385 1386 1387 /** 1388 * Gets all option labels (visible text) for selected options in the specified select or multi-select element. 1389 * 1390 * @access public 1391 * @param string $selectLocator an element locator identifying a drop-down menu 1392 * @return array an array of all selected option labels in the specified select drop-down 1393 */ 1394 public function getSelectedLabels($selectLocator) 1395 { 1396 return $this->getStringArray("getSelectedLabels", array($selectLocator)); 1397 } 1398 1399 1400 /** 1401 * Gets option label (visible text) for selected option in the specified select element. 1402 * 1403 * @access public 1404 * @param string $selectLocator an element locator identifying a drop-down menu 1405 * @return string the selected option label in the specified select drop-down 1406 */ 1407 public function getSelectedLabel($selectLocator) 1408 { 1409 return $this->getString("getSelectedLabel", array($selectLocator)); 1410 } 1411 1412 1413 /** 1414 * Gets all option values (value attributes) for selected options in the specified select or multi-select element. 1415 * 1416 * @access public 1417 * @param string $selectLocator an element locator identifying a drop-down menu 1418 * @return array an array of all selected option values in the specified select drop-down 1419 */ 1420 public function getSelectedValues($selectLocator) 1421 { 1422 return $this->getStringArray("getSelectedValues", array($selectLocator)); 1423 } 1424 1425 1426 /** 1427 * Gets option value (value attribute) for selected option in the specified select element. 1428 * 1429 * @access public 1430 * @param string $selectLocator an element locator identifying a drop-down menu 1431 * @return string the selected option value in the specified select drop-down 1432 */ 1433 public function getSelectedValue($selectLocator) 1434 { 1435 return $this->getString("getSelectedValue", array($selectLocator)); 1436 } 1437 1438 1439 /** 1440 * Gets all option indexes (option number, starting at 0) for selected options in the specified select or multi-select element. 1441 * 1442 * @access public 1443 * @param string $selectLocator an element locator identifying a drop-down menu 1444 * @return array an array of all selected option indexes in the specified select drop-down 1445 */ 1446 public function getSelectedIndexes($selectLocator) 1447 { 1448 return $this->getStringArray("getSelectedIndexes", array($selectLocator)); 1449 } 1450 1451 1452 /** 1453 * Gets option index (option number, starting at 0) for selected option in the specified select element. 1454 * 1455 * @access public 1456 * @param string $selectLocator an element locator identifying a drop-down menu 1457 * @return string the selected option index in the specified select drop-down 1458 */ 1459 public function getSelectedIndex($selectLocator) 1460 { 1461 return $this->getString("getSelectedIndex", array($selectLocator)); 1462 } 1463 1464 1465 /** 1466 * Gets all option element IDs for selected options in the specified select or multi-select element. 1467 * 1468 * @access public 1469 * @param string $selectLocator an element locator identifying a drop-down menu 1470 * @return array an array of all selected option IDs in the specified select drop-down 1471 */ 1472 public function getSelectedIds($selectLocator) 1473 { 1474 return $this->getStringArray("getSelectedIds", array($selectLocator)); 1475 } 1476 1477 1478 /** 1479 * Gets option element ID for selected option in the specified select element. 1480 * 1481 * @access public 1482 * @param string $selectLocator an element locator identifying a drop-down menu 1483 * @return string the selected option ID in the specified select drop-down 1484 */ 1485 public function getSelectedId($selectLocator) 1486 { 1487 return $this->getString("getSelectedId", array($selectLocator)); 1488 } 1489 1490 1491 /** 1492 * Determines whether some option in a drop-down menu is selected. 1493 * 1494 * @access public 1495 * @param string $selectLocator an element locator identifying a drop-down menu 1496 * @return boolean true if some option has been selected, false otherwise 1497 */ 1498 public function isSomethingSelected($selectLocator) 1499 { 1500 return $this->getBoolean("isSomethingSelected", array($selectLocator)); 1501 } 1502 1503 1504 /** 1505 * Gets all option labels in the specified select drop-down. 1506 * 1507 * @access public 1508 * @param string $selectLocator an element locator identifying a drop-down menu 1509 * @return array an array of all option labels in the specified select drop-down 1510 */ 1511 public function getSelectOptions($selectLocator) 1512 { 1513 return $this->getStringArray("getSelectOptions", array($selectLocator)); 1514 } 1515 1516 1517 /** 1518 * Gets the value of an element attribute. 1519 * 1520 * @access public 1521 * @param string $attributeLocator an element locator followed by an @ sign and then the name of the attribute, e.g. "foo@bar" 1522 * @return string the value of the specified attribute 1523 */ 1524 public function getAttribute($attributeLocator) 1525 { 1526 return $this->getString("getAttribute", array($attributeLocator)); 1527 } 1528 1529 1530 /** 1531 * Verifies that the specified text pattern appears somewhere on the rendered page shown to the user. 1532 * 1533 * @access public 1534 * @param string $pattern a pattern to match with the text of the page 1535 * @return boolean true if the pattern matches the text, false otherwise 1536 */ 1537 public function isTextPresent($pattern) 1538 { 1539 return $this->getBoolean("isTextPresent", array($pattern)); 1540 } 1541 1542 1543 /** 1544 * Verifies that the specified element is somewhere on the page. 1545 * 1546 * @access public 1547 * @param string $locator an element locator 1548 * @return boolean true if the element is present, false otherwise 1549 */ 1550 public function isElementPresent($locator) 1551 { 1552 return $this->getBoolean("isElementPresent", array($locator)); 1553 } 1554 1555 1556 /** 1557 * Determines if the specified element is visible. An 1558 * element can be rendered invisible by setting the CSS "visibility" 1559 * property to "hidden", or the "display" property to "none", either for the 1560 * element itself or one if its ancestors. This method will fail if 1561 * the element is not present. 1562 * 1563 * @access public 1564 * @param string $locator an element locator 1565 * @return boolean true if the specified element is visible, false otherwise 1566 */ 1567 public function isVisible($locator) 1568 { 1569 return $this->getBoolean("isVisible", array($locator)); 1570 } 1571 1572 1573 /** 1574 * Determines whether the specified input element is editable, ie hasn't been disabled. 1575 * This method will fail if the specified element isn't an input element. 1576 * 1577 * @access public 1578 * @param string $locator an element locator 1579 * @return boolean true if the input element is editable, false otherwise 1580 */ 1581 public function isEditable($locator) 1582 { 1583 return $this->getBoolean("isEditable", array($locator)); 1584 } 1585 1586 1587 /** 1588 * Returns the IDs of all buttons on the page. 1589 * 1590 * <p> 1591 * If a given button has no ID, it will appear as "" in this array. 1592 * </p> 1593 * 1594 * @access public 1595 * @return array the IDs of all buttons on the page 1596 */ 1597 public function getAllButtons() 1598 { 1599 return $this->getStringArray("getAllButtons", array()); 1600 } 1601 1602 1603 /** 1604 * Returns the IDs of all links on the page. 1605 * 1606 * <p> 1607 * If a given link has no ID, it will appear as "" in this array. 1608 * </p> 1609 * 1610 * @access public 1611 * @return array the IDs of all links on the page 1612 */ 1613 public function getAllLinks() 1614 { 1615 return $this->getStringArray("getAllLinks", array()); 1616 } 1617 1618 1619 /** 1620 * Returns the IDs of all input fields on the page. 1621 * 1622 * <p> 1623 * If a given field has no ID, it will appear as "" in this array. 1624 * </p> 1625 * 1626 * @access public 1627 * @return array the IDs of all field on the page 1628 */ 1629 public function getAllFields() 1630 { 1631 return $this->getStringArray("getAllFields", array()); 1632 } 1633 1634 1635 /** 1636 * Returns every instance of some attribute from all known windows. 1637 * 1638 * @access public 1639 * @param string $attributeName name of an attribute on the windows 1640 * @return array the set of values of this attribute from all known windows. 1641 */ 1642 public function getAttributeFromAllWindows($attributeName) 1643 { 1644 return $this->getStringArray("getAttributeFromAllWindows", array($attributeName)); 1645 } 1646 1647 1648 /** 1649 * deprecated - use dragAndDrop instead 1650 * 1651 * @access public 1652 * @param string $locator an element locator 1653 * @param string $movementsString offset in pixels from the current location to which the element should be moved, e.g., "+70,-300" 1654 */ 1655 public function dragdrop($locator, $movementsString) 1656 { 1657 $this->doCommand("dragdrop", array($locator, $movementsString)); 1658 } 1659 1660 1661 /** 1662 * Configure the number of pixels between "mousemove" events during dragAndDrop commands (default=10). 1663 * <p> 1664 * Setting this value to 0 means that we'll send a "mousemove" event to every single pixel 1665 * in between the start location and the end location; that can be very slow, and may 1666 * cause some browsers to force the JavaScript to timeout. 1667 * </p><p> 1668 * If the mouse speed is greater than the distance between the two dragged objects, we'll 1669 * just send one "mousemove" at the start location and then one final one at the end location. 1670 * </p> 1671 * 1672 * @access public 1673 * @param string $pixels the number of pixels between "mousemove" events 1674 */ 1675 public function setMouseSpeed($pixels) 1676 { 1677 $this->doCommand("setMouseSpeed", array($pixels)); 1678 } 1679 1680 1681 /** 1682 * Returns the number of pixels between "mousemove" events during dragAndDrop commands (default=10). 1683 * 1684 * @access public 1685 * @return number the number of pixels between "mousemove" events during dragAndDrop commands (default=10) 1686 */ 1687 public function getMouseSpeed() 1688 { 1689 return $this->getNumber("getMouseSpeed", array()); 1690 } 1691 1692 1693 /** 1694 * Drags an element a certain distance and then drops it 1695 * 1696 * @access public 1697 * @param string $locator an element locator 1698 * @param string $movementsString offset in pixels from the current location to which the element should be moved, e.g., "+70,-300" 1699 */ 1700 public function dragAndDrop($locator, $movementsString) 1701 { 1702 $this->doCommand("dragAndDrop", array($locator, $movementsString)); 1703 } 1704 1705 1706 /** 1707 * Drags an element and drops it on another element 1708 * 1709 * @access public 1710 * @param string $locatorOfObjectToBeDragged an element to be dragged 1711 * @param string $locatorOfDragDestinationObject an element whose location (i.e., whose center-most pixel) will be the point where locatorOfObjectToBeDragged is dropped 1712 */ 1713 public function dragAndDropToObject($locatorOfObjectToBeDragged, $locatorOfDragDestinationObject) 1714 { 1715 $this->doCommand("dragAndDropToObject", array($locatorOfObjectToBeDragged, $locatorOfDragDestinationObject)); 1716 } 1717 1718 1719 /** 1720 * Gives focus to the currently selected window 1721 * 1722 * @access public 1723 */ 1724 public function windowFocus() 1725 { 1726 $this->doCommand("windowFocus", array()); 1727 } 1728 1729 1730 /** 1731 * Resize currently selected window to take up the entire screen 1732 * 1733 * @access public 1734 */ 1735 public function windowMaximize() 1736 { 1737 $this->doCommand("windowMaximize", array()); 1738 } 1739 1740 1741 /** 1742 * Returns the IDs of all windows that the browser knows about. 1743 * 1744 * @access public 1745 * @return array the IDs of all windows that the browser knows about. 1746 */ 1747 public function getAllWindowIds() 1748 { 1749 return $this->getStringArray("getAllWindowIds", array()); 1750 } 1751 1752 1753 /** 1754 * Returns the names of all windows that the browser knows about. 1755 * 1756 * @access public 1757 * @return array the names of all windows that the browser knows about. 1758 */ 1759 public function getAllWindowNames() 1760 { 1761 return $this->getStringArray("getAllWindowNames", array()); 1762 } 1763 1764 1765 /** 1766 * Returns the titles of all windows that the browser knows about. 1767 * 1768 * @access public 1769 * @return array the titles of all windows that the browser knows about. 1770 */ 1771 public function getAllWindowTitles() 1772 { 1773 return $this->getStringArray("getAllWindowTitles", array()); 1774 } 1775 1776 1777 /** 1778 * Returns the entire HTML source between the opening and 1779 * closing "html" tags. 1780 * 1781 * @access public 1782 * @return string the entire HTML source 1783 */ 1784 public function getHtmlSource() 1785 { 1786 return $this->getString("getHtmlSource", array()); 1787 } 1788 1789 1790 /** 1791 * Moves the text cursor to the specified position in the given input element or textarea. 1792 * This method will fail if the specified element isn't an input element or textarea. 1793 * 1794 * @access public 1795 * @param string $locator an element locator pointing to an input element or textarea 1796 * @param string $position the numerical position of the cursor in the field; position should be 0 to move the position to the beginning of the field. You can also set the cursor to -1 to move it to the end of the field. 1797 */ 1798 public function setCursorPosition($locator, $position) 1799 { 1800 $this->doCommand("setCursorPosition", array($locator, $position)); 1801 } 1802 1803 1804 /** 1805 * Get the relative index of an element to its parent (starting from 0). The comment node and empty text node 1806 * will be ignored. 1807 * 1808 * @access public 1809 * @param string $locator an element locator pointing to an element 1810 * @return number of relative index of the element to its parent (starting from 0) 1811 */ 1812 public function getElementIndex($locator) 1813 { 1814 return $this->getNumber("getElementIndex", array($locator)); 1815 } 1816 1817 1818 /** 1819 * Check if these two elements have same parent and are ordered siblings in the DOM. Two same elements will 1820 * not be considered ordered. 1821 * 1822 * @access public 1823 * @param string $locator1 an element locator pointing to the first element 1824 * @param string $locator2 an element locator pointing to the second element 1825 * @return boolean true if element1 is the previous sibling of element2, false otherwise 1826 */ 1827 public function isOrdered($locator1, $locator2) 1828 { 1829 return $this->getBoolean("isOrdered", array($locator1, $locator2)); 1830 } 1831 1832 1833 /** 1834 * Retrieves the horizontal position of an element 1835 * 1836 * @access public 1837 * @param string $locator an element locator pointing to an element OR an element itself 1838 * @return number of pixels from the edge of the frame. 1839 */ 1840 public function getElementPositionLeft($locator) 1841 { 1842 return $this->getNumber("getElementPositionLeft", array($locator)); 1843 } 1844 1845 1846 /** 1847 * Retrieves the vertical position of an element 1848 * 1849 * @access public 1850 * @param string $locator an element locator pointing to an element OR an element itself 1851 * @return number of pixels from the edge of the frame. 1852 */ 1853 public function getElementPositionTop($locator) 1854 { 1855 return $this->getNumber("getElementPositionTop", array($locator)); 1856 } 1857 1858 1859 /** 1860 * Retrieves the width of an element 1861 * 1862 * @access public 1863 * @param string $locator an element locator pointing to an element 1864 * @return number width of an element in pixels 1865 */ 1866 public function getElementWidth($locator) 1867 { 1868 return $this->getNumber("getElementWidth", array($locator)); 1869 } 1870 1871 1872 /** 1873 * Retrieves the height of an element 1874 * 1875 * @access public 1876 * @param string $locator an element locator pointing to an element 1877 * @return number height of an element in pixels 1878 */ 1879 public function getElementHeight($locator) 1880 { 1881 return $this->getNumber("getElementHeight", array($locator)); 1882 } 1883 1884 1885 /** 1886 * Retrieves the text cursor position in the given input element or textarea; beware, this may not work perfectly on all browsers. 1887 * 1888 * <p> 1889 * Specifically, if the cursor/selection has been cleared by JavaScript, this command will tend to 1890 * return the position of the last location of the cursor, even though the cursor is now gone from the page. This is filed as SEL-243. 1891 * </p> 1892 * This method will fail if the specified element isn't an input element or textarea, or there is no cursor in the element. 1893 * 1894 * @access public 1895 * @param string $locator an element locator pointing to an input element or textarea 1896 * @return number the numerical position of the cursor in the field 1897 */ 1898 public function getCursorPosition($locator) 1899 { 1900 return $this->getNumber("getCursorPosition", array($locator)); 1901 } 1902 1903 1904 /** 1905 * Returns the specified expression. 1906 * 1907 * <p> 1908 * This is useful because of JavaScript preprocessing. 1909 * It is used to generate commands like assertExpression and waitForExpression. 1910 * </p> 1911 * 1912 * @access public 1913 * @param string $expression the value to return 1914 * @return string the value passed in 1915 */ 1916 public function getExpression($expression) 1917 { 1918 return $this->getString("getExpression", array($expression)); 1919 } 1920 1921 1922 /** 1923 * Returns the number of nodes that match the specified xpath, eg. "//table" would give 1924 * the number of tables. 1925 * 1926 * @access public 1927 * @param string $xpath the xpath expression to evaluate. do NOT wrap this expression in a 'count()' function; we will do that for you. 1928 * @return number the number of nodes that match the specified xpath 1929 */ 1930 public function getXpathCount($xpath) 1931 { 1932 return $this->getNumber("getXpathCount", array($xpath)); 1933 } 1934 1935 1936 /** 1937 * Temporarily sets the "id" attribute of the specified element, so you can locate it in the future 1938 * using its ID rather than a slow/complicated XPath. This ID will disappear once the page is 1939 * reloaded. 1940 * 1941 * @access public 1942 * @param string $locator an element locator pointing to an element 1943 * @param string $identifier a string to be used as the ID of the specified element 1944 */ 1945 public function assignId($locator, $identifier) 1946 { 1947 $this->doCommand("assignId", array($locator, $identifier)); 1948 } 1949 1950 1951 /** 1952 * Specifies whether Selenium should use the native in-browser implementation 1953 * of XPath (if any native version is available); if you pass "false" to 1954 * this function, we will always use our pure-JavaScript xpath library. 1955 * Using the pure-JS xpath library can improve the consistency of xpath 1956 * element locators between different browser vendors, but the pure-JS 1957 * version is much slower than the native implementations. 1958 * 1959 * @access public 1960 * @param string $allow boolean, true means we'll prefer to use native XPath; false means we'll only use JS XPath 1961 */ 1962 public function allowNativeXpath($allow) 1963 { 1964 $this->doCommand("allowNativeXpath", array($allow)); 1965 } 1966 1967 1968 /** 1969 * Runs the specified JavaScript snippet repeatedly until it evaluates to "true". 1970 * The snippet may have multiple lines, but only the result of the last line 1971 * will be considered. 1972 * 1973 * <p> 1974 * Note that, by default, the snippet will be run in the runner's test window, not in the window 1975 * of your application. To get the window of your application, you can use 1976 * the JavaScript snippet <code>selenium.browserbot.getCurrentWindow()</code>, and then 1977 * run your JavaScript in there 1978 * </p> 1979 * 1980 * @access public 1981 * @param string $script the JavaScript snippet to run 1982 * @param string $timeout a timeout in milliseconds, after which this command will return with an error 1983 */ 1984 public function waitForCondition($script, $timeout) 1985 { 1986 $this->doCommand("waitForCondition", array($script, $timeout)); 1987 } 1988 1989 1990 /** 1991 * Specifies the amount of time that Selenium will wait for actions to complete. 1992 * 1993 * <p> 1994 * Actions that require waiting include "open" and the "waitFor*" actions. 1995 * </p> 1996 * The default timeout is 30 seconds. 1997 * 1998 * @access public 1999 * @param string $timeout a timeout in milliseconds, after which the action will return with an error 2000 */ 2001 public function setTimeout($timeout) 2002 { 2003 $this->doCommand("setTimeout", array($timeout)); 2004 } 2005 2006 2007 /** 2008 * Waits for a new page to load. 2009 * 2010 * <p> 2011 * You can use this command instead of the "AndWait" suffixes, "clickAndWait", "selectAndWait", "typeAndWait" etc. 2012 * (which are only available in the JS API). 2013 * </p><p> 2014 * Selenium constantly keeps track of new pages loading, and sets a "newPageLoaded" 2015 * flag when it first notices a page load. Running any other Selenium command after 2016 * turns the flag to false. Hence, if you want to wait for a page to load, you must 2017 * wait immediately after a Selenium command that caused a page-load. 2018 * </p> 2019 * 2020 * @access public 2021 * @param string $timeout a timeout in milliseconds, after which this command will return with an error 2022 */ 2023 public function waitForPageToLoad($timeout) 2024 { 2025 $this->doCommand("waitForPageToLoad", array($timeout)); 2026 } 2027 2028 2029 /** 2030 * Waits for a new frame to load. 2031 * 2032 * <p> 2033 * Selenium constantly keeps track of new pages and frames loading, 2034 * and sets a "newPageLoaded" flag when it first notices a page load. 2035 * </p> 2036 * 2037 * See waitForPageToLoad for more information. 2038 * 2039 * @access public 2040 * @param string $frameAddress FrameAddress from the server side 2041 * @param string $timeout a timeout in milliseconds, after which this command will return with an error 2042 */ 2043 public function waitForFrameToLoad($frameAddress, $timeout) 2044 { 2045 $this->doCommand("waitForFrameToLoad", array($frameAddress, $timeout)); 2046 } 2047 2048 2049 /** 2050 * Return all cookies of the current page under test. 2051 * 2052 * @access public 2053 * @return string all cookies of the current page under test 2054 */ 2055 public function getCookie() 2056 { 2057 return $this->getString("getCookie", array()); 2058 } 2059 2060 2061 /** 2062 * Create a new cookie whose path and domain are same with those of current page 2063 * under test, unless you specified a path for this cookie explicitly. 2064 * 2065 * @access public 2066 * @param string $nameValuePair name and value of the cookie in a format "name=value" 2067 * @param string $optionsString options for the cookie. Currently supported options include 'path' and 'max_age'. the optionsString's format is "path=/path/, max_age=60". The order of options are irrelevant, the unit of the value of 'max_age' is second. 2068 */ 2069 public function createCookie($nameValuePair, $optionsString) 2070 { 2071 $this->doCommand("createCookie", array($nameValuePair, $optionsString)); 2072 } 2073 2074 2075 /** 2076 * Delete a named cookie with specified path. 2077 * 2078 * @access public 2079 * @param string $name the name of the cookie to be deleted 2080 * @param string $path the path property of the cookie to be deleted 2081 */ 2082 public function deleteCookie($name, $path) 2083 { 2084 $this->doCommand("deleteCookie", array($name, $path)); 2085 } 2086 2087 2088 /** 2089 * Sets the threshold for browser-side logging messages; log messages beneath this threshold will be discarded. 2090 * Valid logLevel strings are: "debug", "info", "warn", "error" or "off". 2091 * To see the browser logs, you need to 2092 * either show the log window in GUI mode, or enable browser-side logging in Selenium RC. 2093 * 2094 * @access public 2095 * @param string $logLevel one of the following: "debug", "info", "warn", "error" or "off" 2096 */ 2097 public function setBrowserLogLevel($logLevel) 2098 { 2099 $this->doCommand("setBrowserLogLevel", array($logLevel)); 2100 } 2101 2102 2103 /** 2104 * Creates a new "script" tag in the body of the current test window, and 2105 * adds the specified text into the body of the command. Scripts run in 2106 * this way can often be debugged more easily than scripts executed using 2107 * Selenium's "getEval" command. Beware that JS exceptions thrown in these script 2108 * tags aren't managed by Selenium, so you should probably wrap your script 2109 * in try/catch blocks if there is any chance that the script will throw 2110 * an exception. 2111 * 2112 * @access public 2113 * @param string $script the JavaScript snippet to run 2114 */ 2115 public function runScript($script) 2116 { 2117 $this->doCommand("runScript", array($script)); 2118 } 2119 2120 2121 /** 2122 * Defines a new function for Selenium to locate elements on the page. 2123 * For example, 2124 * if you define the strategy "foo", and someone runs click("foo=blah"), we'll 2125 * run your function, passing you the string "blah", and click on the element 2126 * that your function 2127 * returns, or throw an "Element not found" error if your function returns null. 2128 * 2129 * We'll pass three arguments to your function: 2130 * 2131 * <ul> 2132 * 2133 * <li> 2134 * locator: the string the user passed in 2135 * </li> 2136 * <li> 2137 * inWindow: the currently selected window 2138 * </li> 2139 * <li> 2140 * inDocument: the currently selected document 2141 * </li> 2142 * </ul> 2143 * The function must return null if the element can't be found. 2144 * 2145 * @access public 2146 * @param string $strategyName the name of the strategy to define; this should use only letters [a-zA-Z] with no spaces or other punctuation. 2147 * @param string $functionDefinition a string defining the body of a function in JavaScript. For example: <code>return inDocument.getElementById(locator);</code> 2148 */ 2149 public function addLocationStrategy($strategyName, $functionDefinition) 2150 { 2151 $this->doCommand("addLocationStrategy", array($strategyName, $functionDefinition)); 2152 } 2153 2154 2155 /** 2156 * Writes a message to the status bar and adds a note to the browser-side 2157 * log. 2158 * 2159 * @access public 2160 * @param string $context the message to be sent to the browser 2161 */ 2162 public function setContext($context) 2163 { 2164 $this->doCommand("setContext", array($context)); 2165 } 2166 2167 2168 /** 2169 * Captures a PNG screenshot to the specified file. 2170 * 2171 * @access public 2172 * @param string $filename the absolute path to the file to be written, e.g. "c:\blah\screenshot.png" 2173 */ 2174 public function captureScreenshot($filename) 2175 { 2176 $this->doCommand("captureScreenshot", array($filename)); 2177 } 2178 2179 2180 protected function doCommand($verb, $args = array()) 2181 { 2182 $url = sprintf('http://%s:%s/selenium-server/driver/?cmd=%s', $this->host, $this->port, urlencode($verb)); 2183 for ($i = 0; $i < count($args); $i++) { 2184 $argNum = strval($i + 1); 2185 $url .= sprintf('&%s=%s', $argNum, urlencode(trim($args[$i]))); 2186 } 2187 2188 if (isset($this->sessionId)) { 2189 $url .= sprintf('&%s=%s', 'sessionId', $this->sessionId); 2190 } 2191 2192 if (!$handle = fopen($url, 'r')) { 2193 throw new Testing_Selenium_Exception('Cannot connected to Selenium RC Server'); 2194 } 2195 2196 stream_set_blocking($handle, 1); 2197 $response = stream_get_contents($handle); 2198 fclose($handle); 2199 2200 if (!preg_match('/^OK/', $response)) { 2201 throw new Testing_Selenium_Exception('The Response of the Selenium RC is invalid: ' . $response); 2202 } 2203 2204 return $response; 2205 } 2206 2207 private function getString($verb, $args = array()) 2208 { 2209 try { 2210 $result = $this->doCommand($verb, $args); 2211 } catch (Testing_Selenium_Exception $e) { 2212 return $e; 2213 } 2214 return substr($result, 3); 2215 } 2216 2217 private function getStringArray($verb, $args = array()) 2218 { 2219 $csv = $this->getString($verb, $args); 2220 $token = ''; 2221 $tokens = array(); 2222 $letters = preg_split('//', $csv, -1, PREG_SPLIT_NO_EMPTY); 2223 for ($i = 0; $i < count($letters); $i++) { 2224 $letter = $letters[$i]; 2225 switch($letter) { 2226 case '\\': 2227 $i++; 2228 $letter = $letters[$i]; 2229 $token = $token . $letter; 2230 break; 2231 case ',': 2232 array_push($tokens, $token); 2233 $token = ''; 2234 break; 2235 default: 2236 $token = $token . $letter; 2237 break; 2238 } 2239 } 2240 array_push($tokens, $token); 2241 return $tokens; 2242 } 2243 2244 private function getBoolean($verb, $args = array()) 2245 { 2246 $result = $this->getString($verb, $args); 2247 switch ($result) { 2248 case 'true': 2249 return true; 2250 case 'false': 2251 return false; 2252 default: 2253 throw new Testing_Selenium_Exception('result is neither "true" or "false": ' . $result); 2254 } 2255 } 2256} 2257?> 2258