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 version 1.36
10
12 use WWW::Selenium;
13 my $sel = WWW::Selenium->new( host => "localhost",
15 port => 4444,
16 browser => "*iexplore",
17 browser_url => "http://www.google.com",
18 );
19 $sel->start;
21 $sel->open("http://www.google.com");
22 $sel->type("q", "hello world");
23 $sel->click("btnG");
24 $sel->wait_for_page_to_load(5000);
25 print $sel->get_title;
26 $sel->stop;
27
29 Selenium Remote Control (SRC) is a test tool that allows you to write
30 automated web application UI tests in any programming language against
31 any HTTP website using any mainstream JavaScript-enabled browser. SRC
32 provides a Selenium Server, which can automatically start/stop/control
33 any supported browser. It works by using Selenium Core, a pure-HTML+JS
34 library that performs automated tasks in JavaScript; the Selenium
35 Server communicates directly with the browser using AJAX
36 (XmlHttpRequest).
37 <http://www.openqa.org/selenium-rc/>
39 This module sends commands directly to the Server using simple HTTP
41 GET/POST requests. Using this module together with the Selenium
42 Server, you can automatically control any supported browser.
43 To use this module, you need to have already downloaded and started the
45 Selenium Server. (The Selenium Server is a Java application.)
46 Element Locators
48 Element Locators tell Selenium which HTML element a command refers
49 to.The format of a locator is:
50 locatorType=argument
52 We support the following strategies for locating elements:
54 • identifier=id: Select the element with the specified @id attribute.
56 If no match isfound, select the first element whose @name attribute
57 is id.(This is normally the default; see below.)
58 • id=id:Select the element with the specified @id attribute.
60 • name=name:Select the first element with the specified @name
62 attribute.
63 • username
65 • name=username
67 The name may optionally be followed by one or more element-filters,
69 separated from the name by whitespace. If the filterType is not
70 specified, value is assumed.
71 • name=flavour value=chocolate
73 • dom=javascriptExpression: Find an element by evaluating the
75 specified string. This allows you to traverse the HTML Document
76 ObjectModel using JavaScript. Note that you must not return a
77 value in this string; simply make it the last expression in the
78 block.
79 • dom=document.forms['myForm'].myDropdown
81 • dom=document.images[56]
83 • dom=function foo() { return document.links[1]; }; foo();
85 • xpath=xpathExpression: Locate an element using an XPath expression.
87 • xpath=//img[@alt='The image alt text']
89 • xpath=//table[@id='table1']//tr[4]/td[2]
91 • xpath=//a[contains(@href,'#id1')]
93 • xpath=//a[contains(@href,'#id1')]/@class
95 • xpath=(//table[@class='stylee'])//th[text()='theHeaderText']/../td
97 • xpath=//input[@name='name2' and @value='yes']
99 • xpath=//*[text()="right"]
101 • link=textPattern:Select the link (anchor) element which contains
103 text matching thespecified pattern.
104 • link=The link text
106 • css=cssSelectorSyntax:Select the element using css selectors.
108 Please refer to http://www.w3.org/TR/REC-CSS2/selector.html (CSS2
109 selectors), http://www.w3.org/TR/2001/CR-css3-selectors-20011113/
110 (CSS3 selectors) for more information. You can also check the
111 TestCssLocators test in the selenium test suite for an example of
112 usage, which is included in the downloaded selenium core package.
113 • css=a[href="#id3"]
115 • css=span#firstChild + span
117 Currently the css selector locator supports all css1, css2 and css3
119 selectors except namespace in css3, some pseudo
120 classes(:nth-of-type, :nth-last-of-type, :first-of-type,
121 :last-of-type, :only-of-type, :visited, :hover, :active, :focus,
122 :indeterminate) and pseudo elements(::first-line, ::first-letter,
123 ::selection, ::before, ::after).
124 • ui=uiSpecifierString:Locate an element by resolving the UI
126 specifier string to another locator, and evaluating it. See the
127 http://svn.openqa.org/fisheye/browse/~raw,r=trunk/selenium/trunk/src/main/resources/core/scripts/ui-doc.html
128 (Selenium UI-Element Reference) for more details.
129 • ui=loginPages::loginButton()
131 • ui=settingsPages::toggle(label=Hide Email)
133 • ui=forumPages::postBody(index=2)//a[2]
135 Without an explicit locator prefix, Selenium uses the following
137 defaultstrategies:
138 • dom, for locators starting with "document."
140 • xpath, for locators starting with "//"
142 • identifier, otherwise
144 Element Filters
146 Element filters can be used with a locator to refine a list of
147 candidate elements. They are currently used only in the 'name'
148 element-locator.
149 Filters look much like locators, ie.
151 filterType=argument
153 Supported element-filters are:
155 value=valuePattern
157 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
162 from zero).
163 String-match Patterns
165 Various Pattern syntaxes are available for matching string values:
166 • glob:pattern:Match a string against a "glob" (aka "wildmat")
168 pattern. "Glob" is akind of limited regular-expression syntax
169 typically used in command-lineshells. In a glob pattern, "*"
170 represents any sequence of characters, and "?"represents any single
171 character. Glob patterns match against the entirestring.
172 • regexp:regexp:Match a string using a regular-expression. The full
174 power of JavaScriptregular-expressions is available.
175 • regexpi:regexpi:Match a string using a case-insensitive regular-
177 expression.
178 • exact:string:Match a string exactly, verbatim, without any of that
180 fancy wildcardstuff.
181 If no pattern prefix is specified, Selenium assumes that it's a
183 "glob"pattern.
184 For commands that return multiple values (such as
186 verifySelectOptions),the string being matched is a comma-separated list
187 of the return values,where both commas and backslashes in the values
188 are backslash-escaped.When providing a pattern, the optional matching
189 syntax (i.e. glob,regexp, etc.) is specified once, as usual, at the
190 beginning of thepattern.
191 METHODS
193 The following methods are available:
194 $sel = WWW::Selenium->new( %args )
196 Constructs a new "WWW::Selenium" object, specifying a Selenium
197 Server host/port, a command to launch the browser, and a starting
198 URL for the browser.
199 Options:
201 • "host"
203 host is the host name on which the Selenium Server resides.
205 • "port"
207 port is the port on which the Selenium Server is listening.
209 • "browser_url"
211 browser_url is the starting URL including just a domain name.
213 We'll start the browser pointing at the Selenium resources on
214 this URL, e.g. "http://www.google.com" would send the browser
215 to "http://www.google.com/selenium-server/SeleneseRunner.html"
216 • "browser" or "browser_start_command"
218 This is the command string used to launch the browser, e.g.
220 "*firefox", "*iexplore" or "/usr/bin/firefox"
221 This option may be any one of the following:
223 • "*firefox [absolute path]"
225 Automatically launch a new Firefox process using a custom
227 Firefox profile. This profile will be automatically
228 configured to use the Selenium Server as a proxy and to
229 have all annoying prompts ("save your password?" "forms are
230 insecure" "make Firefox your default browser?" disabled.
231 You may optionally specify an absolute path to your firefox
232 executable, or just say "*firefox". If no absolute path is
233 specified, we'll look for firefox.exe in a default location
234 (normally c:\program files\mozilla firefox\firefox.exe),
235 which you can override by setting the Java system property
236 "firefoxDefaultPath" to the correct path to Firefox.
237 • "*iexplore [absolute path]"
239 Automatically launch a new Internet Explorer process using
241 custom Windows registry settings. This process will be
242 automatically configured to use the Selenium Server as a
243 proxy and to have all annoying prompts ("save your
244 password?" "forms are insecure" "make Firefox your default
245 browser?" disabled. You may optionally specify an absolute
246 path to your iexplore executable, or just say "*iexplore".
247 If no absolute path is specified, we'll look for
248 iexplore.exe in a default location (normally c:\program
249 files\internet explorer\iexplore.exe), which you can
250 override by setting the Java system property
251 "iexploreDefaultPath" to the correct path to Internet
252 Explorer.
253 • "/path/to/my/browser [other arguments]"
255 You may also simply specify the absolute path to your
257 browser executable, or use a relative path to your
258 executable (which we'll try to find on your path).
259 Warning: If you specify your own custom browser, it's up to
260 you to configure it correctly. At a minimum, you'll need
261 to configure your browser to use the Selenium Server as a
262 proxy, and disable all browser-specific prompting.
263 • "auto_stop"
265 Defaults to true, and will attempt to close the browser if the
267 object goes out of scope and stop hasn't been called.
268 • "keep_alive"
270 Number of connections LWP should cache. This is just a minor
272 speed improvement. Defaults to 5.
273 • "http_method">
275 Choose which HTTP method should be used for requests to the
277 Selenium server. Only GET and POST are supported.
278 $sel->pause($timeout)
280 Waits $timeout milliseconds (default: 1 second)
281 $sel->click($locator)
283 Clicks on a link, button, checkbox or radio button. If the click
284 actioncauses a new page to load (like a link usually does),
285 callwaitForPageToLoad.
286 $locator is an element locator
288 $sel->double_click($locator)
289 Double clicks on a link, button, checkbox or radio button. If the
290 double click actioncauses a new page to load (like a link usually
291 does), callwaitForPageToLoad.
292 $locator is an element locator
294 $sel->context_menu($locator)
295 Simulates opening the context menu for the specified element (as
296 might happen if the user "right-clicked" on the element).
297 $locator is an element locator
299 $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 the
306 mouse event relative to the element returned by the locator.
307 $sel->double_click_at($locator, $coord_string)
308 Doubleclicks on a link, button, checkbox or radio button. If the
309 actioncauses a new page to load (like a link usually does),
310 callwaitForPageToLoad.
311 $locator is an element locator
313 $coord_string is specifies the x,y position (i.e. - 10,20) of the
314 mouse event relative to the element returned by the locator.
315 $sel->context_menu_at($locator, $coord_string)
316 Simulates opening the context menu for the specified element (as
317 might happen if the user "right-clicked" on the element).
318 $locator is an element locator
320 $coord_string is specifies the x,y position (i.e. - 10,20) of the
321 mouse event relative to the element returned by the locator.
322 $sel->fire_event($locator, $event_name)
323 Explicitly simulate an event, to trigger the corresponding
324 "onevent"handler.
325 $locator is an element locator
327 $event_name is the event name, e.g. "focus" or "blur"
328 $sel->focus($locator)
329 Move the focus to the specified element; for example, if the
330 element is an input field, move the cursor to that field.
331 $locator is an element locator
333 $sel->key_press($locator, $key_sequence)
334 Simulates a user pressing and releasing a key.
335 $locator is an element locator
337 $key_sequence is Either be a string("\" followed by the numeric
338 keycode of the key to be pressed, normally the ASCII value of that
339 key), or a single character. For example: "w", "\119".
340 $sel->shift_key_down()
341 Press the shift key and hold it down until doShiftUp() is called or
342 a new page is loaded.
343 $sel->shift_key_up()
345 Release the shift key.
346 $sel->meta_key_down()
348 Press the meta key and hold it down until doMetaUp() is called or a
349 new page is loaded.
350 $sel->meta_key_up()
352 Release the meta key.
353 $sel->alt_key_down()
355 Press the alt key and hold it down until doAltUp() is called or a
356 new page is loaded.
357 $sel->alt_key_up()
359 Release the alt key.
360 $sel->control_key_down()
362 Press the control key and hold it down until doControlUp() is
363 called or a new page is loaded.
364 $sel->control_key_up()
366 Release the control key.
367 $sel->key_down($locator, $key_sequence)
369 Simulates a user pressing a key (without releasing it yet).
370 $locator is an element locator
372 $key_sequence is Either be a string("\" followed by the numeric
373 keycode of the key to be pressed, normally the ASCII value of that
374 key), or a single character. For example: "w", "\119".
375 $sel->key_up($locator, $key_sequence)
376 Simulates a user releasing a key.
377 $locator is an element locator
379 $key_sequence is Either be a string("\" followed by the numeric
380 keycode of the key to be pressed, normally the ASCII value of that
381 key), or a single character. For example: "w", "\119".
382 $sel->mouse_over($locator)
383 Simulates a user hovering a mouse over the specified element.
384 $locator is an element locator
386 $sel->mouse_out($locator)
387 Simulates a user moving the mouse pointer away from the specified
388 element.
389 $locator is an element locator
391 $sel->mouse_down($locator)
392 Simulates a user pressing the left mouse button (without releasing
393 it yet) onthe specified element.
394 $locator is an element locator
396 $sel->mouse_down_right($locator)
397 Simulates a user pressing the right mouse button (without releasing
398 it yet) onthe specified element.
399 $locator is an element locator
401 $sel->mouse_down_at($locator, $coord_string)
402 Simulates a user pressing the left mouse button (without releasing
403 it yet) atthe specified location.
404 $locator is an element locator
406 $coord_string is specifies the x,y position (i.e. - 10,20) of the
407 mouse event relative to the element returned by the locator.
408 $sel->mouse_down_right_at($locator, $coord_string)
409 Simulates a user pressing the right mouse button (without releasing
410 it yet) atthe specified location.
411 $locator is an element locator
413 $coord_string is specifies the x,y position (i.e. - 10,20) of the
414 mouse event relative to the element returned by the locator.
415 $sel->mouse_up($locator)
416 Simulates the event that occurs when the user releases the mouse
417 button (i.e., stopsholding the button down) on the specified
418 element.
419 $locator is an element locator
421 $sel->mouse_up_right($locator)
422 Simulates the event that occurs when the user releases the right
423 mouse button (i.e., stopsholding the button down) on the specified
424 element.
425 $locator is an element locator
427 $sel->mouse_up_at($locator, $coord_string)
428 Simulates the event that occurs when the user releases the mouse
429 button (i.e., stopsholding the button down) at the specified
430 location.
431 $locator is an element locator
433 $coord_string is specifies the x,y position (i.e. - 10,20) of the
434 mouse event relative to the element returned by the locator.
435 $sel->mouse_up_right_at($locator, $coord_string)
436 Simulates the event that occurs when the user releases the right
437 mouse button (i.e., stopsholding the button down) at the specified
438 location.
439 $locator is an element locator
441 $coord_string is specifies the x,y position (i.e. - 10,20) of the
442 mouse event relative to the element returned by the locator.
443 $sel->mouse_move($locator)
444 Simulates a user pressing the mouse button (without releasing it
445 yet) onthe specified element.
446 $locator is an element locator
448 $sel->mouse_move_at($locator, $coord_string)
449 Simulates a user pressing the mouse button (without releasing it
450 yet) onthe specified element.
451 $locator is an element locator
453 $coord_string is specifies the x,y position (i.e. - 10,20) of the
454 mouse event relative to the element returned by the locator.
455 $sel->type($locator, $value)
456 Sets the value of an input field, as though you typed it in. Can
457 also be used to set the value of combo boxes, check boxes, etc. In
458 these cases,value should be the value of the option selected, not
459 the visible text.
460 $locator is an element locator
462 $value is the value to type
463 $sel->type_keys($locator, $value)
464 Simulates keystroke events on the specified element, as though you
465 typed the value key-by-key. This is a convenience method for
466 calling keyDown, keyUp, keyPress for every character in the
467 specified string;this is useful for dynamic UI widgets (like auto-
468 completing combo boxes) that require explicit key events.
469 Unlike the simple "type" command, which forces the specified value
471 into the page directly, this commandmay or may not have any visible
472 effect, even in cases where typing keys would normally have a
473 visible effect.For example, if you use "typeKeys" on a form
474 element, you may or may not see the results of what you typed inthe
475 field.
476 In some cases, you may need to use the simple "type" command to set
478 the value of the field and then the "typeKeys" command tosend the
479 keystroke events corresponding to what you just typed.
480 $locator is an element locator
482 $value is the value to type
483 $sel->set_speed($value)
484 Set execution speed (i.e., set the millisecond length of a delay
485 which will follow each selenium operation). By default, there is
486 no such delay, i.e.,the delay is 0 milliseconds.
487 $value is the number of milliseconds to pause after operation
489 $sel->get_speed()
490 Get execution speed (i.e., get the millisecond length of the delay
491 following each selenium operation). By default, there is no such
492 delay, i.e.,the delay is 0 milliseconds.See also setSpeed.
493 Returns the execution speed in milliseconds.
495 $sel->check($locator)
496 Check a toggle-button (checkbox/radio)
497 $locator is an element locator
499 $sel->uncheck($locator)
500 Uncheck a toggle-button (checkbox/radio)
501 $locator is an element locator
503 $sel->select($select_locator, $option_locator)
504 Select an option from a drop-down using an option locator. Option
505 locators provide different ways of specifying options of an
506 HTMLSelect element (e.g. for selecting a specific option, or for
507 assertingthat the selected option satisfies a specification). There
508 are severalforms of Select Option Locator.
509 • label=labelPattern:matches options based on their labels, i.e.
511 the visible text. (Thisis the default.)
512 • label=regexp:^[Oo]ther
514 • value=valuePattern:matches options based on their values.
516 • value=other
518 • id=id:matches options based on their ids.
520 • id=option1
522 • index=index:matches an option based on its index (offset from
524 zero).
525 • index=2
527 If no option locator prefix is provided, the default behaviour is
529 to match on label.
530 $select_locator is an element locator identifying a drop-down menu
532 $option_locator is an option locator (a label by default)
533 $sel->add_selection($locator, $option_locator)
534 Add a selection to the set of selected options in a multi-select
535 element using an option locator.@see #doSelect for details of
536 option locators
537 $locator is an element locator identifying a multi-select box
539 $option_locator is an option locator (a label by default)
540 $sel->remove_selection($locator, $option_locator)
541 Remove a selection from the set of selected options in a multi-
542 select element using an option locator.@see #doSelect for details
543 of option locators
544 $locator is an element locator identifying a multi-select box
546 $option_locator is an option locator (a label by default)
547 $sel->remove_all_selections($locator)
548 Unselects all of the selected options in a multi-select element.
549 $locator is an element locator identifying a multi-select box
551 $sel->submit($form_locator)
552 Submit the specified form. This is particularly useful for forms
553 withoutsubmit buttons, e.g. single-input "Search" forms.
554 $form_locator is an element locator for the form you want to submit
556 $sel->open($url)
557 Opens an URL in the test frame. This accepts both relative and
558 absoluteURLs.The "open" command waits for the page to load before
559 proceeding,ie. the "AndWait" suffix is implicit.Note: The URL must
560 be on the same domain as the runner HTMLdue to security
561 restrictions in the browser (Same Origin Policy). If youneed to
562 open an URL on another domain, use the Selenium Server to start
563 anew browser session on that domain.
564 $url is the URL to open; may be relative or absolute
566 $sel->open_window($url, $window_id)
567 Opens a popup window (if a window with that ID isn't already
568 open).After opening the window, you'll need to select it using the
569 selectWindowcommand. This command can also be a useful workaround
570 for bug SEL-339. In some cases, Selenium will be unable to
571 intercept a call to window.open (if the call occurs during or
572 before the "onLoad" event, for example).In those cases, you can
573 force Selenium to notice the open window's name by using the
574 Selenium openWindow command, usingan empty (blank) url, like this:
575 openWindow("", "myFunnyWindow").
576 $url is the URL to open, which can be blank
578 $window_id is the JavaScript window ID of the window to select
579 $sel->select_window($window_id)
580 Selects a popup window using a window locator; once a popup window
581 has been selected, allcommands go to that window. To select the
582 main window again, use nullas the target. Window locators provide
583 different ways of specifying the window object:by title, by
584 internal JavaScript "name," or by JavaScript variable.
585 • title=My Special Window:Finds the window using the text that
587 appears in the title bar. Be careful;two windows can share the
588 same title. If that happens, this locator willjust pick one.
589 • name=myWindow:Finds the window using its internal JavaScript
591 "name" property. This is the second parameter "windowName"
592 passed to the JavaScript method window.open(url, windowName,
593 windowFeatures, replaceFlag)(which Selenium intercepts).
594 • var=variableName:Some pop-up windows are unnamed (anonymous),
596 but are associated with a JavaScript variable name in the
597 currentapplication window, e.g. "window.foo =
598 window.open(url);". In those cases, you can open the window
599 using"var=foo".
600 If no window locator prefix is provided, we'll try to guess what
602 you mean like this:
603 1.) if windowID is null, (or the string "null") then it is assumed
605 the user is referring to the original window instantiated by the
606 browser).
607 2.) if the value of the "windowID" parameter is a JavaScript
609 variable name in the current application window, then it is
610 assumedthat this variable contains the return value from a call to
611 the JavaScript window.open() method.
612 3.) Otherwise, selenium looks in a hash it maintains that maps
614 string names to window "names".
615 4.) If that fails, we'll try looping over all of the known windows
617 to try to find the appropriate "title".Since "title" is not
618 necessarily unique, this may have unexpected behavior.
619 If you're having trouble figuring out the name of a window that you
621 want to manipulate, look at the Selenium log messageswhich identify
622 the names of windows created via window.open (and therefore
623 intercepted by Selenium). You will see messageslike the following
624 for each window as it is opened:
625 "debug: window.open call intercepted; window ID (which you can use
627 with selectWindow()) is "myNewWindow""
628 In some cases, Selenium will be unable to intercept a call to
630 window.open (if the call occurs during or before the "onLoad"
631 event, for example).(This is bug SEL-339.) In those cases, you can
632 force Selenium to notice the open window's name by using the
633 Selenium openWindow command, usingan empty (blank) url, like this:
634 openWindow("", "myFunnyWindow").
635 $window_id is the JavaScript window ID of the window to select
637 $sel->select_pop_up($window_id)
638 Simplifies the process of selecting a popup window (and does not
639 offerfunctionality beyond what "selectWindow()" already provides).
640 • If "windowID" is either not specified, or specified as"null",
642 the first non-top window is selected. The top window is the
643 onethat would be selected by "selectWindow()" without providing
644 a"windowID" . This should not be used when more than one
645 popupwindow is in play.
646 • Otherwise, the window will be looked up considering"windowID"
648 as the following in order: 1) the "name" of thewindow, as
649 specified to "window.open()"; 2) a javascriptvariable which is
650 a reference to a window; and 3) the title of thewindow. This is
651 the same ordered lookup performed by"selectWindow" .
652 $window_id is an identifier for the popup window, which can take on
654 a number of different meanings
655 $sel->deselect_pop_up()
656 Selects the main window. Functionally equivalent to
657 using"selectWindow()" and specifying no value for"windowID".
658 $sel->select_frame($locator)
660 Selects a frame within the current window. (You may invoke this
661 commandmultiple times to select nested frames.) To select the
662 parent frame, use"relative=parent" as a locator; to select the top
663 frame, use "relative=top".You can also select a frame by its
664 0-based index number; select the first frame with"index=0", or the
665 third frame with "index=2". You may also use a DOM expression to
666 identify the frame you want directly,like this:
667 "dom=frames["main"].frames["subframe"]"
668 $locator is an element locator identifying a frame or iframe
670 $sel->get_whether_this_frame_match_frame_expression($current_frame_string,
671 $target)
672 Determine whether current/locator identify the frame containing
673 this running code. This is useful in proxy injection mode, where
674 this code runs in everybrowser frame and window, and sometimes the
675 selenium server needs to identifythe "current" frame. In this
676 case, when the test calls selectFrame, thisroutine is called for
677 each frame to figure out which one has been selected.The selected
678 frame will return true, while all others will return false.
679 $current_frame_string is starting frame
681 $target is new frame (which might be relative to the current one)
682 Returns true if the new frame is this code's window
683 $sel->get_whether_this_window_match_window_expression($current_window_string,
684 $target)
685 Determine whether currentWindowString plus target identify the
686 window containing this running code. This is useful in proxy
687 injection mode, where this code runs in everybrowser frame and
688 window, and sometimes the selenium server needs to identifythe
689 "current" window. In this case, when the test calls selectWindow,
690 thisroutine is called for each window to figure out which one has
691 been selected.The selected window will return true, while all
692 others will return false.
693 $current_window_string is starting window
695 $target is new window (which might be relative to the current one,
696 e.g., "_parent")
697 Returns true if the new window is this code's window
698 $sel->wait_for_pop_up($window_id, $timeout)
699 Waits for a popup window to appear and load up.
700 $window_id is the JavaScript window "name" of the window that will
702 appear (not the text of the title bar) If
703 unspecified, or specified as "null", this command will
704 wait for the first non-top window to appear (don't rely
705 on this if you are working with multiple popups
706 simultaneously).
707 $timeout is a timeout in milliseconds, after which the action will
708 return with an error. If this value is not
709 specified, the default Selenium timeout will be
710 used. See the setTimeout() command.
711 $sel->choose_cancel_on_next_confirmation()
712 By default, Selenium's overridden window.confirm() function
713 willreturn true, as if the user had manually clicked OK; after
714 runningthis command, the next call to confirm() will return false,
715 as ifthe user had clicked Cancel. Selenium will then resume using
716 thedefault behavior for future confirmations, automatically
717 returning true (OK) unless/until you explicitly call this command
718 for eachconfirmation.
719 Take note - every time a confirmation comes up, you mustconsume it
721 with a corresponding getConfirmation, or elsethe next selenium
722 operation will fail.
723 $sel->choose_ok_on_next_confirmation()
725 Undo the effect of calling chooseCancelOnNextConfirmation.
726 Notethat Selenium's overridden window.confirm() function will
727 normally automaticallyreturn true, as if the user had manually
728 clicked OK, so you shouldn'tneed to use this command unless for
729 some reason you need to changeyour mind prior to the next
730 confirmation. After any confirmation, Selenium will resume using
731 thedefault behavior for future confirmations, automatically
732 returning true (OK) unless/until you explicitly call
733 chooseCancelOnNextConfirmation for eachconfirmation.
734 Take note - every time a confirmation comes up, you mustconsume it
736 with a corresponding getConfirmation, or elsethe next selenium
737 operation will fail.
738 $sel->answer_on_next_prompt($answer)
740 Instructs Selenium to return the specified answer string in
741 response tothe next JavaScript prompt [window.prompt()].
742 $answer is the answer to give in response to the prompt pop-up
744 $sel->go_back()
745 Simulates the user clicking the "back" button on their browser.
746 $sel->refresh()
748 Simulates the user clicking the "Refresh" button on their browser.
749 $sel->close()
751 Simulates the user clicking the "close" button in the titlebar of a
752 popupwindow or tab.
753 $sel->is_alert_present()
755 Has an alert occurred? This function never throws an exception
756 Returns true if there is an alert
758 $sel->is_prompt_present()
759 Has a prompt occurred? This function never throws an exception
760 Returns true if there is a pending prompt
762 $sel->is_confirmation_present()
763 Has confirm() been called? This function never throws an exception
764 Returns true if there is a pending confirmation
766 $sel->get_alert()
767 Retrieves the message of a JavaScript alert generated during the
768 previous action, or fail if there were no alerts. Getting an alert
769 has the same effect as manually clicking OK. If analert is
770 generated but you do not consume it with getAlert, the next
771 Selenium actionwill fail.
772 Under Selenium, JavaScript alerts will NOT pop up a visible
774 alertdialog.
775 Selenium does NOT support JavaScript alerts that are generated in
777 apage's onload() event handler. In this case a visible dialog WILL
778 begenerated and Selenium will hang until someone manually clicks
779 OK.
780 Returns The message of the most recent JavaScript alert
782 $sel->get_confirmation()
783 Retrieves the message of a JavaScript confirmation dialog generated
784 duringthe previous action. By default, the confirm function will
785 return true, having the same effectas manually clicking OK. This
786 can be changed by prior execution of
787 thechooseCancelOnNextConfirmation command.
788 If an confirmation is generated but you do not consume it with
790 getConfirmation,the next Selenium action will fail.
791 NOTE: under Selenium, JavaScript confirmations will NOT pop up a
793 visibledialog.
794 NOTE: Selenium does NOT support JavaScript confirmations that
796 aregenerated in a page's onload() event handler. In this case a
797 visibledialog WILL be generated and Selenium will hang until you
798 manually clickOK.
799 Returns the message of the most recent JavaScript confirmation
801 dialog
802 $sel->get_prompt()
803 Retrieves the message of a JavaScript question prompt dialog
804 generated duringthe previous action. Successful handling of the
805 prompt requires prior execution of theanswerOnNextPrompt command.
806 If a prompt is generated but youdo not get/verify it, the next
807 Selenium action will fail.
808 NOTE: under Selenium, JavaScript prompts will NOT pop up a
810 visibledialog.
811 NOTE: Selenium does NOT support JavaScript prompts that are
813 generated in apage's onload() event handler. In this case a visible
814 dialog WILL begenerated and Selenium will hang until someone
815 manually clicks OK.
816 Returns the message of the most recent JavaScript question prompt
818 $sel->get_location()
819 Gets the absolute URL of the current page.
820 Returns the absolute URL of the current page
822 $sel->get_title()
823 Gets the title of the current page.
824 Returns the title of the current page
826 $sel->get_body_text()
827 Gets the entire text of the page.
828 Returns the entire text of the page
830 $sel->get_value($locator)
831 Gets the (whitespace-trimmed) value of an input field (or anything
832 else with a value parameter).For checkbox/radio elements, the value
833 will be "on" or "off" depending onwhether the element is checked or
834 not.
835 $locator is an element locator
837 Returns the element value, or "on/off" for checkbox/radio elements
838 $sel->get_text($locator)
839 Gets the text of an element. This works for any element that
840 containstext. This command uses either the textContent (Mozilla-
841 like browsers) orthe innerText (IE-like browsers) of the element,
842 which is the renderedtext shown to the user.
843 $locator is an element locator
845 Returns the text of the element
846 $sel->highlight($locator)
847 Briefly changes the backgroundColor of the specified element
848 yellow. Useful for debugging.
849 $locator is an element locator
851 $sel->get_eval($script)
852 Gets the result of evaluating the specified JavaScript snippet.
853 The snippet mayhave multiple lines, but only the result of the last
854 line will be returned. Note that, by default, the snippet will run
855 in the context of the "selenium"object itself, so "this" will refer
856 to the Selenium object. Use "window" torefer to the window of your
857 application, e.g. "window.document.getElementById('foo')"
858 If you need to usea locator to refer to a single element in your
860 application page, you canuse
861 "this.browserbot.findElement("id=foo")" where "id=foo" is your
862 locator.
863 $script is the JavaScript snippet to run
865 Returns the results of evaluating the snippet
866 $sel->is_checked($locator)
867 Gets whether a toggle-button (checkbox/radio) is checked. Fails if
868 the specified element doesn't exist or isn't a toggle-button.
869 $locator is an element locator pointing to a checkbox or radio
871 button
872 Returns true if the checkbox is checked, false otherwise
873 $sel->get_table($table_cell_address)
874 Gets the text from a cell of a table. The cellAddress
875 syntaxtableLocator.row.column, where row and column start at 0.
876 $table_cell_address is a cell address, e.g. "foo.1.4"
878 Returns the text from the specified cell
879 $sel->get_selected_labels($select_locator)
880 Gets all option labels (visible text) for selected options in the
881 specified select or multi-select element.
882 $select_locator is an element locator identifying a drop-down menu
884 Returns an array of all selected option labels in the specified
885 select drop-down
886 $sel->get_selected_label($select_locator)
887 Gets option label (visible text) for selected option in the
888 specified select element.
889 $select_locator is an element locator identifying a drop-down menu
891 Returns the selected option label in the specified select drop-down
892 $sel->get_selected_values($select_locator)
893 Gets all option values (value attributes) for selected options in
894 the specified select or multi-select element.
895 $select_locator is an element locator identifying a drop-down menu
897 Returns an array of all selected option values in the specified
898 select drop-down
899 $sel->get_selected_value($select_locator)
900 Gets option value (value attribute) for selected option in the
901 specified select element.
902 $select_locator is an element locator identifying a drop-down menu
904 Returns the selected option value in the specified select drop-down
905 $sel->get_selected_indexes($select_locator)
906 Gets all option indexes (option number, starting at 0) for selected
907 options in the specified select or multi-select element.
908 $select_locator is an element locator identifying a drop-down menu
910 Returns an array of all selected option indexes in the specified
911 select drop-down
912 $sel->get_selected_index($select_locator)
913 Gets option index (option number, starting at 0) for selected
914 option in the specified select element.
915 $select_locator is an element locator identifying a drop-down menu
917 Returns the selected option index in the specified select drop-down
918 $sel->get_selected_ids($select_locator)
919 Gets all option element IDs for selected options in the specified
920 select or multi-select element.
921 $select_locator is an element locator identifying a drop-down menu
923 Returns an array of all selected option IDs in the specified select
924 drop-down
925 $sel->get_selected_id($select_locator)
926 Gets option element ID for selected option in the specified select
927 element.
928 $select_locator is an element locator identifying a drop-down menu
930 Returns the selected option ID in the specified select drop-down
931 $sel->is_something_selected($select_locator)
932 Determines whether some option in a drop-down menu is selected.
933 $select_locator is an element locator identifying a drop-down menu
935 Returns true if some option has been selected, false otherwise
936 $sel->get_select_options($select_locator)
937 Gets all option labels in the specified select drop-down.
938 $select_locator is an element locator identifying a drop-down menu
940 Returns an array of all option labels in the specified select drop-
941 down
942 $sel->get_attribute($attribute_locator)
943 Gets the value of an element attribute. The value of the attribute
944 maydiffer across browsers (this is the case for the "style"
945 attribute, forexample).
946 $attribute_locator is an element locator followed by an @ sign and
948 then the name of the attribute, e.g. "foo@bar"
949 Returns the value of the specified attribute
950 $sel->is_text_present($pattern)
951 Verifies that the specified text pattern appears somewhere on the
952 rendered page shown to the user.
953 $pattern is a pattern to match with the text of the page
955 Returns true if the pattern matches the text, false otherwise
956 $sel->is_element_present($locator)
957 Verifies that the specified element is somewhere on the page.
958 $locator is an element locator
960 Returns true if the element is present, false otherwise
961 $sel->is_visible($locator)
962 Determines if the specified element is visible. Anelement can be
963 rendered invisible by setting the CSS "visibility"property to
964 "hidden", or the "display" property to "none", either for
965 theelement itself or one if its ancestors. This method will fail
966 ifthe element is not present.
967 $locator is an element locator
969 Returns true if the specified element is visible, false otherwise
970 $sel->is_editable($locator)
971 Determines whether the specified input element is editable, ie
972 hasn't been disabled.This method will fail if the specified element
973 isn't an input element.
974 $locator is an element locator
976 Returns true if the input element is editable, false otherwise
977 $sel->get_all_buttons()
978 Returns the IDs of all buttons on the page. If a given button has
979 no ID, it will appear as "" in this array.
980 Returns the IDs of all buttons on the page
982 $sel->get_all_links()
983 Returns the IDs of all links on the page. If a given link has no
984 ID, it will appear as "" in this array.
985 Returns the IDs of all links on the page
987 $sel->get_all_fields()
988 Returns the IDs of all input fields on the page. If a given field
989 has no ID, it will appear as "" in this array.
990 Returns the IDs of all field on the page
992 $sel->get_attribute_from_all_windows($attribute_name)
993 Returns an array of JavaScript property values from all known
994 windows having one.
995 $attribute_name is name of an attribute on the windows
997 Returns the set of values of this attribute from all known windows.
998 $sel->dragdrop($locator, $movements_string)
999 deprecated - use dragAndDrop instead
1000 $locator is an element locator
1002 $movements_string is offset in pixels from the current location to
1003 which the element should be moved, e.g., "+70,-300"
1004 $sel->set_mouse_speed($pixels)
1005 Configure the number of pixels between "mousemove" events during
1006 dragAndDrop commands (default=10). Setting this value to 0 means
1007 that we'll send a "mousemove" event to every single pixelin between
1008 the start location and the end location; that can be very slow, and
1009 maycause some browsers to force the JavaScript to timeout.
1010 If the mouse speed is greater than the distance between the two
1012 dragged objects, we'lljust send one "mousemove" at the start
1013 location and then one final one at the end location.
1014 $pixels is the number of pixels between "mousemove" events
1016 $sel->get_mouse_speed()
1017 Returns the number of pixels between "mousemove" events during
1018 dragAndDrop commands (default=10).
1019 Returns the number of pixels between "mousemove" events during
1021 dragAndDrop commands (default=10)
1022 $sel->drag_and_drop($locator, $movements_string)
1023 Drags an element a certain distance and then drops it
1024 $locator is an element locator
1026 $movements_string is offset in pixels from the current location to
1027 which the element should be moved, e.g., "+70,-300"
1028 $sel->drag_and_drop_to_object($locator_of_object_to_be_dragged,
1029 $locator_of_drag_destination_object)
1030 Drags an element and drops it on another element
1031 $locator_of_object_to_be_dragged is an element to be dragged
1033 $locator_of_drag_destination_object is an element whose location
1034 (i.e., whose center-most pixel) will be the point where
1035 locatorOfObjectToBeDragged is dropped
1036 $sel->window_focus()
1037 Gives focus to the currently selected window
1038 $sel->window_maximize()
1040 Resize currently selected window to take up the entire screen
1041 $sel->get_all_window_ids()
1043 Returns the IDs of all windows that the browser knows about in an
1044 array.
1045 Returns Array of identifiers of all windows that the browser knows
1047 about.
1048 $sel->get_all_window_names()
1049 Returns the names of all windows that the browser knows about in an
1050 array.
1051 Returns Array of names of all windows that the browser knows about.
1053 $sel->get_all_window_titles()
1054 Returns the titles of all windows that the browser knows about in
1055 an array.
1056 Returns Array of titles of all windows that the browser knows
1058 about.
1059 $sel->get_html_source()
1060 Returns the entire HTML source between the opening andclosing
1061 "html" tags.
1062 Returns the entire HTML source
1064 $sel->set_cursor_position($locator, $position)
1065 Moves the text cursor to the specified position in the given input
1066 element or textarea.This method will fail if the specified element
1067 isn't an input element or textarea.
1068 $locator is an element locator pointing to an input element or
1070 textarea
1071 $position is the numerical position of the cursor in the field;
1072 position should be 0 to move the position to the beginning of the
1073 field. You can also set the cursor to -1 to move it to the end of
1074 the field.
1075 $sel->get_element_index($locator)
1076 Get the relative index of an element to its parent (starting from
1077 0). The comment node and empty text nodewill be ignored.
1078 $locator is an element locator pointing to an element
1080 Returns of relative index of the element to its parent (starting
1081 from 0)
1082 $sel->is_ordered($locator1, $locator2)
1083 Check if these two elements have same parent and are ordered
1084 siblings in the DOM. Two same elements willnot be considered
1085 ordered.
1086 $locator1 is an element locator pointing to the first element
1088 $locator2 is an element locator pointing to the second element
1089 Returns true if element1 is the previous sibling of element2, false
1090 otherwise
1091 $sel->get_element_position_left($locator)
1092 Retrieves the horizontal position of an element
1093 $locator is an element locator pointing to an element OR an element
1095 itself
1096 Returns of pixels from the edge of the frame.
1097 $sel->get_element_position_top($locator)
1098 Retrieves the vertical position of an element
1099 $locator is an element locator pointing to an element OR an element
1101 itself
1102 Returns of pixels from the edge of the frame.
1103 $sel->get_element_width($locator)
1104 Retrieves the width of an element
1105 $locator is an element locator pointing to an element
1107 Returns width of an element in pixels
1108 $sel->get_element_height($locator)
1109 Retrieves the height of an element
1110 $locator is an element locator pointing to an element
1112 Returns height of an element in pixels
1113 $sel->get_cursor_position($locator)
1114 Retrieves the text cursor position in the given input element or
1115 textarea; beware, this may not work perfectly on all browsers.
1116 Specifically, if the cursor/selection has been cleared by
1117 JavaScript, this command will tend toreturn the position of the
1118 last location of the cursor, even though the cursor is now gone
1119 from the page. This is filed as
1120 http://jira.openqa.org/browse/SEL-243 (SEL-243). This method will
1121 fail if the specified element isn't an input element or textarea,
1122 or there is no cursor in the element.
1123 $locator is an element locator pointing to an input element or
1125 textarea
1126 Returns the numerical position of the cursor in the field
1127 $sel->get_expression($expression)
1128 Returns the specified expression. This is useful because of
1129 JavaScript preprocessing.It is used to generate commands like
1130 assertExpression and waitForExpression.
1131 $expression is the value to return
1133 Returns the value passed in
1134 $sel->get_xpath_count($xpath)
1135 Returns the number of nodes that match the specified xpath, eg.
1136 "//table" would givethe number of tables.
1137 $xpath is the xpath expression to evaluate. do NOT wrap this
1139 expression in a 'count()' function; we will do that for you.
1140 Returns the number of nodes that match the specified xpath
1141 $sel->assign_id($locator, $identifier)
1142 Temporarily sets the "id" attribute of the specified element, so
1143 you can locate it in the futureusing its ID rather than a
1144 slow/complicated XPath. This ID will disappear once the page
1145 isreloaded.
1146 $locator is an element locator pointing to an element
1148 $identifier is a string to be used as the ID of the specified
1149 element
1150 $sel->allow_native_xpath($allow)
1151 Specifies whether Selenium should use the native in-browser
1152 implementationof XPath (if any native version is available); if you
1153 pass "false" tothis function, we will always use our pure-
1154 JavaScript xpath library.Using the pure-JS xpath library can
1155 improve the consistency of xpathelement locators between different
1156 browser vendors, but the pure-JSversion is much slower than the
1157 native implementations.
1158 $allow is boolean, true means we'll prefer to use native XPath;
1160 false means we'll only use JS XPath
1161 $sel->ignore_attributes_without_value($ignore)
1162 Specifies whether Selenium will ignore xpath attributes that have
1163 novalue, i.e. are the empty string, when using the non-native
1164 xpathevaluation engine. You'd want to do this for performance
1165 reasons in IE.However, this could break certain xpaths, for example
1166 an xpath that looksfor an attribute whose value is NOT the empty
1167 string.The hope is that such xpaths are relatively rare, but the
1168 user shouldhave the option of using them. Note that this only
1169 influences xpathevaluation when using the ajaxslt engine (i.e. not
1170 "javascript-xpath").
1171 $ignore is boolean, true means we'll ignore attributes without
1173 value at the expense of xpath "correctness"; false means we'll
1174 sacrifice speed for correctness.
1175 $sel->wait_for_condition($script, $timeout)
1176 Runs the specified JavaScript snippet repeatedly until it evaluates
1177 to "true".The snippet may have multiple lines, but only the result
1178 of the last linewill be considered. Note that, by default, the
1179 snippet will be run in the runner's test window, not in the
1180 windowof your application. To get the window of your application,
1181 you can usethe JavaScript snippet
1182 "selenium.browserbot.getCurrentWindow()", and thenrun your
1183 JavaScript in there
1184 $script is the JavaScript snippet to run
1186 $timeout is a timeout in milliseconds, after which this command
1187 will return with an error
1188 $sel->set_timeout($timeout)
1189 Specifies the amount of time that Selenium will wait for actions to
1190 complete. Actions that require waiting include "open" and the
1191 "waitFor*" actions. The default timeout is 30 seconds.
1192 $timeout is a timeout in milliseconds, after which the action will
1194 return with an error
1195 $sel->wait_for_page_to_load($timeout)
1196 Waits for a new page to load. You can use this command instead of
1197 the "AndWait" suffixes, "clickAndWait", "selectAndWait",
1198 "typeAndWait" etc.(which are only available in the JS API).
1199 Selenium constantly keeps track of new pages loading, and sets a
1201 "newPageLoaded"flag when it first notices a page load. Running any
1202 other Selenium command afterturns the flag to false. Hence, if you
1203 want to wait for a page to load, you mustwait immediately after a
1204 Selenium command that caused a page-load.
1205 $timeout is a timeout in milliseconds, after which this command
1207 will return with an error
1208 $sel->wait_for_frame_to_load($frame_address, $timeout)
1209 Waits for a new frame to load. Selenium constantly keeps track of
1210 new pages and frames loading, and sets a "newPageLoaded" flag when
1211 it first notices a page load. See waitForPageToLoad for more
1212 information.
1213 $frame_address is FrameAddress from the server side
1215 $timeout is a timeout in milliseconds, after which this command
1216 will return with an error
1217 $sel->get_cookie()
1218 Return all cookies of the current page under test.
1219 Returns all cookies of the current page under test
1221 $sel->get_cookie_by_name($name)
1222 Returns the value of the cookie with the specified name, or throws
1223 an error if the cookie is not present.
1224 $name is the name of the cookie
1226 Returns the value of the cookie
1227 $sel->is_cookie_present($name)
1228 Returns true if a cookie with the specified name is present, or
1229 false otherwise.
1230 $name is the name of the cookie
1232 Returns true if a cookie with the specified name is present, or
1233 false otherwise.
1234 $sel->create_cookie($name_value_pair, $options_string)
1235 Create a new cookie whose path and domain are same with those of
1236 current pageunder test, unless you specified a path for this cookie
1237 explicitly.
1238 $name_value_pair is name and value of the cookie in a format
1240 "name=value"
1241 $options_string is options for the cookie. Currently supported
1242 options include 'path', 'max_age' and 'domain'. the
1243 optionsString's format is "path=/path/, max_age=60,
1244 domain=.foo.com". The order of options are irrelevant, the unit
1245 of the value of 'max_age' is second. Note that specifying a domain
1246 that isn't a subset of the current domain will usually fail.
1247 $sel->delete_cookie($name, $options_string)
1248 Delete a named cookie with specified path and domain. Be careful;
1249 to delete a cookie, youneed to delete it using the exact same path
1250 and domain that were used to create the cookie.If the path is
1251 wrong, or the domain is wrong, the cookie simply won't be deleted.
1252 Alsonote that specifying a domain that isn't a subset of the
1253 current domain will usually fail.Since there's no way to discover
1254 at runtime the original path and domain of a given cookie,we've
1255 added an option called 'recurse' to try all sub-domains of the
1256 current domain withall paths that are a subset of the current path.
1257 Beware; this option can be slow. Inbig-O notation, it operates in
1258 O(n*m) time, where n is the number of dots in the domainname and m
1259 is the number of slashes in the path.
1260 $name is the name of the cookie to be deleted
1262 $options_string is options for the cookie. Currently supported
1263 options include 'path', 'domain' and 'recurse.' The
1264 optionsString's format is "path=/path/, domain=.foo.com,
1265 recurse=true". The order of options are irrelevant. Note that
1266 specifying a domain that isn't a subset of the current domain
1267 will usually fail.
1268 $sel->delete_all_visible_cookies()
1269 Calls deleteCookie with recurse=true on all cookies visible to the
1270 current page.As noted on the documentation for deleteCookie,
1271 recurse=true can be much slowerthan simply deleting the cookies
1272 using a known domain/path.
1273 $sel->set_browser_log_level($log_level)
1275 Sets the threshold for browser-side logging messages; log messages
1276 beneath this threshold will be discarded.Valid logLevel strings
1277 are: "debug", "info", "warn", "error" or "off".To see the browser
1278 logs, you need toeither show the log window in GUI mode, or enable
1279 browser-side logging in Selenium RC.
1280 $log_level is one of the following: "debug", "info", "warn",
1282 "error" or "off"
1283 $sel->run_script($script)
1284 Creates a new "script" tag in the body of the current test window,
1285 and adds the specified text into the body of the command. Scripts
1286 run inthis way can often be debugged more easily than scripts
1287 executed usingSelenium's "getEval" command. Beware that JS
1288 exceptions thrown in these scripttags aren't managed by Selenium,
1289 so you should probably wrap your scriptin try/catch blocks if there
1290 is any chance that the script will throwan exception.
1291 $script is the JavaScript snippet to run
1293 $sel->add_location_strategy($strategy_name)
1294 Defines a new function for Selenium to locate elements on the
1295 page.For example,if you define the strategy "foo", and someone runs
1296 click("foo=blah"), we'llrun your function, passing you the string
1297 "blah", and click on the element that your functionreturns, or
1298 throw an "Element not found" error if your function returns
1299 null.We'll pass three arguments to your function:
1300 • locator: the string the user passed in
1302 • inWindow: the currently selected window
1304 • inDocument: the currently selected document
1306 The function must return null if the element can't be found.
1308 $strategy_name is the name of the strategy to define; this should
1310 use only letters [a-zA-Z] with no spaces or other punctuation.
1311 $sel->capture_entire_page_screenshot($filename, $kwargs)
1312 Saves the entire contents of the current window canvas to a PNG
1313 file.Contrast this with the captureScreenshot command, which
1314 captures thecontents of the OS viewport (i.e. whatever is currently
1315 being displayedon the monitor), and is implemented in the RC only.
1316 Currently this onlyworks in Firefox when running in chrome mode,
1317 and in IE non-HTA usingthe EXPERIMENTAL "Snapsie" utility. The
1318 Firefox implementation is mostlyborrowed from the Screengrab!
1319 Firefox extension. Please seehttp://www.screengrab.org and
1320 http://snapsie.sourceforge.net/ fordetails.
1321 $filename is the path to the file to persist the screenshot as. No
1323 filename extension will be appended by default. Directories will
1324 not be created if they do not exist, and an exception will be
1325 thrown, possibly by native code.
1326 $kwargs is a kwargs string that modifies the way the screenshot is
1327 captured. Example: "background=#CCFFDD". Currently valid options:
1328 background the background CSS for the HTML document. This may
1329 be useful to set for capturing screenshots of less-than-ideal
1330 layouts, for example where absolute positioning causes the
1331 calculation of the canvas dimension to fail and a black
1332 background is exposed (possibly obscuring black text).
1333 $sel->rollup($rollup_name, $kwargs)
1334 Executes a command rollup, which is a series of commands with a
1335 uniquename, and optionally arguments that control the generation of
1336 the set ofcommands. If any one of the rolled-up commands fails, the
1337 rollup isconsidered to have failed. Rollups may also contain nested
1338 rollups.
1339 $rollup_name is the name of the rollup command
1341 $kwargs is keyword arguments string that influences how the rollup
1342 expands into commands
1343 $sel->add_script($script_content, $script_tag_id)
1344 Loads script content into a new script tag in the Selenium
1345 document. Thisdiffers from the runScript command in that runScript
1346 adds the script tagto the document of the AUT, not the Selenium
1347 document. The followingentities in the script content are replaced
1348 by the characters they represent: < > &The corresponding
1349 remove command is removeScript.
1350 $script_content is the Javascript content of the script to add
1352 $script_tag_id is (optional) the id of the new script tag. If
1353 specified, and an element with this id already exists, this
1354 operation will fail.
1355 $sel->remove_script($script_tag_id)
1356 Removes a script tag from the Selenium document identified by the
1357 givenid. Does nothing if the referenced tag doesn't exist.
1358 $script_tag_id is the id of the script element to remove.
1360 $sel->use_xpath_library($library_name)
1361 Allows choice of one of the available libraries.
1362 $library_name is name of the desired library Only the following
1364 three can be chosen:
1365 • "ajaxslt" - Google's library
1366 • "javascript-xpath" - Cybozu Labs' faster library
1368 • "default" - The default library. Currently the default
1370 library is "ajaxslt" .
1371 If libraryName isn't one of these three, then no change will be made.
1373 $sel->set_context($context)
1375 Writes a message to the status bar and adds a note to the browser-
1376 sidelog.
1377 $context is the message to be sent to the browser
1379 $sel->attach_file($field_locator, $file_locator)
1380 Sets a file input (upload) field to the file listed in fileLocator
1381 $field_locator is an element locator
1383 $file_locator is a URL pointing to the specified file. Before the
1384 file can be set in the input field (fieldLocator), Selenium RC may
1385 need to transfer the file to the local machine before attaching the
1386 file in a web page form. This is common in selenium grid
1387 configurations where the RC server driving the browser is not the
1388 same machine that started the test. Supported Browsers: Firefox
1389 ("*chrome") only.
1390 $sel->capture_screenshot($filename)
1391 Captures a PNG screenshot to the specified file.
1392 $filename is the absolute path to the file to be written, e.g.
1394 "c:\blah\screenshot.png"
1395 $sel->capture_screenshot_to_string()
1396 Capture a PNG screenshot. It then returns the file as a base 64
1397 encoded string.
1398 Returns The base 64 encoded string of the screen shot (PNG file)
1400 $sel->capture_entire_page_screenshot_to_string($kwargs)
1401 Downloads a screenshot of the browser current window canvas to a
1402 based 64 encoded PNG file. The entire windows canvas is
1403 captured,including parts rendered outside of the current view
1404 port.Currently this only works in Mozilla and when running in
1405 chrome mode.
1406 $kwargs is A kwargs string that modifies the way the screenshot is
1408 captured. Example: "background=#CCFFDD". This may be useful to set
1409 for capturing screenshots of less-than-ideal layouts, for example
1410 where absolute positioning causes the calculation of the canvas
1411 dimension to fail and a black background is exposed (possibly
1412 obscuring black text).
1413 Returns The base 64 encoded string of the page screenshot (PNG
1414 file)
1415 $sel->shut_down_selenium_server()
1416 Kills the running Selenium Server and all browser sessions. After
1417 you run this command, you will no longer be able to sendcommands to
1418 the server; you can't remotely start the server once it has been
1419 stopped. Normallyyou should prefer to run the "stop" command,
1420 which terminates the current browser session, rather than shutting
1421 down the entire server.
1422 $sel->retrieve_last_remote_control_logs()
1424 Retrieve the last messages logged on a specific remote control.
1425 Useful for error reports, especiallywhen running multiple remote
1426 controls in a distributed environment. The maximum number of log
1427 messagesthat can be retrieve is configured on remote control
1428 startup.
1429 Returns The last N log messages as a multi-line string.
1431 $sel->key_down_native($keycode)
1432 Simulates a user pressing a key (without releasing it yet) by
1433 sending a native operating system keystroke.This function uses the
1434 java.awt.Robot class to send a keystroke; this more accurately
1435 simulates typinga key on the keyboard. It does not honor settings
1436 from the shiftKeyDown, controlKeyDown, altKeyDown andmetaKeyDown
1437 commands, and does not target any particular HTML element. To send
1438 a keystroke to a particularelement, focus on the element first
1439 before running this command.
1440 $keycode is an integer keycode number corresponding to a
1442 java.awt.event.KeyEvent; note that Java keycodes are NOT the same
1443 thing as JavaScript keycodes!
1444 $sel->key_up_native($keycode)
1445 Simulates a user releasing a key by sending a native operating
1446 system keystroke.This function uses the java.awt.Robot class to
1447 send a keystroke; this more accurately simulates typinga key on the
1448 keyboard. It does not honor settings from the shiftKeyDown,
1449 controlKeyDown, altKeyDown andmetaKeyDown commands, and does not
1450 target any particular HTML element. To send a keystroke to a
1451 particularelement, focus on the element first before running this
1452 command.
1453 $keycode is an integer keycode number corresponding to a
1455 java.awt.event.KeyEvent; note that Java keycodes are NOT the same
1456 thing as JavaScript keycodes!
1457 $sel->key_press_native($keycode)
1458 Simulates a user pressing and releasing a key by sending a native
1459 operating system keystroke.This function uses the java.awt.Robot
1460 class to send a keystroke; this more accurately simulates typinga
1461 key on the keyboard. It does not honor settings from the
1462 shiftKeyDown, controlKeyDown, altKeyDown andmetaKeyDown commands,
1463 and does not target any particular HTML element. To send a
1464 keystroke to a particularelement, focus on the element first before
1465 running this command.
1466 $keycode is an integer keycode number corresponding to a
1468 java.awt.event.KeyEvent; note that Java keycodes are NOT the same
1469 thing as JavaScript keycodes!
1470 $sel->wait_for_text_present($text, $timeout)
1471 Waits until $text is present in the html source
1472 $sel->wait_for_element_present($locator, $timeout)
1474 Waits until $locator is present
1475 $sel->is_location($expected_location)
1477 Verify the location of the current page ends with the expected
1478 location. If an URL querystring is provided, this is checked as
1479 well.
1480 $expected_location is the location to match.
1482 Note: This function is deprecated, use get_location() instead.
1484 $sel->get_checked($locator)
1486 Gets whether a toggle-button (checkbox/radio) is checked. Fails if
1487 the specified element doesn't exist or isn't a toggle-button.
1488 $locator is an element locator pointing to a checkbox or radio
1490 button.
1491 Note: This function is deprecated, use is_checked() instead.
1493 $sel->is_selected($locator, $option_locator)
1495 Verifies that the selected option of a drop-down satisfies the
1496 optionSpecifier.
1497 See the select command for more information about option locators.
1499 $locator is an element locator.
1501 $option_locator is an option locator, typically just an option
1502 label (e.g. "John Smith").
1503 Note: This function is deprecated, use the get_selected_*() methods
1505 instead.
1506 $sel->get_selected_options($locator)
1508 Gets all option labels for selected options in the specified select
1509 or multi-select element.
1510 $locator is an element locator.
1512 Note: This function is deprecated, use get_selected_labels()
1514 instead.
1515 $sel->get_absolute_location()
1517 Gets the absolute URL of the current page.
1518 Note: This function is deprecated, use get_location() instead.
1520
1522 WWW::Selenium - Perl Client for the Selenium Remote Control test tool
1523
1525 For more information about Selenium Remote Control, visit the website
1526 at <http://www.openqa.org/selenium-rc/>.
1527 Selenium Remote Control maintained by Dan Fabulich
1529 <dfabulich@warpmail.net>
1530
1532 The Selenium Remote Control JIRA issue tracking system is available
1533 online at <http://jira.openqa.org/browse/SRC>.
1534
1536 • Maintained by: Matt Phillips <mattp@cpan.org>, Luke Closs
1537 <lukec@cpan.org>
1538 • Originally by Mattia Barbon <mbarbon@cpan.org>
1540
1542 This software is Copyright (c) 2006 by ThoughtWorks, Inc.
1543 This is free software, licensed under:
1545 The Apache License, Version 2.0, January 2004
1547perl v5.32.1 2021-01-27 WWW::Selenium(3)