1WWW::Selenium(3) User Contributed Perl Documentation WWW::Selenium(3)
2
6 WWW::Selenium - Perl Client for the Selenium Remote Control test tool
7
9 use WWW::Selenium;
10 my $sel = WWW::Selenium->new( host => "localhost",
12 port => 4444,
13 browser => "*iexplore",
14 browser_url => "http://www.google.com",
15 );
16 $sel->start;
18 $sel->open("http://www.google.com");
19 $sel->type("q", "hello world");
20 $sel->click("btnG");
21 $sel->wait_for_page_to_load(5000);
22 print $sel->get_title;
23 $sel->stop;
24
26 Selenium Remote Control (SRC) is a test tool that allows you to write
27 automated web application UI tests in any programming language against
28 any HTTP website using any mainstream JavaScript-enabled browser. SRC
29 provides a Selenium Server, which can automatically start/stop/control
30 any supported browser. It works by using Selenium Core, a pure-HTML+JS
31 library that performs automated tasks in JavaScript; the Selenium
32 Server communicates directly with the browser using AJAX
33 (XmlHttpRequest).
34 http://www.openqa.org/selenium-rc/ <http://www.openqa.org/selenium-rc/>
36 This module sends commands directly to the Server using simple HTTP
38 GET/POST requests. Using this module together with the Selenium
39 Server, you can automatically control any supported browser.
40 To use this module, you need to have already downloaded and started the
42 Selenium Server. (The Selenium Server is a Java application.)
43 Element Locators
45 Element Locators tell Selenium which HTML element a command refers
47 to.The format of a locator is:
48 locatorType=argument
50 We support the following strategies for locating elements:
52 · identifier=id: Select the element with the specified @id attribute.
54 If no match isfound, select the first element whose @name attribute
55 is id.(This is normally the default; see below.)
56 · id=id:Select the element with the specified @id attribute.
58 · name=name:Select the first element with the specified @name
60 attribute.
61 · username
63 · name=username
65 The name may optionally be followed by one or more element-filters,
67 separated from the name by whitespace. If the filterType is not
68 specified, value is assumed.
69 · name=flavour value=chocolate
71 · dom=javascriptExpression: Find an element by evaluating the
73 specified string. This allows you to traverse the HTML Document
74 ObjectModel using JavaScript. Note that you must not return a
75 value in this string; simply make it the last expression in the
76 block.
77 · dom=document.forms['myForm'].myDropdown
79 · dom=document.images[56]
81 · dom=function foo() { return document.links[1]; }; foo();
83 · xpath=xpathExpression: Locate an element using an XPath expression.
85 · xpath=//img[@alt='The image alt text']
87 · xpath=//table[@id='table1']//tr[4]/td[2]
89 · xpath=//a[contains(@href,'#id1')]
91 · xpath=//a[contains(@href,'#id1')]/@class
93 · xpath=(//table[@class='stylee'])//th[text()='theHeaderText']/../td
95 · xpath=//input[@name='name2' and @value='yes']
97 · xpath=//*[text()="right"]
99 · link=textPattern:Select the link (anchor) element which contains
101 text matching thespecified pattern.
102 · link=The link text
104 · css=cssSelectorSyntax:Select the element using css selectors.
106 Please refer to http://www.w3.org/TR/REC-CSS2/selector.html (CSS2
107 selectors), http://www.w3.org/TR/2001/CR-css3-selectors-20011113/
108 (CSS3 selectors) for more information. You can also check the
109 TestCssLocators test in the selenium test suite for an example of
110 usage, which is included in the downloaded selenium core package.
111 · css=a[href="#id3"]
113 · css=span#firstChild + span
115 Currently the css selector locator supports all css1, css2 and css3
117 selectors except namespace in css3, some pseudo
118 classes(:nth-of-type, :nth-last-of-type, :first-of-type,
119 :last-of-type, :only-of-type, :visited, :hover, :active, :focus,
120 :indeterminate) and pseudo elements(::first-line, ::first-letter,
121 ::selection, ::before, ::after).
122 · ui=uiSpecifierString:Locate an element by resolving the UI
124 specifier string to another locator, and evaluating it. See the
125 http://svn.openqa.org/fisheye/browse/~raw,r=trunk/selenium/trunk/src/main/resources/core/scripts/ui-doc.html
126 (Selenium UI-Element Reference) for more details.
127 · ui=loginPages::loginButton()
129 · ui=settingsPages::toggle(label=Hide Email)
131 · ui=forumPages::postBody(index=2)//a[2]
133 Without an explicit locator prefix, Selenium uses the following
135 defaultstrategies:
136 · dom, for locators starting with "document."
138 · xpath, for locators starting with "//"
140 · identifier, otherwise
142 Element Filters
144 Element filters can be used with a locator to refine a list of
146 candidate elements. They are currently used only in the 'name'
147 element-locator.
148 Filters look much like locators, ie.
150 filterType=argument
152 Supported element-filters are:
154 value=valuePattern
156 Matches elements based on their values. This is particularly
158 useful for refining a list of similarly-named toggle-buttons.
159 index=index
161 Selects a single element based on its position in the list (offset
163 from zero).
164 String-match Patterns
166 Various Pattern syntaxes are available for matching string values:
168 · glob:pattern:Match a string against a "glob" (aka "wildmat")
170 pattern. "Glob" is akind of limited regular-expression syntax
171 typically used in command-lineshells. In a glob pattern, "*"
172 represents any sequence of characters, and "?"represents any single
173 character. Glob patterns match against the entirestring.
174 · regexp:regexp:Match a string using a regular-expression. The full
176 power of JavaScriptregular-expressions is available.
177 · regexpi:regexpi:Match a string using a case-insensitive regular-
179 expression.
180 · exact:string:Match a string exactly, verbatim, without any of that
182 fancy wildcardstuff.
183 If no pattern prefix is specified, Selenium assumes that it's a
185 "glob"pattern.
186 For commands that return multiple values (such as
188 verifySelectOptions),the string being matched is a comma-separated list
189 of the return values,where both commas and backslashes in the values
190 are backslash-escaped.When providing a pattern, the optional matching
191 syntax (i.e. glob,regexp, etc.) is specified once, as usual, at the
192 beginning of thepattern.
193 METHODS
195 The following methods are available:
196 $sel = WWW::Selenium->new( %args )
198 Constructs a new "WWW::Selenium" object, specifying a Selenium
199 Server host/port, a command to launch the browser, and a starting
200 URL for the browser.
201 Options:
203 · "host"
205 host is the host name on which the Selenium Server resides.
207 · "port"
209 port is the port on which the Selenium Server is listening.
211 · "browser_url"
213 browser_url is the starting URL including just a domain name.
215 We'll start the browser pointing at the Selenium resources on
216 this URL, e.g. "http://www.google.com" would send the browser
217 to "http://www.google.com/selenium-server/SeleneseRunner.html"
218 · "browser" or "browser_start_command"
220 This is the command string used to launch the browser, e.g.
222 "*firefox", "*iexplore" or "/usr/bin/firefox"
223 This option may be any one of the following:
225 · "*firefox [absolute path]"
227 Automatically launch a new Firefox process using a custom
229 Firefox profile. This profile will be automatically
230 configured to use the Selenium Server as a proxy and to
231 have all annoying prompts ("save your password?" "forms are
232 insecure" "make Firefox your default browser?" disabled.
233 You may optionally specify an absolute path to your firefox
234 executable, or just say "*firefox". If no absolute path is
235 specified, we'll look for firefox.exe in a default location
236 (normally c:\program files\mozilla firefox\firefox.exe),
237 which you can override by setting the Java system property
238 "firefoxDefaultPath" to the correct path to Firefox.
239 · "*iexplore [absolute path]"
241 Automatically launch a new Internet Explorer process using
243 custom Windows registry settings. This process will be
244 automatically configured to use the Selenium Server as a
245 proxy and to have all annoying prompts ("save your
246 password?" "forms are insecure" "make Firefox your default
247 browser?" disabled. You may optionally specify an absolute
248 path to your iexplore executable, or just say "*iexplore".
249 If no absolute path is specified, we'll look for
250 iexplore.exe in a default location (normally c:\program
251 files\internet explorer\iexplore.exe), which you can
252 override by setting the Java system property
253 "iexploreDefaultPath" to the correct path to Internet
254 Explorer.
255 · "/path/to/my/browser [other arguments]"
257 You may also simply specify the absolute path to your
259 browser executable, or use a relative path to your
260 executable (which we'll try to find on your path).
261 Warning: If you specify your own custom browser, it's up to
262 you to configure it correctly. At a minimum, you'll need
263 to configure your browser to use the Selenium Server as a
264 proxy, and disable all browser-specific prompting.
265 · "auto_stop"
267 Defaults to true, and will attempt to close the browser if the
269 object goes out of scope and stop hasn't been called.
270 · "keep_alive"
272 Number of connections LWP should cache. This is just a minor
274 speed improvement. Defaults to 5.
275 $sel->pause($timeout)
277 Waits $timeout milliseconds (default: 1 second)
278 $sel->click($locator)
280 Clicks on a link, button, checkbox or radio button. If the click
281 actioncauses a new page to load (like a link usually does),
282 callwaitForPageToLoad.
283 $locator is an element locator
285 $sel->double_click($locator)
287 Double clicks on a link, button, checkbox or radio button. If the
288 double click actioncauses a new page to load (like a link usually
289 does), callwaitForPageToLoad.
290 $locator is an element locator
292 $sel->context_menu($locator)
294 Simulates opening the context menu for the specified element (as
295 might happen if the user "right-clicked" on the element).
296 $locator is an element locator
298 $sel->click_at($locator, $coord_string)
300 Clicks on a link, button, checkbox or radio button. If the click
301 actioncauses a new page to load (like a link usually does),
302 callwaitForPageToLoad.
303 $locator is an element locator
305 $coord_string is specifies the x,y position (i.e. - 10,20) of
307 the mouse event relative to the element returned by the
308 locator.
309 $sel->double_click_at($locator, $coord_string)
311 Doubleclicks on a link, button, checkbox or radio button. If the
312 actioncauses a new page to load (like a link usually does),
313 callwaitForPageToLoad.
314 $locator is an element locator
316 $coord_string is specifies the x,y position (i.e. - 10,20) of
318 the mouse event relative to the element returned by the
319 locator.
320 $sel->context_menu_at($locator, $coord_string)
322 Simulates opening the context menu for the specified element (as
323 might happen if the user "right-clicked" on the element).
324 $locator is an element locator
326 $coord_string is specifies the x,y position (i.e. - 10,20) of
328 the mouse event relative to the element returned by the
329 locator.
330 $sel->fire_event($locator, $event_name)
332 Explicitly simulate an event, to trigger the corresponding
333 "onevent"handler.
334 $locator is an element locator
336 $event_name is the event name, e.g. "focus" or "blur"
338 $sel->focus($locator)
340 Move the focus to the specified element; for example, if the
341 element is an input field, move the cursor to that field.
342 $locator is an element locator
344 $sel->key_press($locator, $key_sequence)
346 Simulates a user pressing and releasing a key.
347 $locator is an element locator
349 $key_sequence is Either be a string("\" followed by the numeric
351 keycode of the key to be pressed, normally the ASCII value of
352 that key), or a single character. For example: "w", "\119".
353 $sel->shift_key_down()
355 Press the shift key and hold it down until doShiftUp() is called or
356 a new page is loaded.
357 $sel->shift_key_up()
359 Release the shift key.
360 $sel->meta_key_down()
362 Press the meta key and hold it down until doMetaUp() is called or a
363 new page is loaded.
364 $sel->meta_key_up()
366 Release the meta key.
367 $sel->alt_key_down()
369 Press the alt key and hold it down until doAltUp() is called or a
370 new page is loaded.
371 $sel->alt_key_up()
373 Release the alt key.
374 $sel->control_key_down()
376 Press the control key and hold it down until doControlUp() is
377 called or a new page is loaded.
378 $sel->control_key_up()
380 Release the control key.
381 $sel->key_down($locator, $key_sequence)
383 Simulates a user pressing a key (without releasing it yet).
384 $locator is an element locator
386 $key_sequence is Either be a string("\" followed by the numeric
388 keycode of the key to be pressed, normally the ASCII value of
389 that key), or a single character. For example: "w", "\119".
390 $sel->key_up($locator, $key_sequence)
392 Simulates a user releasing a key.
393 $locator is an element locator
395 $key_sequence is Either be a string("\" followed by the numeric
397 keycode of the key to be pressed, normally the ASCII value of
398 that key), or a single character. For example: "w", "\119".
399 $sel->mouse_over($locator)
401 Simulates a user hovering a mouse over the specified element.
402 $locator is an element locator
404 $sel->mouse_out($locator)
406 Simulates a user moving the mouse pointer away from the specified
407 element.
408 $locator is an element locator
410 $sel->mouse_down($locator)
412 Simulates a user pressing the left mouse button (without releasing
413 it yet) onthe specified element.
414 $locator is an element locator
416 $sel->mouse_down_right($locator)
418 Simulates a user pressing the right mouse button (without releasing
419 it yet) onthe specified element.
420 $locator is an element locator
422 $sel->mouse_down_at($locator, $coord_string)
424 Simulates a user pressing the left mouse button (without releasing
425 it yet) atthe specified location.
426 $locator is an element locator
428 $coord_string is specifies the x,y position (i.e. - 10,20) of
430 the mouse event relative to the element returned by the
431 locator.
432 $sel->mouse_down_right_at($locator, $coord_string)
434 Simulates a user pressing the right mouse button (without releasing
435 it yet) atthe specified location.
436 $locator is an element locator
438 $coord_string is specifies the x,y position (i.e. - 10,20) of
440 the mouse event relative to the element returned by the
441 locator.
442 $sel->mouse_up($locator)
444 Simulates the event that occurs when the user releases the mouse
445 button (i.e., stopsholding the button down) on the specified
446 element.
447 $locator is an element locator
449 $sel->mouse_up_right($locator)
451 Simulates the event that occurs when the user releases the right
452 mouse button (i.e., stopsholding the button down) on the specified
453 element.
454 $locator is an element locator
456 $sel->mouse_up_at($locator, $coord_string)
458 Simulates the event that occurs when the user releases the mouse
459 button (i.e., stopsholding the button down) at the specified
460 location.
461 $locator is an element locator
463 $coord_string is specifies the x,y position (i.e. - 10,20) of
465 the mouse event relative to the element returned by the
466 locator.
467 $sel->mouse_up_right_at($locator, $coord_string)
469 Simulates the event that occurs when the user releases the right
470 mouse button (i.e., stopsholding the button down) at the specified
471 location.
472 $locator is an element locator
474 $coord_string is specifies the x,y position (i.e. - 10,20) of
476 the mouse event relative to the element returned by the
477 locator.
478 $sel->mouse_move($locator)
480 Simulates a user pressing the mouse button (without releasing it
481 yet) onthe specified element.
482 $locator is an element locator
484 $sel->mouse_move_at($locator, $coord_string)
486 Simulates a user pressing the mouse button (without releasing it
487 yet) onthe specified element.
488 $locator is an element locator
490 $coord_string is specifies the x,y position (i.e. - 10,20) of
492 the mouse event relative to the element returned by the
493 locator.
494 $sel->type($locator, $value)
496 Sets the value of an input field, as though you typed it in. Can
497 also be used to set the value of combo boxes, check boxes, etc. In
498 these cases,value should be the value of the option selected, not
499 the visible text.
500 $locator is an element locator
502 $value is the value to type
504 $sel->type_keys($locator, $value)
506 Simulates keystroke events on the specified element, as though you
507 typed the value key-by-key. This is a convenience method for
508 calling keyDown, keyUp, keyPress for every character in the
509 specified string;this is useful for dynamic UI widgets (like auto-
510 completing combo boxes) that require explicit key events.
511 Unlike the simple "type" command, which forces the specified value
513 into the page directly, this commandmay or may not have any visible
514 effect, even in cases where typing keys would normally have a
515 visible effect.For example, if you use "typeKeys" on a form
516 element, you may or may not see the results of what you typed inthe
517 field.
518 In some cases, you may need to use the simple "type" command to set
520 the value of the field and then the "typeKeys" command tosend the
521 keystroke events corresponding to what you just typed.
522 $locator is an element locator
524 $value is the value to type
526 $sel->set_speed($value)
528 Set execution speed (i.e., set the millisecond length of a delay
529 which will follow each selenium operation). By default, there is
530 no such delay, i.e.,the delay is 0 milliseconds.
531 $value is the number of milliseconds to pause after operation
533 $sel->get_speed()
535 Get execution speed (i.e., get the millisecond length of the delay
536 following each selenium operation). By default, there is no such
537 delay, i.e.,the delay is 0 milliseconds.See also setSpeed.
538 Returns the execution speed in milliseconds.
540 $sel->check($locator)
542 Check a toggle-button (checkbox/radio)
543 $locator is an element locator
545 $sel->uncheck($locator)
547 Uncheck a toggle-button (checkbox/radio)
548 $locator is an element locator
550 $sel->select($select_locator, $option_locator)
552 Select an option from a drop-down using an option locator. Option
553 locators provide different ways of specifying options of an
554 HTMLSelect element (e.g. for selecting a specific option, or for
555 assertingthat the selected option satisfies a specification). There
556 are severalforms of Select Option Locator.
557 · label=labelPattern:matches options based on their labels, i.e.
559 the visible text. (Thisis the default.)
560 · label=regexp:^[Oo]ther
562 · value=valuePattern:matches options based on their values.
564 · value=other
566 · id=id:matches options based on their ids.
568 · id=option1
570 · index=index:matches an option based on its index (offset from
572 zero).
573 · index=2
575 If no option locator prefix is provided, the default behaviour is
577 to match on label.
578 $select_locator is an element locator identifying a drop-down
580 menu
581 $option_locator is an option locator (a label by default)
583 $sel->add_selection($locator, $option_locator)
585 Add a selection to the set of selected options in a multi-select
586 element using an option locator.@see #doSelect for details of
587 option locators
588 $locator is an element locator identifying a multi-select box
590 $option_locator is an option locator (a label by default)
592 $sel->remove_selection($locator, $option_locator)
594 Remove a selection from the set of selected options in a multi-
595 select element using an option locator.@see #doSelect for details
596 of option locators
597 $locator is an element locator identifying a multi-select box
599 $option_locator is an option locator (a label by default)
601 $sel->remove_all_selections($locator)
603 Unselects all of the selected options in a multi-select element.
604 $locator is an element locator identifying a multi-select box
606 $sel->submit($form_locator)
608 Submit the specified form. This is particularly useful for forms
609 withoutsubmit buttons, e.g. single-input "Search" forms.
610 $form_locator is an element locator for the form you want to
612 submit
613 $sel->open($url, $ignore_response_code)
615 Opens an URL in the test frame. This accepts both relative and
616 absoluteURLs.The "open" command waits for the page to load before
617 proceeding,ie. the "AndWait" suffix is implicit.Note: The URL must
618 be on the same domain as the runner HTMLdue to security
619 restrictions in the browser (Same Origin Policy). If youneed to
620 open an URL on another domain, use the Selenium Server to start
621 anew browser session on that domain.
622 $url is the URL to open; may be relative or absolute
624 $ignore_response_code is (optional) turn off ajax head request
626 functionality
627 $sel->open_window($url, $window_id)
629 Opens a popup window (if a window with that ID isn't already
630 open).After opening the window, you'll need to select it using the
631 selectWindowcommand. This command can also be a useful workaround
632 for bug SEL-339. In some cases, Selenium will be unable to
633 intercept a call to window.open (if the call occurs during or
634 before the "onLoad" event, for example).In those cases, you can
635 force Selenium to notice the open window's name by using the
636 Selenium openWindow command, usingan empty (blank) url, like this:
637 openWindow("", "myFunnyWindow").
638 $url is the URL to open, which can be blank
640 $window_id is the JavaScript window ID of the window to select
642 $sel->select_window($window_id)
644 Selects a popup window using a window locator; once a popup window
645 has been selected, allcommands go to that window. To select the
646 main window again, use nullas the target. Window locators provide
647 different ways of specifying the window object:by title, by
648 internal JavaScript "name," or by JavaScript variable.
649 · title=My Special Window:Finds the window using the text that
651 appears in the title bar. Be careful;two windows can share the
652 same title. If that happens, this locator willjust pick one.
653 · name=myWindow:Finds the window using its internal JavaScript
655 "name" property. This is the second parameter "windowName"
656 passed to the JavaScript method window.open(url, windowName,
657 windowFeatures, replaceFlag)(which Selenium intercepts).
658 · var=variableName:Some pop-up windows are unnamed (anonymous),
660 but are associated with a JavaScript variable name in the
661 currentapplication window, e.g. "window.foo =
662 window.open(url);". In those cases, you can open the window
663 using"var=foo".
664 If no window locator prefix is provided, we'll try to guess what
666 you mean like this:
667 1.) if windowID is null, (or the string "null") then it is assumed
669 the user is referring to the original window instantiated by the
670 browser).
671 2.) if the value of the "windowID" parameter is a JavaScript
673 variable name in the current application window, then it is
674 assumedthat this variable contains the return value from a call to
675 the JavaScript window.open() method.
676 3.) Otherwise, selenium looks in a hash it maintains that maps
678 string names to window "names".
679 4.) If that fails, we'll try looping over all of the known windows
681 to try to find the appropriate "title".Since "title" is not
682 necessarily unique, this may have unexpected behavior.
683 If you're having trouble figuring out the name of a window that you
685 want to manipulate, look at the Selenium log messageswhich identify
686 the names of windows created via window.open (and therefore
687 intercepted by Selenium). You will see messageslike the following
688 for each window as it is opened:
689 "debug: window.open call intercepted; window ID (which you can use
691 with selectWindow()) is "myNewWindow""
692 In some cases, Selenium will be unable to intercept a call to
694 window.open (if the call occurs during or before the "onLoad"
695 event, for example).(This is bug SEL-339.) In those cases, you can
696 force Selenium to notice the open window's name by using the
697 Selenium openWindow command, usingan empty (blank) url, like this:
698 openWindow("", "myFunnyWindow").
699 $window_id is the JavaScript window ID of the window to select
701 $sel->select_pop_up($window_id)
703 Simplifies the process of selecting a popup window (and does not
704 offerfunctionality beyond what "selectWindow()" already provides).
705 · If "windowID" is either not specified, or specified as"null",
707 the first non-top window is selected. The top window is the
708 onethat would be selected by "selectWindow()" without providing
709 a"windowID" . This should not be used when more than one
710 popupwindow is in play.
711 · Otherwise, the window will be looked up considering"windowID"
713 as the following in order: 1) the "name" of thewindow, as
714 specified to "window.open()"; 2) a javascriptvariable which is
715 a reference to a window; and 3) the title of thewindow. This is
716 the same ordered lookup performed by"selectWindow" .
717 $window_id is an identifier for the popup window, which can
719 take on a number of different meanings
720 $sel->deselect_pop_up()
722 Selects the main window. Functionally equivalent to
723 using"selectWindow()" and specifying no value for"windowID".
724 $sel->select_frame($locator)
726 Selects a frame within the current window. (You may invoke this
727 commandmultiple times to select nested frames.) To select the
728 parent frame, use"relative=parent" as a locator; to select the top
729 frame, use "relative=top".You can also select a frame by its
730 0-based index number; select the first frame with"index=0", or the
731 third frame with "index=2". You may also use a DOM expression to
732 identify the frame you want directly,like this:
733 "dom=frames["main"].frames["subframe"]"
734 $locator is an element locator identifying a frame or iframe
736 $sel->get_whether_this_frame_match_frame_expression($current_frame_string,
738 $target)
739 Determine whether current/locator identify the frame containing
740 this running code. This is useful in proxy injection mode, where
741 this code runs in everybrowser frame and window, and sometimes the
742 selenium server needs to identifythe "current" frame. In this
743 case, when the test calls selectFrame, thisroutine is called for
744 each frame to figure out which one has been selected.The selected
745 frame will return true, while all others will return false.
746 $current_frame_string is starting frame
748 $target is new frame (which might be relative to the current
750 one)
751 Returns true if the new frame is this code's window
753 $sel->get_whether_this_window_match_window_expression($current_window_string,
755 $target)
756 Determine whether currentWindowString plus target identify the
757 window containing this running code. This is useful in proxy
758 injection mode, where this code runs in everybrowser frame and
759 window, and sometimes the selenium server needs to identifythe
760 "current" window. In this case, when the test calls selectWindow,
761 thisroutine is called for each window to figure out which one has
762 been selected.The selected window will return true, while all
763 others will return false.
764 $current_window_string is starting window
766 $target is new window (which might be relative to the current
768 one, e.g., "_parent")
769 Returns true if the new window is this code's window
771 $sel->wait_for_pop_up($window_id, $timeout)
773 Waits for a popup window to appear and load up.
774 $window_id is the JavaScript window "name" of the window that
776 will appear (not the text of the title bar) If
777 unspecified, or specified as "null", this command will
778 wait for the first non-top window to appear (don't rely
779 on this if you are working with multiple popups
780 simultaneously).
781 $timeout is a timeout in milliseconds, after which the action
783 will return with an error. If this value is not
784 specified, the default Selenium timeout will be
785 used. See the setTimeout() command.
786 $sel->choose_cancel_on_next_confirmation()
788 By default, Selenium's overridden window.confirm() function
789 willreturn true, as if the user had manually clicked OK; after
790 runningthis command, the next call to confirm() will return false,
791 as ifthe user had clicked Cancel. Selenium will then resume using
792 thedefault behavior for future confirmations, automatically
793 returning true (OK) unless/until you explicitly call this command
794 for eachconfirmation.
795 Take note - every time a confirmation comes up, you mustconsume it
797 with a corresponding getConfirmation, or elsethe next selenium
798 operation will fail.
799 $sel->choose_ok_on_next_confirmation()
801 Undo the effect of calling chooseCancelOnNextConfirmation.
802 Notethat Selenium's overridden window.confirm() function will
803 normally automaticallyreturn true, as if the user had manually
804 clicked OK, so you shouldn'tneed to use this command unless for
805 some reason you need to changeyour mind prior to the next
806 confirmation. After any confirmation, Selenium will resume using
807 thedefault behavior for future confirmations, automatically
808 returning true (OK) unless/until you explicitly call
809 chooseCancelOnNextConfirmation for eachconfirmation.
810 Take note - every time a confirmation comes up, you mustconsume it
812 with a corresponding getConfirmation, or elsethe next selenium
813 operation will fail.
814 $sel->answer_on_next_prompt($answer)
816 Instructs Selenium to return the specified answer string in
817 response tothe next JavaScript prompt [window.prompt()].
818 $answer is the answer to give in response to the prompt pop-up
820 $sel->go_back()
822 Simulates the user clicking the "back" button on their browser.
823 $sel->refresh()
825 Simulates the user clicking the "Refresh" button on their browser.
826 $sel->close()
828 Simulates the user clicking the "close" button in the titlebar of a
829 popupwindow or tab.
830 $sel->is_alert_present()
832 Has an alert occurred? This function never throws an exception
833 Returns true if there is an alert
835 $sel->is_prompt_present()
837 Has a prompt occurred? This function never throws an exception
838 Returns true if there is a pending prompt
840 $sel->is_confirmation_present()
842 Has confirm() been called? This function never throws an exception
843 Returns true if there is a pending confirmation
845 $sel->get_alert()
847 Retrieves the message of a JavaScript alert generated during the
848 previous action, or fail if there were no alerts. Getting an alert
849 has the same effect as manually clicking OK. If analert is
850 generated but you do not consume it with getAlert, the next
851 Selenium actionwill fail.
852 Under Selenium, JavaScript alerts will NOT pop up a visible
854 alertdialog.
855 Selenium does NOT support JavaScript alerts that are generated in
857 apage's onload() event handler. In this case a visible dialog WILL
858 begenerated and Selenium will hang until someone manually clicks
859 OK.
860 Returns The message of the most recent JavaScript alert
862 $sel->get_confirmation()
864 Retrieves the message of a JavaScript confirmation dialog generated
865 duringthe previous action. By default, the confirm function will
866 return true, having the same effectas manually clicking OK. This
867 can be changed by prior execution of
868 thechooseCancelOnNextConfirmation command.
869 If an confirmation is generated but you do not consume it with
871 getConfirmation,the next Selenium action will fail.
872 NOTE: under Selenium, JavaScript confirmations will NOT pop up a
874 visibledialog.
875 NOTE: Selenium does NOT support JavaScript confirmations that
877 aregenerated in a page's onload() event handler. In this case a
878 visibledialog WILL be generated and Selenium will hang until you
879 manually clickOK.
880 Returns the message of the most recent JavaScript confirmation
882 dialog
883 $sel->get_prompt()
885 Retrieves the message of a JavaScript question prompt dialog
886 generated duringthe previous action. Successful handling of the
887 prompt requires prior execution of theanswerOnNextPrompt command.
888 If a prompt is generated but youdo not get/verify it, the next
889 Selenium action will fail.
890 NOTE: under Selenium, JavaScript prompts will NOT pop up a
892 visibledialog.
893 NOTE: Selenium does NOT support JavaScript prompts that are
895 generated in apage's onload() event handler. In this case a visible
896 dialog WILL begenerated and Selenium will hang until someone
897 manually clicks OK.
898 Returns the message of the most recent JavaScript question
900 prompt
901 $sel->get_location()
903 Gets the absolute URL of the current page.
904 Returns the absolute URL of the current page
906 $sel->get_title()
908 Gets the title of the current page.
909 Returns the title of the current page
911 $sel->get_body_text()
913 Gets the entire text of the page.
914 Returns the entire text of the page
916 $sel->get_value($locator)
918 Gets the (whitespace-trimmed) value of an input field (or anything
919 else with a value parameter).For checkbox/radio elements, the value
920 will be "on" or "off" depending onwhether the element is checked or
921 not.
922 $locator is an element locator
924 Returns the element value, or "on/off" for checkbox/radio
926 elements
927 $sel->get_text($locator)
929 Gets the text of an element. This works for any element that
930 containstext. This command uses either the textContent (Mozilla-
931 like browsers) orthe innerText (IE-like browsers) of the element,
932 which is the renderedtext shown to the user.
933 $locator is an element locator
935 Returns the text of the element
937 $sel->highlight($locator)
939 Briefly changes the backgroundColor of the specified element
940 yellow. Useful for debugging.
941 $locator is an element locator
943 $sel->get_eval($script)
945 Gets the result of evaluating the specified JavaScript snippet.
946 The snippet mayhave multiple lines, but only the result of the last
947 line will be returned. Note that, by default, the snippet will run
948 in the context of the "selenium"object itself, so "this" will refer
949 to the Selenium object. Use "window" torefer to the window of your
950 application, e.g. "window.document.getElementById('foo')"
951 If you need to usea locator to refer to a single element in your
953 application page, you canuse
954 "this.browserbot.findElement("id=foo")" where "id=foo" is your
955 locator.
956 $script is the JavaScript snippet to run
958 Returns the results of evaluating the snippet
960 $sel->is_checked($locator)
962 Gets whether a toggle-button (checkbox/radio) is checked. Fails if
963 the specified element doesn't exist or isn't a toggle-button.
964 $locator is an element locator pointing to a checkbox or radio
966 button
967 Returns true if the checkbox is checked, false otherwise
969 $sel->get_table($table_cell_address)
971 Gets the text from a cell of a table. The cellAddress
972 syntaxtableLocator.row.column, where row and column start at 0.
973 $table_cell_address is a cell address, e.g. "foo.1.4"
975 Returns the text from the specified cell
977 $sel->get_selected_labels($select_locator)
979 Gets all option labels (visible text) for selected options in the
980 specified select or multi-select element.
981 $select_locator is an element locator identifying a drop-down
983 menu
984 Returns an array of all selected option labels in the specified
986 select drop-down
987 $sel->get_selected_label($select_locator)
989 Gets option label (visible text) for selected option in the
990 specified select element.
991 $select_locator is an element locator identifying a drop-down
993 menu
994 Returns the selected option label in the specified select drop-
996 down
997 $sel->get_selected_values($select_locator)
999 Gets all option values (value attributes) for selected options in
1000 the specified select or multi-select element.
1001 $select_locator is an element locator identifying a drop-down
1003 menu
1004 Returns an array of all selected option values in the specified
1006 select drop-down
1007 $sel->get_selected_value($select_locator)
1009 Gets option value (value attribute) for selected option in the
1010 specified select element.
1011 $select_locator is an element locator identifying a drop-down
1013 menu
1014 Returns the selected option value in the specified select drop-
1016 down
1017 $sel->get_selected_indexes($select_locator)
1019 Gets all option indexes (option number, starting at 0) for selected
1020 options in the specified select or multi-select element.
1021 $select_locator is an element locator identifying a drop-down
1023 menu
1024 Returns an array of all selected option indexes in the
1026 specified select drop-down
1027 $sel->get_selected_index($select_locator)
1029 Gets option index (option number, starting at 0) for selected
1030 option in the specified select element.
1031 $select_locator is an element locator identifying a drop-down
1033 menu
1034 Returns the selected option index in the specified select drop-
1036 down
1037 $sel->get_selected_ids($select_locator)
1039 Gets all option element IDs for selected options in the specified
1040 select or multi-select element.
1041 $select_locator is an element locator identifying a drop-down
1043 menu
1044 Returns an array of all selected option IDs in the specified
1046 select drop-down
1047 $sel->get_selected_id($select_locator)
1049 Gets option element ID for selected option in the specified select
1050 element.
1051 $select_locator is an element locator identifying a drop-down
1053 menu
1054 Returns the selected option ID in the specified select drop-
1056 down
1057 $sel->is_something_selected($select_locator)
1059 Determines whether some option in a drop-down menu is selected.
1060 $select_locator is an element locator identifying a drop-down
1062 menu
1063 Returns true if some option has been selected, false otherwise
1065 $sel->get_select_options($select_locator)
1067 Gets all option labels in the specified select drop-down.
1068 $select_locator is an element locator identifying a drop-down
1070 menu
1071 Returns an array of all option labels in the specified select
1073 drop-down
1074 $sel->get_attribute($attribute_locator)
1076 Gets the value of an element attribute. The value of the attribute
1077 maydiffer across browsers (this is the case for the "style"
1078 attribute, forexample).
1079 $attribute_locator is an element locator followed by an @ sign
1081 and then the name of the attribute, e.g. "foo@bar"
1082 Returns the value of the specified attribute
1084 $sel->is_text_present($pattern)
1086 Verifies that the specified text pattern appears somewhere on the
1087 rendered page shown to the user.
1088 $pattern is a pattern to match with the text of the page
1090 Returns true if the pattern matches the text, false otherwise
1092 $sel->is_element_present($locator)
1094 Verifies that the specified element is somewhere on the page.
1095 $locator is an element locator
1097 Returns true if the element is present, false otherwise
1099 $sel->is_visible($locator)
1101 Determines if the specified element is visible. Anelement can be
1102 rendered invisible by setting the CSS "visibility"property to
1103 "hidden", or the "display" property to "none", either for
1104 theelement itself or one if its ancestors. This method will fail
1105 ifthe element is not present.
1106 $locator is an element locator
1108 Returns true if the specified element is visible, false
1110 otherwise
1111 $sel->is_editable($locator)
1113 Determines whether the specified input element is editable, ie
1114 hasn't been disabled.This method will fail if the specified element
1115 isn't an input element.
1116 $locator is an element locator
1118 Returns true if the input element is editable, false otherwise
1120 $sel->get_all_buttons()
1122 Returns the IDs of all buttons on the page. If a given button has
1123 no ID, it will appear as "" in this array.
1124 Returns the IDs of all buttons on the page
1126 $sel->get_all_links()
1128 Returns the IDs of all links on the page. If a given link has no
1129 ID, it will appear as "" in this array.
1130 Returns the IDs of all links on the page
1132 $sel->get_all_fields()
1134 Returns the IDs of all input fields on the page. If a given field
1135 has no ID, it will appear as "" in this array.
1136 Returns the IDs of all field on the page
1138 $sel->get_attribute_from_all_windows($attribute_name)
1140 Returns an array of JavaScript property values from all known
1141 windows having one.
1142 $attribute_name is name of an attribute on the windows
1144 Returns the set of values of this attribute from all known
1146 windows.
1147 $sel->dragdrop($locator, $movements_string)
1149 deprecated - use dragAndDrop instead
1150 $locator is an element locator
1152 $movements_string is offset in pixels from the current location
1154 to which the element should be moved, e.g., "+70,-300"
1155 $sel->set_mouse_speed($pixels)
1157 Configure the number of pixels between "mousemove" events during
1158 dragAndDrop commands (default=10). Setting this value to 0 means
1159 that we'll send a "mousemove" event to every single pixelin between
1160 the start location and the end location; that can be very slow, and
1161 maycause some browsers to force the JavaScript to timeout.
1162 If the mouse speed is greater than the distance between the two
1164 dragged objects, we'lljust send one "mousemove" at the start
1165 location and then one final one at the end location.
1166 $pixels is the number of pixels between "mousemove" events
1168 $sel->get_mouse_speed()
1170 Returns the number of pixels between "mousemove" events during
1171 dragAndDrop commands (default=10).
1172 Returns the number of pixels between "mousemove" events during
1174 dragAndDrop commands (default=10)
1175 $sel->drag_and_drop($locator, $movements_string)
1177 Drags an element a certain distance and then drops it
1178 $locator is an element locator
1180 $movements_string is offset in pixels from the current location
1182 to which the element should be moved, e.g., "+70,-300"
1183 $sel->drag_and_drop_to_object($locator_of_object_to_be_dragged,
1185 $locator_of_drag_destination_object)
1186 Drags an element and drops it on another element
1187 $locator_of_object_to_be_dragged is an element to be dragged
1189 $locator_of_drag_destination_object is an element whose
1191 location (i.e., whose center-most pixel) will be the point
1192 where locatorOfObjectToBeDragged is dropped
1193 $sel->window_focus()
1195 Gives focus to the currently selected window
1196 $sel->window_maximize()
1198 Resize currently selected window to take up the entire screen
1199 $sel->get_all_window_ids()
1201 Returns the IDs of all windows that the browser knows about in an
1202 array.
1203 Returns Array of identifiers of all windows that the browser
1205 knows about.
1206 $sel->get_all_window_names()
1208 Returns the names of all windows that the browser knows about in an
1209 array.
1210 Returns Array of names of all windows that the browser knows
1212 about.
1213 $sel->get_all_window_titles()
1215 Returns the titles of all windows that the browser knows about in
1216 an array.
1217 Returns Array of titles of all windows that the browser knows
1219 about.
1220 $sel->get_html_source()
1222 Returns the entire HTML source between the opening andclosing
1223 "html" tags.
1224 Returns the entire HTML source
1226 $sel->set_cursor_position($locator, $position)
1228 Moves the text cursor to the specified position in the given input
1229 element or textarea.This method will fail if the specified element
1230 isn't an input element or textarea.
1231 $locator is an element locator pointing to an input element or
1233 textarea
1234 $position is the numerical position of the cursor in the field;
1236 position should be 0 to move the position to the beginning of
1237 the field. You can also set the cursor to -1 to move it to the
1238 end of the field.
1239 $sel->get_element_index($locator)
1241 Get the relative index of an element to its parent (starting from
1242 0). The comment node and empty text nodewill be ignored.
1243 $locator is an element locator pointing to an element
1245 Returns of relative index of the element to its parent
1247 (starting from 0)
1248 $sel->is_ordered($locator1, $locator2)
1250 Check if these two elements have same parent and are ordered
1251 siblings in the DOM. Two same elements willnot be considered
1252 ordered.
1253 $locator1 is an element locator pointing to the first element
1255 $locator2 is an element locator pointing to the second element
1257 Returns true if element1 is the previous sibling of element2,
1259 false otherwise
1260 $sel->get_element_position_left($locator)
1262 Retrieves the horizontal position of an element
1263 $locator is an element locator pointing to an element OR an
1265 element itself
1266 Returns of pixels from the edge of the frame.
1268 $sel->get_element_position_top($locator)
1270 Retrieves the vertical position of an element
1271 $locator is an element locator pointing to an element OR an
1273 element itself
1274 Returns of pixels from the edge of the frame.
1276 $sel->get_element_width($locator)
1278 Retrieves the width of an element
1279 $locator is an element locator pointing to an element
1281 Returns width of an element in pixels
1283 $sel->get_element_height($locator)
1285 Retrieves the height of an element
1286 $locator is an element locator pointing to an element
1288 Returns height of an element in pixels
1290 $sel->get_cursor_position($locator)
1292 Retrieves the text cursor position in the given input element or
1293 textarea; beware, this may not work perfectly on all browsers.
1294 Specifically, if the cursor/selection has been cleared by
1295 JavaScript, this command will tend toreturn the position of the
1296 last location of the cursor, even though the cursor is now gone
1297 from the page. This is filed as
1298 http://jira.openqa.org/browse/SEL-243 (SEL-243). This method will
1299 fail if the specified element isn't an input element or textarea,
1300 or there is no cursor in the element.
1301 $locator is an element locator pointing to an input element or
1303 textarea
1304 Returns the numerical position of the cursor in the field
1306 $sel->get_expression($expression)
1308 Returns the specified expression. This is useful because of
1309 JavaScript preprocessing.It is used to generate commands like
1310 assertExpression and waitForExpression.
1311 $expression is the value to return
1313 Returns the value passed in
1315 $sel->get_xpath_count($xpath)
1317 Returns the number of nodes that match the specified xpath, eg.
1318 "//table" would givethe number of tables.
1319 $xpath is the xpath expression to evaluate. do NOT wrap this
1321 expression in a 'count()' function; we will do that for you.
1322 Returns the number of nodes that match the specified xpath
1324 $sel->assign_id($locator, $identifier)
1326 Temporarily sets the "id" attribute of the specified element, so
1327 you can locate it in the futureusing its ID rather than a
1328 slow/complicated XPath. This ID will disappear once the page
1329 isreloaded.
1330 $locator is an element locator pointing to an element
1332 $identifier is a string to be used as the ID of the specified
1334 element
1335 $sel->allow_native_xpath($allow)
1337 Specifies whether Selenium should use the native in-browser
1338 implementationof XPath (if any native version is available); if you
1339 pass "false" tothis function, we will always use our pure-
1340 JavaScript xpath library.Using the pure-JS xpath library can
1341 improve the consistency of xpathelement locators between different
1342 browser vendors, but the pure-JSversion is much slower than the
1343 native implementations.
1344 $allow is boolean, true means we'll prefer to use native XPath;
1346 false means we'll only use JS XPath
1347 $sel->ignore_attributes_without_value($ignore)
1349 Specifies whether Selenium will ignore xpath attributes that have
1350 novalue, i.e. are the empty string, when using the non-native
1351 xpathevaluation engine. You'd want to do this for performance
1352 reasons in IE.However, this could break certain xpaths, for example
1353 an xpath that looksfor an attribute whose value is NOT the empty
1354 string.The hope is that such xpaths are relatively rare, but the
1355 user shouldhave the option of using them. Note that this only
1356 influences xpathevaluation when using the ajaxslt engine (i.e. not
1357 "javascript-xpath").
1358 $ignore is boolean, true means we'll ignore attributes without
1360 value at the expense of xpath
1361 "correctness"; false means we'll
1362 sacrifice speed for correctness.
1363 $sel->wait_for_condition($script, $timeout)
1365 Runs the specified JavaScript snippet repeatedly until it evaluates
1366 to "true".The snippet may have multiple lines, but only the result
1367 of the last linewill be considered. Note that, by default, the
1368 snippet will be run in the runner's test window, not in the
1369 windowof your application. To get the window of your application,
1370 you can usethe JavaScript snippet
1371 "selenium.browserbot.getCurrentWindow()", and thenrun your
1372 JavaScript in there
1373 $script is the JavaScript snippet to run
1375 $timeout is a timeout in milliseconds, after which this command
1377 will return with an error
1378 $sel->set_timeout($timeout)
1380 Specifies the amount of time that Selenium will wait for actions to
1381 complete. Actions that require waiting include "open" and the
1382 "waitFor*" actions. The default timeout is 30 seconds.
1383 $timeout is a timeout in milliseconds, after which the action
1385 will return with an error
1386 $sel->wait_for_page_to_load($timeout)
1388 Waits for a new page to load. You can use this command instead of
1389 the "AndWait" suffixes, "clickAndWait", "selectAndWait",
1390 "typeAndWait" etc.(which are only available in the JS API).
1391 Selenium constantly keeps track of new pages loading, and sets a
1393 "newPageLoaded"flag when it first notices a page load. Running any
1394 other Selenium command afterturns the flag to false. Hence, if you
1395 want to wait for a page to load, you mustwait immediately after a
1396 Selenium command that caused a page-load.
1397 $timeout is a timeout in milliseconds, after which this command
1399 will return with an error
1400 $sel->wait_for_frame_to_load($frame_address, $timeout)
1402 Waits for a new frame to load. Selenium constantly keeps track of
1403 new pages and frames loading, and sets a "newPageLoaded" flag when
1404 it first notices a page load. See waitForPageToLoad for more
1405 information.
1406 $frame_address is FrameAddress from the server side
1408 $timeout is a timeout in milliseconds, after which this command
1410 will return with an error
1411 $sel->get_cookie()
1413 Return all cookies of the current page under test.
1414 Returns all cookies of the current page under test
1416 $sel->get_cookie_by_name($name)
1418 Returns the value of the cookie with the specified name, or throws
1419 an error if the cookie is not present.
1420 $name is the name of the cookie
1422 Returns the value of the cookie
1424 $sel->is_cookie_present($name)
1426 Returns true if a cookie with the specified name is present, or
1427 false otherwise.
1428 $name is the name of the cookie
1430 Returns true if a cookie with the specified name is present, or
1432 false otherwise.
1433 $sel->create_cookie($name_value_pair, $options_string)
1435 Create a new cookie whose path and domain are same with those of
1436 current pageunder test, unless you specified a path for this cookie
1437 explicitly.
1438 $name_value_pair is name and value of the cookie in a format
1440 "name=value"
1441 $options_string is options for the cookie. Currently supported
1443 options include 'path', 'max_age' and 'domain'. the
1444 optionsString's format is "path=/path/, max_age=60,
1445 domain=.foo.com". The order of options are irrelevant, the unit
1446 of the value of 'max_age' is second. Note that specifying a
1447 domain that isn't a subset of the current domain will
1448 usually fail.
1449 $sel->delete_cookie($name, $options_string)
1451 Delete a named cookie with specified path and domain. Be careful;
1452 to delete a cookie, youneed to delete it using the exact same path
1453 and domain that were used to create the cookie.If the path is
1454 wrong, or the domain is wrong, the cookie simply won't be deleted.
1455 Alsonote that specifying a domain that isn't a subset of the
1456 current domain will usually fail.Since there's no way to discover
1457 at runtime the original path and domain of a given cookie,we've
1458 added an option called 'recurse' to try all sub-domains of the
1459 current domain withall paths that are a subset of the current path.
1460 Beware; this option can be slow. Inbig-O notation, it operates in
1461 O(n*m) time, where n is the number of dots in the domainname and m
1462 is the number of slashes in the path.
1463 $name is the name of the cookie to be deleted
1465 $options_string is options for the cookie. Currently supported
1467 options include 'path', 'domain' and 'recurse.' The
1468 optionsString's format is "path=/path/, domain=.foo.com,
1469 recurse=true". The order of options are irrelevant. Note
1470 that specifying a domain that isn't a subset of the
1471 current domain will usually fail.
1472 $sel->delete_all_visible_cookies()
1474 Calls deleteCookie with recurse=true on all cookies visible to the
1475 current page.As noted on the documentation for deleteCookie,
1476 recurse=true can be much slowerthan simply deleting the cookies
1477 using a known domain/path.
1478 $sel->set_browser_log_level($log_level)
1480 Sets the threshold for browser-side logging messages; log messages
1481 beneath this threshold will be discarded.Valid logLevel strings
1482 are: "debug", "info", "warn", "error" or "off".To see the browser
1483 logs, you need toeither show the log window in GUI mode, or enable
1484 browser-side logging in Selenium RC.
1485 $log_level is one of the following: "debug", "info", "warn",
1487 "error" or "off"
1488 $sel->run_script($script)
1490 Creates a new "script" tag in the body of the current test window,
1491 and adds the specified text into the body of the command. Scripts
1492 run inthis way can often be debugged more easily than scripts
1493 executed usingSelenium's "getEval" command. Beware that JS
1494 exceptions thrown in these scripttags aren't managed by Selenium,
1495 so you should probably wrap your scriptin try/catch blocks if there
1496 is any chance that the script will throwan exception.
1497 $script is the JavaScript snippet to run
1499 $sel->add_location_strategy($strategy_name)
1501 Defines a new function for Selenium to locate elements on the
1502 page.For example,if you define the strategy "foo", and someone runs
1503 click("foo=blah"), we'llrun your function, passing you the string
1504 "blah", and click on the element that your functionreturns, or
1505 throw an "Element not found" error if your function returns
1506 null.We'll pass three arguments to your function:
1507 · locator: the string the user passed in
1509 · inWindow: the currently selected window
1511 · inDocument: the currently selected document
1513 The function must return null if the element can't be found.
1515 $strategy_name is the name of the strategy to define; this
1517 should use only letters [a-zA-Z] with no spaces or other
1518 punctuation.
1519 $sel->capture_entire_page_screenshot($filename, $kwargs)
1521 Saves the entire contents of the current window canvas to a PNG
1522 file.Contrast this with the captureScreenshot command, which
1523 captures thecontents of the OS viewport (i.e. whatever is currently
1524 being displayedon the monitor), and is implemented in the RC only.
1525 Currently this onlyworks in Firefox when running in chrome mode,
1526 and in IE non-HTA usingthe EXPERIMENTAL "Snapsie" utility. The
1527 Firefox implementation is mostlyborrowed from the Screengrab!
1528 Firefox extension. Please seehttp://www.screengrab.org and
1529 http://snapsie.sourceforge.net/ fordetails.
1530 $filename is the path to the file to persist the screenshot as.
1532 No filename extension will be appended by
1533 default. Directories will not be created if
1534 they do not exist, and an exception will be
1535 thrown, possibly by native code.
1536 $kwargs is a kwargs string that modifies the way the screenshot
1538 is captured. Example: "background=#CCFFDD" .
1539 Currently valid options:
1540 =item background
1541 the background CSS for the HTML document. This
1543 may be useful to set for capturing screenshots of
1544 less-than-ideal layouts, for example where absolute
1545 positioning causes the calculation of the canvas
1546 dimension to fail and a black background is exposed
1547 (possibly obscuring black text).
1548 $sel->rollup($rollup_name, $kwargs)
1550 Executes a command rollup, which is a series of commands with a
1551 uniquename, and optionally arguments that control the generation of
1552 the set ofcommands. If any one of the rolled-up commands fails, the
1553 rollup isconsidered to have failed. Rollups may also contain nested
1554 rollups.
1555 $rollup_name is the name of the rollup command
1557 $kwargs is keyword arguments string that influences how the
1559 rollup expands into commands
1560 $sel->add_script($script_content, $script_tag_id)
1562 Loads script content into a new script tag in the Selenium
1563 document. Thisdiffers from the runScript command in that runScript
1564 adds the script tagto the document of the AUT, not the Selenium
1565 document. The followingentities in the script content are replaced
1566 by the characters theyrepresent: < > &The
1567 corresponding remove command is removeScript.
1568 $script_content is the Javascript content of the script to add
1570 $script_tag_id is (optional) the id of the new script tag. If
1572 specified, and an element with this id already
1573 exists, this operation will fail.
1574 $sel->remove_script($script_tag_id)
1576 Removes a script tag from the Selenium document identified by the
1577 givenid. Does nothing if the referenced tag doesn't exist.
1578 $script_tag_id is the id of the script element to remove.
1580 $sel->use_xpath_library($library_name)
1582 Allows choice of one of the available libraries.
1583 $library_name is name of the desired library Only the following
1585 three can be chosen:
1586 · "ajaxslt" - Google's library
1588 · "javascript-xpath" - Cybozu Labs' faster library
1590 · "default" - The default library. Currently the default
1592 library is "ajaxslt" .
1593 =back
1595 If libraryName isn't one of these three, then no change will be made.
1597 $sel->set_context($context)
1599 Writes a message to the status bar and adds a note to the
1601 browser-sidelog.
1602 $context is the message to be sent to the browser
1604 $sel->attach_file($field_locator, $file_locator)
1606 Sets a file input (upload) field to the file listed in
1608 fileLocator
1609 $field_locator is an element locator
1611 $file_locator is a URL pointing to the specified file.
1613 Before the file can be set in the input field
1614 (fieldLocator), Selenium RC may need to transfer the file
1615 to the local machine before attaching the file in a web
1616 page form. This is common in selenium grid configurations
1617 where the RC server driving the browser is not the same
1618 machine that started the test. Supported Browsers:
1619 Firefox ("*chrome") only.
1620 $sel->capture_screenshot($filename)
1622 Captures a PNG screenshot to the specified file.
1624 $filename is the absolute path to the file to be written,
1626 e.g. "c:\blah\screenshot.png"
1627 $sel->capture_screenshot_to_string()
1629 Capture a PNG screenshot. It then returns the file as a base
1631 64 encoded string.
1632 Returns The base 64 encoded string of the screen shot (PNG
1634 file)
1635 $sel->capture_entire_page_screenshot_to_string($kwargs)
1637 Downloads a screenshot of the browser current window canvas to
1639 a based 64 encoded PNG file. The entire windows canvas is
1640 captured,including parts rendered outside of the current view
1641 port.Currently this only works in Mozilla and when running in
1642 chrome mode.
1643 $kwargs is A kwargs string that modifies the way the
1645 screenshot is captured. Example: "background=#CCFFDD". This
1646 may be useful to set for capturing screenshots of less-
1647 than-ideal layouts, for example where absolute positioning
1648 causes the calculation of the canvas dimension to fail and
1649 a black background is exposed (possibly obscuring black
1650 text).
1651 Returns The base 64 encoded string of the page screenshot
1653 (PNG file)
1654 $sel->shut_down_selenium_server()
1656 Kills the running Selenium Server and all browser sessions.
1658 After you run this command, you will no longer be able to
1659 sendcommands to the server; you can't remotely start the server
1660 once it has been stopped. Normallyyou should prefer to run the
1661 "stop" command, which terminates the current browser session,
1662 rather than shutting down the entire server.
1663 $sel->retrieve_last_remote_control_logs()
1665 Retrieve the last messages logged on a specific remote control.
1667 Useful for error reports, especiallywhen running multiple
1668 remote controls in a distributed environment. The maximum
1669 number of log messagesthat can be retrieve is configured on
1670 remote control startup.
1671 Returns The last N log messages as a multi-line string.
1673 $sel->key_down_native($keycode)
1675 Simulates a user pressing a key (without releasing it yet) by
1677 sending a native operating system keystroke.This function uses
1678 the java.awt.Robot class to send a keystroke; this more
1679 accurately simulates typinga key on the keyboard. It does not
1680 honor settings from the shiftKeyDown, controlKeyDown,
1681 altKeyDown andmetaKeyDown commands, and does not target any
1682 particular HTML element. To send a keystroke to a
1683 particularelement, focus on the element first before running
1684 this command.
1685 $keycode is an integer keycode number corresponding to a
1687 java.awt.event.KeyEvent; note that Java keycodes are NOT
1688 the same thing as JavaScript keycodes!
1689 $sel->key_up_native($keycode)
1691 Simulates a user releasing a key by sending a native operating
1693 system keystroke.This function uses the java.awt.Robot class to
1694 send a keystroke; this more accurately simulates typinga key on
1695 the keyboard. It does not honor settings from the
1696 shiftKeyDown, controlKeyDown, altKeyDown andmetaKeyDown
1697 commands, and does not target any particular HTML element. To
1698 send a keystroke to a particularelement, focus on the element
1699 first before running this command.
1700 $keycode is an integer keycode number corresponding to a
1702 java.awt.event.KeyEvent; note that Java keycodes are NOT
1703 the same thing as JavaScript keycodes!
1704 $sel->key_press_native($keycode)
1706 Simulates a user pressing and releasing a key by sending a
1708 native operating system keystroke.This function uses the
1709 java.awt.Robot class to send a keystroke; this more accurately
1710 simulates typinga key on the keyboard. It does not honor
1711 settings from the shiftKeyDown, controlKeyDown, altKeyDown
1712 andmetaKeyDown commands, and does not target any particular
1713 HTML element. To send a keystroke to a particularelement,
1714 focus on the element first before running this command.
1715 $keycode is an integer keycode number corresponding to a
1717 java.awt.event.KeyEvent; note that Java keycodes are NOT
1718 the same thing as JavaScript keycodes!
1719 $sel->wait_for_text_present($text, $timeout)
1721 Waits until $text is present in the html source
1723 $sel->wait_for_element_present($locator, $timeout)
1725 Waits until $locator is present
1727 * $sel->is_location($expected_location)
1729 Verify the location of the current page ends with the expected
1731 location. If an URL querystring is provided, this is checked
1732 as well.
1733 $expected_location is the location to match.
1735 Note: This function is deprecated, use get_location() instead.
1737 * $sel->get_checked($locator)
1739 Gets whether a toggle-button (checkbox/radio) is checked.
1741 Fails if the specified element doesn't exist or isn't a toggle-
1742 button.
1743 $locator is an element locator pointing to a checkbox or
1745 radio button.
1746 Note: This function is deprecated, use is_checked() instead.
1748 * $sel->is_selected($locator, $option_locator)
1750 Verifies that the selected option of a drop-down satisfies the
1752 optionSpecifier.
1753 See the select command for more information about option
1755 locators.
1756 $locator is an element locator. $option_locator is an
1758 option locator, typically just an option label (e.g. "John
1759 Smith").
1760 Note: This function is deprecated, use the get_selected_*()
1762 methods instead.
1763 * $sel->get_selected_options($locator)
1765 Gets all option labels for selected options in the specified
1767 select or multi-select element.
1768 $locator is an element locator.
1770 Note: This function is deprecated, use get_selected_labels()
1772 instead.
1773 * $sel->get_absolute_location()
1775 Gets the absolute URL of the current page.
1777 Note: This function is deprecated, use get_location() instead.
1779
1781 For more information about Selenium Remote Control, visit the website
1782 at http://www.openqa.org/selenium-rc/ <http://www.openqa.org/selenium-
1783 rc/>.
1784
1786 The Selenium Remote Control JIRA issue tracking system is available
1787 online at <http://jira.openqa.org/browse/SRC>.
1788
1790 Perl driver maintained by Luke Closs <selenium-rc@awesnob.com>
1791 Selenium Remote Control maintained by Dan Fabulich
1793 <dfabulich@warpmail.net>
1794
1796 Copyright (c) 2006 ThoughtWorks, Inc
1797 Licensed under the Apache License, Version 2.0 (the "License"); you may
1799 not use this file except in compliance with the License. You may
1800 obtain a copy of the License at
1801 http://www.apache.org/licenses/LICENSE-2.0
1803 Unless required by applicable law or agreed to in writing, software
1805 distributed under the License is distributed on an "AS IS" BASIS,
1806 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
1807 implied. See the License for the specific language governing
1808 permissions and limitations under the License.
1809
1811 Hey! The above document had some coding errors, which are explained
1812 below:
1813 Around line 3197:
1815 You can't have =items (as at line 3231) unless the first thing
1816 after the =over is an =item
1817 Around line 3552:
1819 You forgot a '=back' before '=head1'
1820perl v5.12.0 2010-06-03 WWW::Selenium(3)