Back to index

plone3  3.1.7
selenium.py
Go to the documentation of this file.
00001 
00002 """
00003 Copyright 2006 ThoughtWorks, Inc.
00004 
00005 Licensed under the Apache License, Version 2.0 (the "License");
00006 you may not use this file except in compliance with the License.
00007 You may obtain a copy of the License at
00008 
00009     http://www.apache.org/licenses/LICENSE-2.0
00010 
00011 Unless required by applicable law or agreed to in writing, software
00012 distributed under the License is distributed on an "AS IS" BASIS,
00013 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014 See the License for the specific language governing permissions and
00015 limitations under the License.
00016 """
00017 __docformat__ = "restructuredtext en"
00018 
00019 # This file has been automatically generated via XSL
00020 
00021 import httplib
00022 import urllib
00023 import re
00024 
00025 class selenium:
00026     """
00027 Defines an object that runs Selenium commands.
00028     
00029     Element Locators
00030     ~~~~~~~~~~~~~~~~
00031     Element Locators tell Selenium which HTML element a command refers to.
00032     The format of a locator is:
00033     \ *locatorType*\ **=**\ \ *argument*
00034     We support the following strategies for locating elements:
00035     
00036     *    \ **identifier**\ =\ *id*
00037         Select the element with the specified @id attribute. If no match is
00038         found, select the first element whose @name attribute is \ *id*.
00039         (This is normally the default; see below.)
00040     *    \ **id**\ =\ *id*
00041         Select the element with the specified @id attribute.
00042     *    \ **name**\ =\ *name*
00043         Select the first element with the specified @name attribute.
00044     
00045         *    username
00046         *    name=username
00047         
00048         
00049     
00050         The name may optionally be followed by one or more \ *element-filters*, separated from the name by whitespace.  If the \ *filterType* is not specified, \ **value**\  is assumed.
00051     
00052         *    name=flavour value=chocolate
00053         
00054         
00055     *    \ **dom**\ =\ *javascriptExpression*
00056         
00057             Find an element by evaluating the specified string.  This allows you to traverse the HTML Document Object
00058             Model using JavaScript.  Note that you must not return a value in this string; simply make it the last expression in the block.
00059             *    dom=document.forms['myForm'].myDropdown
00060             *    dom=document.images[56]
00061             *    dom=function foo() { return document.links[1]; }; foo();
00062             
00063             
00064         
00065     *    \ **xpath**\ =\ *xpathExpression*
00066         Locate an element using an XPath expression.
00067         *    xpath=//img[@alt='The image alt text']
00068         *    xpath=//table[@id='table1']//tr[4]/td[2]
00069         
00070         
00071     *    \ **link**\ =\ *textPattern*
00072         Select the link (anchor) element which contains text matching the
00073         specified \ *pattern*.
00074         *    link=The link text
00075         
00076         
00077     *    \ **css**\ =\ *cssSelectorSyntax*
00078         Select the element using css selectors. Please refer to CSS2 selectors, CSS3 selectors for more information. You can also check the TestCssLocators test in the selenium test suite for an example of usage, which is included in the downloaded selenium core package.
00079         *    css=a[href="#id3"]
00080         *    css=span#firstChild + span
00081         
00082         
00083     
00084         Currently the css selector locator supports all css1, css2 and css3 selectors except namespace in css3, some pseudo classes(:nth-of-type, :nth-last-of-type, :first-of-type, :last-of-type, :only-of-type, :visited, :hover, :active, :focus, :indeterminate) and pseudo elements(::first-line, ::first-letter, ::selection, ::before, ::after). 
00085     
00086     
00087     Without an explicit locator prefix, Selenium uses the following default
00088     strategies:
00089     
00090     *    \ **dom**\ , for locators starting with "document."
00091     *    \ **xpath**\ , for locators starting with "//"
00092     *    \ **identifier**\ , otherwise
00093     
00094     Element Filters
00095     ~~~~~~~~~~~~~~~Element filters can be used with a locator to refine a list of candidate elements.  They are currently used only in the 'name' element-locator.
00096     Filters look much like locators, ie.
00097     \ *filterType*\ **=**\ \ *argument*Supported element-filters are:
00098     \ **value=**\ \ *valuePattern*
00099     
00100     Matches elements based on their values.  This is particularly useful for refining a list of similarly-named toggle-buttons.\ **index=**\ \ *index*
00101     
00102     Selects a single element based on its position in the list (offset from zero).String-match Patterns
00103     ~~~~~~~~~~~~~~~~~~~~~
00104     Various Pattern syntaxes are available for matching string values:
00105     
00106     *    \ **glob:**\ \ *pattern*
00107         Match a string against a "glob" (aka "wildmat") pattern. "Glob" is a
00108         kind of limited regular-expression syntax typically used in command-line
00109         shells. In a glob pattern, "*" represents any sequence of characters, and "?"
00110         represents any single character. Glob patterns match against the entire
00111         string.
00112     *    \ **regexp:**\ \ *regexp*
00113         Match a string using a regular-expression. The full power of JavaScript
00114         regular-expressions is available.
00115     *    \ **exact:**\ \ *string*
00116         Match a string exactly, verbatim, without any of that fancy wildcard
00117         stuff.
00118     
00119     
00120     If no pattern prefix is specified, Selenium assumes that it's a "glob"
00121     pattern.
00122     
00123     
00124     """
00125 
00126 ### This part is hard-coded in the XSL
00127     def __init__(self, host, port, browserStartCommand, browserURL):
00128         self.host = host
00129         self.port = port
00130         self.browserStartCommand = browserStartCommand
00131         self.browserURL = browserURL
00132         self.sessionId = None
00133 
00134     def start(self):
00135         result = self.get_string("getNewBrowserSession", [self.browserStartCommand, self.browserURL])
00136         try:
00137             self.sessionId = long(result)
00138         except ValueError:
00139             raise Exception, result
00140         
00141     def stop(self):
00142         self.do_command("testComplete", [])
00143         self.sessionId = None
00144 
00145     def do_command(self, verb, args):
00146         conn = httplib.HTTPConnection(self.host, self.port)
00147         commandString = u'/selenium-server/driver/?cmd=' + urllib.quote_plus(unicode(verb).encode('utf-8'))
00148         for i in range(len(args)):
00149             commandString = commandString + '&' + unicode(i+1) + '=' + urllib.quote_plus(unicode(args[i]).encode('utf-8'))
00150         if (None != self.sessionId):
00151             commandString = commandString + "&sessionId=" + unicode(self.sessionId)
00152         conn.request("GET", commandString)
00153     
00154         response = conn.getresponse()
00155         #print response.status, response.reason
00156         data = unicode(response.read(), "UTF-8")
00157         result = response.reason
00158         #print "Selenium Result: " + repr(data) + "\n\n"
00159         if (not data.startswith('OK')):
00160             raise Exception, data
00161         return data
00162     
00163     def get_string(self, verb, args):
00164         result = self.do_command(verb, args)
00165         return result[3:]
00166     
00167     def get_string_array(self, verb, args):
00168         csv = self.get_string(verb, args)
00169         token = ""
00170         tokens = []
00171         escape = False
00172         for i in range(len(csv)):
00173             letter = csv[i]
00174             if (escape):
00175                 token = token + letter
00176                 escape = False
00177                 continue
00178             if (letter == '\\'):
00179                 escape = True
00180             elif (letter == ','):
00181                 tokens.append(token)
00182                 token = ""
00183             else:
00184                 token = token + letter
00185         tokens.append(token)
00186         return tokens
00187 
00188     def get_number(self, verb, args):
00189         # Is there something I need to do here?
00190         return self.get_string(verb, args)
00191     
00192     def get_number_array(self, verb, args):
00193         # Is there something I need to do here?
00194         return self.get_string_array(verb, args)
00195 
00196     def get_boolean(self, verb, args):
00197         boolstr = self.get_string(verb, args)
00198         if ("true" == boolstr):
00199             return True
00200         if ("false" == boolstr):
00201             return False
00202         raise ValueError, "result is neither 'true' nor 'false': " + boolstr
00203     
00204     def get_boolean_array(self, verb, args):
00205         boolarr = self.get_string_array(verb, args)
00206         for i in range(len(boolarr)):
00207             if ("true" == boolstr):
00208                 boolarr[i] = True
00209                 continue
00210             if ("false" == boolstr):
00211                 boolarr[i] = False
00212                 continue
00213             raise ValueError, "result is neither 'true' nor 'false': " + boolarr[i]
00214         return boolarr
00215     
00216     
00217 
00218 ### From here on, everything's auto-generated from XML
00219 
00220 
00221     def click(self,locator):
00222         """
00223         Clicks on a link, button, checkbox or radio button. If the click action
00224         causes a new page to load (like a link usually does), call
00225         waitForPageToLoad.
00226         
00227         'locator' is an element locator
00228         """
00229         self.do_command("click", [locator,])
00230 
00231 
00232     def double_click(self,locator):
00233         """
00234         Double clicks on a link, button, checkbox or radio button. If the double click action
00235         causes a new page to load (like a link usually does), call
00236         waitForPageToLoad.
00237         
00238         'locator' is an element locator
00239         """
00240         self.do_command("doubleClick", [locator,])
00241 
00242 
00243     def click_at(self,locator,coordString):
00244         """
00245         Clicks on a link, button, checkbox or radio button. If the click action
00246         causes a new page to load (like a link usually does), call
00247         waitForPageToLoad.
00248         
00249         'locator' is an element locator
00250         'coordString' is specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.
00251         """
00252         self.do_command("clickAt", [locator,coordString,])
00253 
00254 
00255     def double_click_at(self,locator,coordString):
00256         """
00257         Doubleclicks on a link, button, checkbox or radio button. If the action
00258         causes a new page to load (like a link usually does), call
00259         waitForPageToLoad.
00260         
00261         'locator' is an element locator
00262         'coordString' is specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.
00263         """
00264         self.do_command("doubleClickAt", [locator,coordString,])
00265 
00266 
00267     def fire_event(self,locator,eventName):
00268         """
00269         Explicitly simulate an event, to trigger the corresponding "on\ *event*"
00270         handler.
00271         
00272         'locator' is an element locator
00273         'eventName' is the event name, e.g. "focus" or "blur"
00274         """
00275         self.do_command("fireEvent", [locator,eventName,])
00276 
00277 
00278     def key_press(self,locator,keySequence):
00279         """
00280         Simulates a user pressing and releasing a key.
00281         
00282         'locator' is an element locator
00283         'keySequence' is Either be a string("\" followed by the numeric keycode  of the key to be pressed, normally the ASCII value of that key), or a single  character. For example: "w", "\119".
00284         """
00285         self.do_command("keyPress", [locator,keySequence,])
00286 
00287 
00288     def shift_key_down(self):
00289         """
00290         Press the shift key and hold it down until doShiftUp() is called or a new page is loaded.
00291         
00292         """
00293         self.do_command("shiftKeyDown", [])
00294 
00295 
00296     def shift_key_up(self):
00297         """
00298         Release the shift key.
00299         
00300         """
00301         self.do_command("shiftKeyUp", [])
00302 
00303 
00304     def meta_key_down(self):
00305         """
00306         Press the meta key and hold it down until doMetaUp() is called or a new page is loaded.
00307         
00308         """
00309         self.do_command("metaKeyDown", [])
00310 
00311 
00312     def meta_key_up(self):
00313         """
00314         Release the meta key.
00315         
00316         """
00317         self.do_command("metaKeyUp", [])
00318 
00319 
00320     def alt_key_down(self):
00321         """
00322         Press the alt key and hold it down until doAltUp() is called or a new page is loaded.
00323         
00324         """
00325         self.do_command("altKeyDown", [])
00326 
00327 
00328     def alt_key_up(self):
00329         """
00330         Release the alt key.
00331         
00332         """
00333         self.do_command("altKeyUp", [])
00334 
00335 
00336     def control_key_down(self):
00337         """
00338         Press the control key and hold it down until doControlUp() is called or a new page is loaded.
00339         
00340         """
00341         self.do_command("controlKeyDown", [])
00342 
00343 
00344     def control_key_up(self):
00345         """
00346         Release the control key.
00347         
00348         """
00349         self.do_command("controlKeyUp", [])
00350 
00351 
00352     def key_down(self,locator,keySequence):
00353         """
00354         Simulates a user pressing a key (without releasing it yet).
00355         
00356         'locator' is an element locator
00357         'keySequence' is Either be a string("\" followed by the numeric keycode  of the key to be pressed, normally the ASCII value of that key), or a single  character. For example: "w", "\119".
00358         """
00359         self.do_command("keyDown", [locator,keySequence,])
00360 
00361 
00362     def key_up(self,locator,keySequence):
00363         """
00364         Simulates a user releasing a key.
00365         
00366         'locator' is an element locator
00367         'keySequence' is Either be a string("\" followed by the numeric keycode  of the key to be pressed, normally the ASCII value of that key), or a single  character. For example: "w", "\119".
00368         """
00369         self.do_command("keyUp", [locator,keySequence,])
00370 
00371 
00372     def mouse_over(self,locator):
00373         """
00374         Simulates a user hovering a mouse over the specified element.
00375         
00376         'locator' is an element locator
00377         """
00378         self.do_command("mouseOver", [locator,])
00379 
00380 
00381     def mouse_out(self,locator):
00382         """
00383         Simulates a user moving the mouse pointer away from the specified element.
00384         
00385         'locator' is an element locator
00386         """
00387         self.do_command("mouseOut", [locator,])
00388 
00389 
00390     def mouse_down(self,locator):
00391         """
00392         Simulates a user pressing the mouse button (without releasing it yet) on
00393         the specified element.
00394         
00395         'locator' is an element locator
00396         """
00397         self.do_command("mouseDown", [locator,])
00398 
00399 
00400     def mouse_down_at(self,locator,coordString):
00401         """
00402         Simulates a user pressing the mouse button (without releasing it yet) on
00403         the specified element.
00404         
00405         'locator' is an element locator
00406         'coordString' is specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.
00407         """
00408         self.do_command("mouseDownAt", [locator,coordString,])
00409 
00410 
00411     def mouse_up(self,locator):
00412         """
00413         Simulates a user pressing the mouse button (without releasing it yet) on
00414         the specified element.
00415         
00416         'locator' is an element locator
00417         """
00418         self.do_command("mouseUp", [locator,])
00419 
00420 
00421     def mouse_up_at(self,locator,coordString):
00422         """
00423         Simulates a user pressing the mouse button (without releasing it yet) on
00424         the specified element.
00425         
00426         'locator' is an element locator
00427         'coordString' is specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.
00428         """
00429         self.do_command("mouseUpAt", [locator,coordString,])
00430 
00431 
00432     def mouse_move(self,locator):
00433         """
00434         Simulates a user pressing the mouse button (without releasing it yet) on
00435         the specified element.
00436         
00437         'locator' is an element locator
00438         """
00439         self.do_command("mouseMove", [locator,])
00440 
00441 
00442     def mouse_move_at(self,locator,coordString):
00443         """
00444         Simulates a user pressing the mouse button (without releasing it yet) on
00445         the specified element.
00446         
00447         'locator' is an element locator
00448         'coordString' is specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.
00449         """
00450         self.do_command("mouseMoveAt", [locator,coordString,])
00451 
00452 
00453     def type(self,locator,value):
00454         """
00455         Sets the value of an input field, as though you typed it in.
00456         
00457         Can also be used to set the value of combo boxes, check boxes, etc. In these cases,
00458         value should be the value of the option selected, not the visible text.
00459         
00460         
00461         'locator' is an element locator
00462         'value' is the value to type
00463         """
00464         self.do_command("type", [locator,value,])
00465 
00466 
00467     def set_speed(self,value):
00468         """
00469         Set execution speed (i.e., set the millisecond length of a delay which will follow each selenium operation).  By default, there is no such delay, i.e.,
00470         the delay is 0 milliseconds.
00471         
00472         'value' is the number of milliseconds to pause after operation
00473         """
00474         self.do_command("setSpeed", [value,])
00475 
00476 
00477     def get_speed(self):
00478         """
00479         Get execution speed (i.e., get the millisecond length of the delay following each selenium operation).  By default, there is no such delay, i.e.,
00480         the delay is 0 milliseconds.
00481         
00482         See also setSpeed.
00483         
00484         """
00485         self.do_command("getSpeed", [])
00486 
00487 
00488     def check(self,locator):
00489         """
00490         Check a toggle-button (checkbox/radio)
00491         
00492         'locator' is an element locator
00493         """
00494         self.do_command("check", [locator,])
00495 
00496 
00497     def uncheck(self,locator):
00498         """
00499         Uncheck a toggle-button (checkbox/radio)
00500         
00501         'locator' is an element locator
00502         """
00503         self.do_command("uncheck", [locator,])
00504 
00505 
00506     def select(self,selectLocator,optionLocator):
00507         """
00508         Select an option from a drop-down using an option locator.
00509         
00510         
00511         Option locators provide different ways of specifying options of an HTML
00512         Select element (e.g. for selecting a specific option, or for asserting
00513         that the selected option satisfies a specification). There are several
00514         forms of Select Option Locator.
00515         
00516         *    \ **label**\ =\ *labelPattern*
00517             matches options based on their labels, i.e. the visible text. (This
00518             is the default.)
00519             *    label=regexp:^[Oo]ther
00520             
00521             
00522         *    \ **value**\ =\ *valuePattern*
00523             matches options based on their values.
00524             *    value=other
00525             
00526             
00527         *    \ **id**\ =\ *id*
00528             matches options based on their ids.
00529             *    id=option1
00530             
00531             
00532         *    \ **index**\ =\ *index*
00533             matches an option based on its index (offset from zero).
00534             *    index=2
00535             
00536             
00537         
00538         
00539         If no option locator prefix is provided, the default behaviour is to match on \ **label**\ .
00540         
00541         
00542         
00543         'selectLocator' is an element locator identifying a drop-down menu
00544         'optionLocator' is an option locator (a label by default)
00545         """
00546         self.do_command("select", [selectLocator,optionLocator,])
00547 
00548 
00549     def add_selection(self,locator,optionLocator):
00550         """
00551         Add a selection to the set of selected options in a multi-select element using an option locator.
00552         
00553         @see #doSelect for details of option locators
00554         
00555         'locator' is an element locator identifying a multi-select box
00556         'optionLocator' is an option locator (a label by default)
00557         """
00558         self.do_command("addSelection", [locator,optionLocator,])
00559 
00560 
00561     def remove_selection(self,locator,optionLocator):
00562         """
00563         Remove a selection from the set of selected options in a multi-select element using an option locator.
00564         
00565         @see #doSelect for details of option locators
00566         
00567         'locator' is an element locator identifying a multi-select box
00568         'optionLocator' is an option locator (a label by default)
00569         """
00570         self.do_command("removeSelection", [locator,optionLocator,])
00571 
00572 
00573     def submit(self,formLocator):
00574         """
00575         Submit the specified form. This is particularly useful for forms without
00576         submit buttons, e.g. single-input "Search" forms.
00577         
00578         'formLocator' is an element locator for the form you want to submit
00579         """
00580         self.do_command("submit", [formLocator,])
00581 
00582 
00583     def open(self,url):
00584         """
00585         Opens an URL in the test frame. This accepts both relative and absolute
00586         URLs.
00587         
00588         The "open" command waits for the page to load before proceeding,
00589         ie. the "AndWait" suffix is implicit.
00590         
00591         \ *Note*: The URL must be on the same domain as the runner HTML
00592         due to security restrictions in the browser (Same Origin Policy). If you
00593         need to open an URL on another domain, use the Selenium Server to start a
00594         new browser session on that domain.
00595         
00596         'url' is the URL to open; may be relative or absolute
00597         """
00598         self.do_command("open", [url,])
00599 
00600 
00601     def open_window(self,url,windowID):
00602         """
00603         Opens a popup window (if a window with that ID isn't already open).
00604         After opening the window, you'll need to select it using the selectWindow
00605         command.
00606         
00607         This command can also be a useful workaround for bug SEL-339.  In some cases, Selenium will be unable to intercept a call to window.open (if the call occurs during or before the "onLoad" event, for example).
00608         In those cases, you can force Selenium to notice the open window's name by using the Selenium openWindow command, using
00609         an empty (blank) url, like this: openWindow("", "myFunnyWindow").
00610         
00611         
00612         'url' is the URL to open, which can be blank
00613         'windowID' is the JavaScript window ID of the window to select
00614         """
00615         self.do_command("openWindow", [url,windowID,])
00616 
00617 
00618     def select_window(self,windowID):
00619         """
00620         Selects a popup window; once a popup window has been selected, all
00621         commands go to that window. To select the main window again, use null
00622         as the target.
00623         
00624         Selenium has several strategies for finding the window object referred to by the "windowID" parameter.
00625         1.) if windowID is null, then it is assumed the user is referring to the original window instantiated by the browser).
00626         2.) if the value of the "windowID" parameter is a JavaScript variable name in the current application window, then it is assumed
00627         that this variable contains the return value from a call to the JavaScript window.open() method.
00628         3.) Otherwise, selenium looks in a hash it maintains that maps string names to window objects.  Each of these string 
00629         names matches the second parameter "windowName" past to the JavaScript method  window.open(url, windowName, windowFeatures, replaceFlag)
00630         (which selenium intercepts).
00631         If you're having trouble figuring out what is the name of a window that you want to manipulate, look at the selenium log messages
00632         which identify the names of windows created via window.open (and therefore intercepted by selenium).  You will see messages
00633         like the following for each window as it is opened:
00634         ``debug: window.open call intercepted; window ID (which you can use with selectWindow()) is "myNewWindow"``
00635         In some cases, Selenium will be unable to intercept a call to window.open (if the call occurs during or before the "onLoad" event, for example).
00636         (This is bug SEL-339.)  In those cases, you can force Selenium to notice the open window's name by using the Selenium openWindow command, using
00637         an empty (blank) url, like this: openWindow("", "myFunnyWindow").
00638         
00639         
00640         'windowID' is the JavaScript window ID of the window to select
00641         """
00642         self.do_command("selectWindow", [windowID,])
00643 
00644 
00645     def select_frame(self,locator):
00646         """
00647         Selects a frame within the current window.  (You may invoke this command
00648         multiple times to select nested frames.)  To select the parent frame, use
00649         "relative=parent" as a locator; to select the top frame, use "relative=top".
00650         
00651         You may also use a DOM expression to identify the frame you want directly,
00652         like this: ``dom=frames["main"].frames["subframe"]``
00653         
00654         
00655         'locator' is an element locator identifying a frame or iframe
00656         """
00657         self.do_command("selectFrame", [locator,])
00658 
00659 
00660     def get_log_messages(self):
00661         """
00662         Return the contents of the log.
00663         
00664         This is a placeholder intended to make the code generator make this API
00665         available to clients.  The selenium server will intercept this call, however,
00666         and return its recordkeeping of log messages since the last call to this API.
00667         Thus this code in JavaScript will never be called.
00668         The reason I opted for a servercentric solution is to be able to support
00669         multiple frames served from different domains, which would break a
00670         centralized JavaScript logging mechanism under some conditions.
00671         
00672         
00673         """
00674         return self.get_string("getLogMessages", [])
00675 
00676 
00677     def get_whether_this_frame_match_frame_expression(self,currentFrameString,target):
00678         """
00679         Determine whether current/locator identify the frame containing this running code.
00680         
00681         This is useful in proxy injection mode, where this code runs in every
00682         browser frame and window, and sometimes the selenium server needs to identify
00683         the "current" frame.  In this case, when the test calls selectFrame, this
00684         routine is called for each frame to figure out which one has been selected.
00685         The selected frame will return true, while all others will return false.
00686         
00687         
00688         'currentFrameString' is starting frame
00689         'target' is new frame (which might be relative to the current one)
00690         """
00691         return self.get_boolean("getWhetherThisFrameMatchFrameExpression", [currentFrameString,target,])
00692 
00693 
00694     def get_whether_this_window_match_window_expression(self,currentWindowString,target):
00695         """
00696         Determine whether currentWindowString plus target identify the window containing this running code.
00697         
00698         This is useful in proxy injection mode, where this code runs in every
00699         browser frame and window, and sometimes the selenium server needs to identify
00700         the "current" window.  In this case, when the test calls selectWindow, this
00701         routine is called for each window to figure out which one has been selected.
00702         The selected window will return true, while all others will return false.
00703         
00704         
00705         'currentWindowString' is starting window
00706         'target' is new window (which might be relative to the current one, e.g., "_parent")
00707         """
00708         return self.get_boolean("getWhetherThisWindowMatchWindowExpression", [currentWindowString,target,])
00709 
00710 
00711     def wait_for_pop_up(self,windowID,timeout):
00712         """
00713         Waits for a popup window to appear and load up.
00714         
00715         'windowID' is the JavaScript window ID of the window that will appear
00716         'timeout' is a timeout in milliseconds, after which the action will return with an error
00717         """
00718         self.do_command("waitForPopUp", [windowID,timeout,])
00719 
00720 
00721     def choose_cancel_on_next_confirmation(self):
00722         """
00723         By default, Selenium's overridden window.confirm() function will
00724         return true, as if the user had manually clicked OK.  After running
00725         this command, the next call to confirm() will return false, as if
00726         the user had clicked Cancel.
00727         
00728         """
00729         self.do_command("chooseCancelOnNextConfirmation", [])
00730 
00731 
00732     def answer_on_next_prompt(self,answer):
00733         """
00734         Instructs Selenium to return the specified answer string in response to
00735         the next JavaScript prompt [window.prompt()].
00736         
00737         'answer' is the answer to give in response to the prompt pop-up
00738         """
00739         self.do_command("answerOnNextPrompt", [answer,])
00740 
00741 
00742     def go_back(self):
00743         """
00744         Simulates the user clicking the "back" button on their browser.
00745         
00746         """
00747         self.do_command("goBack", [])
00748 
00749 
00750     def refresh(self):
00751         """
00752         Simulates the user clicking the "Refresh" button on their browser.
00753         
00754         """
00755         self.do_command("refresh", [])
00756 
00757 
00758     def close(self):
00759         """
00760         Simulates the user clicking the "close" button in the titlebar of a popup
00761         window or tab.
00762         
00763         """
00764         self.do_command("close", [])
00765 
00766 
00767     def is_alert_present(self):
00768         """
00769         Has an alert occurred?
00770         
00771         
00772         This function never throws an exception
00773         
00774         
00775         
00776         """
00777         return self.get_boolean("isAlertPresent", [])
00778 
00779 
00780     def is_prompt_present(self):
00781         """
00782         Has a prompt occurred?
00783         
00784         
00785         This function never throws an exception
00786         
00787         
00788         
00789         """
00790         return self.get_boolean("isPromptPresent", [])
00791 
00792 
00793     def is_confirmation_present(self):
00794         """
00795         Has confirm() been called?
00796         
00797         
00798         This function never throws an exception
00799         
00800         
00801         
00802         """
00803         return self.get_boolean("isConfirmationPresent", [])
00804 
00805 
00806     def get_alert(self):
00807         """
00808         Retrieves the message of a JavaScript alert generated during the previous action, or fail if there were no alerts.
00809         
00810         Getting an alert has the same effect as manually clicking OK. If an
00811         alert is generated but you do not get/verify it, the next Selenium action
00812         will fail.
00813         NOTE: under Selenium, JavaScript alerts will NOT pop up a visible alert
00814         dialog.
00815         NOTE: Selenium does NOT support JavaScript alerts that are generated in a
00816         page's onload() event handler. In this case a visible dialog WILL be
00817         generated and Selenium will hang until someone manually clicks OK.
00818         
00819         
00820         """
00821         return self.get_string("getAlert", [])
00822 
00823 
00824     def get_confirmation(self):
00825         """
00826         Retrieves the message of a JavaScript confirmation dialog generated during
00827         the previous action.
00828         
00829         
00830         By default, the confirm function will return true, having the same effect
00831         as manually clicking OK. This can be changed by prior execution of the
00832         chooseCancelOnNextConfirmation command. If an confirmation is generated
00833         but you do not get/verify it, the next Selenium action will fail.
00834         
00835         
00836         NOTE: under Selenium, JavaScript confirmations will NOT pop up a visible
00837         dialog.
00838         
00839         
00840         NOTE: Selenium does NOT support JavaScript confirmations that are
00841         generated in a page's onload() event handler. In this case a visible
00842         dialog WILL be generated and Selenium will hang until you manually click
00843         OK.
00844         
00845         
00846         
00847         """
00848         return self.get_string("getConfirmation", [])
00849 
00850 
00851     def get_prompt(self):
00852         """
00853         Retrieves the message of a JavaScript question prompt dialog generated during
00854         the previous action.
00855         
00856         Successful handling of the prompt requires prior execution of the
00857         answerOnNextPrompt command. If a prompt is generated but you
00858         do not get/verify it, the next Selenium action will fail.
00859         NOTE: under Selenium, JavaScript prompts will NOT pop up a visible
00860         dialog.
00861         NOTE: Selenium does NOT support JavaScript prompts that are generated in a
00862         page's onload() event handler. In this case a visible dialog WILL be
00863         generated and Selenium will hang until someone manually clicks OK.
00864         
00865         
00866         """
00867         return self.get_string("getPrompt", [])
00868 
00869 
00870     def get_location(self):
00871         """
00872         Gets the absolute URL of the current page.
00873         
00874         """
00875         return self.get_string("getLocation", [])
00876 
00877 
00878     def get_title(self):
00879         """
00880         Gets the title of the current page.
00881         
00882         """
00883         return self.get_string("getTitle", [])
00884 
00885 
00886     def get_body_text(self):
00887         """
00888         Gets the entire text of the page.
00889         
00890         """
00891         return self.get_string("getBodyText", [])
00892 
00893 
00894     def get_value(self,locator):
00895         """
00896         Gets the (whitespace-trimmed) value of an input field (or anything else with a value parameter).
00897         For checkbox/radio elements, the value will be "on" or "off" depending on
00898         whether the element is checked or not.
00899         
00900         'locator' is an element locator
00901         """
00902         return self.get_string("getValue", [locator,])
00903 
00904 
00905     def get_text(self,locator):
00906         """
00907         Gets the text of an element. This works for any element that contains
00908         text. This command uses either the textContent (Mozilla-like browsers) or
00909         the innerText (IE-like browsers) of the element, which is the rendered
00910         text shown to the user.
00911         
00912         'locator' is an element locator
00913         """
00914         return self.get_string("getText", [locator,])
00915 
00916 
00917     def get_eval(self,script):
00918         """
00919         Gets the result of evaluating the specified JavaScript snippet.  The snippet may
00920         have multiple lines, but only the result of the last line will be returned.
00921         
00922         Note that, by default, the snippet will run in the context of the "selenium"
00923         object itself, so ``this`` will refer to the Selenium object, and ``window`` will
00924         refer to the top-level runner test window, not the window of your application.
00925         If you need a reference to the window of your application, you can refer
00926         to ``this.browserbot.getCurrentWindow()`` and if you need to use
00927         a locator to refer to a single element in your application page, you can
00928         use ``this.page().findElement("foo")`` where "foo" is your locator.
00929         
00930         
00931         'script' is the JavaScript snippet to run
00932         """
00933         return self.get_string("getEval", [script,])
00934 
00935 
00936     def is_checked(self,locator):
00937         """
00938         Gets whether a toggle-button (checkbox/radio) is checked.  Fails if the specified element doesn't exist or isn't a toggle-button.
00939         
00940         'locator' is an element locator pointing to a checkbox or radio button
00941         """
00942         return self.get_boolean("isChecked", [locator,])
00943 
00944 
00945     def get_table(self,tableCellAddress):
00946         """
00947         Gets the text from a cell of a table. The cellAddress syntax
00948         tableLocator.row.column, where row and column start at 0.
00949         
00950         'tableCellAddress' is a cell address, e.g. "foo.1.4"
00951         """
00952         return self.get_string("getTable", [tableCellAddress,])
00953 
00954 
00955     def get_selected_labels(self,selectLocator):
00956         """
00957         Gets all option labels (visible text) for selected options in the specified select or multi-select element.
00958         
00959         'selectLocator' is an element locator identifying a drop-down menu
00960         """
00961         return self.get_string_array("getSelectedLabels", [selectLocator,])
00962 
00963 
00964     def get_selected_label(self,selectLocator):
00965         """
00966         Gets option label (visible text) for selected option in the specified select element.
00967         
00968         'selectLocator' is an element locator identifying a drop-down menu
00969         """
00970         return self.get_string("getSelectedLabel", [selectLocator,])
00971 
00972 
00973     def get_selected_values(self,selectLocator):
00974         """
00975         Gets all option values (value attributes) for selected options in the specified select or multi-select element.
00976         
00977         'selectLocator' is an element locator identifying a drop-down menu
00978         """
00979         return self.get_string_array("getSelectedValues", [selectLocator,])
00980 
00981 
00982     def get_selected_value(self,selectLocator):
00983         """
00984         Gets option value (value attribute) for selected option in the specified select element.
00985         
00986         'selectLocator' is an element locator identifying a drop-down menu
00987         """
00988         return self.get_string("getSelectedValue", [selectLocator,])
00989 
00990 
00991     def get_selected_indexes(self,selectLocator):
00992         """
00993         Gets all option indexes (option number, starting at 0) for selected options in the specified select or multi-select element.
00994         
00995         'selectLocator' is an element locator identifying a drop-down menu
00996         """
00997         return self.get_string_array("getSelectedIndexes", [selectLocator,])
00998 
00999 
01000     def get_selected_index(self,selectLocator):
01001         """
01002         Gets option index (option number, starting at 0) for selected option in the specified select element.
01003         
01004         'selectLocator' is an element locator identifying a drop-down menu
01005         """
01006         return self.get_string("getSelectedIndex", [selectLocator,])
01007 
01008 
01009     def get_selected_ids(self,selectLocator):
01010         """
01011         Gets all option element IDs for selected options in the specified select or multi-select element.
01012         
01013         'selectLocator' is an element locator identifying a drop-down menu
01014         """
01015         return self.get_string_array("getSelectedIds", [selectLocator,])
01016 
01017 
01018     def get_selected_id(self,selectLocator):
01019         """
01020         Gets option element ID for selected option in the specified select element.
01021         
01022         'selectLocator' is an element locator identifying a drop-down menu
01023         """
01024         return self.get_string("getSelectedId", [selectLocator,])
01025 
01026 
01027     def is_something_selected(self,selectLocator):
01028         """
01029         Determines whether some option in a drop-down menu is selected.
01030         
01031         'selectLocator' is an element locator identifying a drop-down menu
01032         """
01033         return self.get_boolean("isSomethingSelected", [selectLocator,])
01034 
01035 
01036     def get_select_options(self,selectLocator):
01037         """
01038         Gets all option labels in the specified select drop-down.
01039         
01040         'selectLocator' is an element locator identifying a drop-down menu
01041         """
01042         return self.get_string_array("getSelectOptions", [selectLocator,])
01043 
01044 
01045     def get_attribute(self,attributeLocator):
01046         """
01047         Gets the value of an element attribute.
01048         
01049         'attributeLocator' is an element locator followed by an
01050         """
01051         return self.get_string("getAttribute", [attributeLocator,])
01052 
01053 
01054     def is_text_present(self,pattern):
01055         """
01056         Verifies that the specified text pattern appears somewhere on the rendered page shown to the user.
01057         
01058         'pattern' is a pattern to match with the text of the page
01059         """
01060         return self.get_boolean("isTextPresent", [pattern,])
01061 
01062 
01063     def is_element_present(self,locator):
01064         """
01065         Verifies that the specified element is somewhere on the page.
01066         
01067         'locator' is an element locator
01068         """
01069         return self.get_boolean("isElementPresent", [locator,])
01070 
01071 
01072     def is_visible(self,locator):
01073         """
01074         Determines if the specified element is visible. An
01075         element can be rendered invisible by setting the CSS "visibility"
01076         property to "hidden", or the "display" property to "none", either for the
01077         element itself or one if its ancestors.  This method will fail if
01078         the element is not present.
01079         
01080         'locator' is an element locator
01081         """
01082         return self.get_boolean("isVisible", [locator,])
01083 
01084 
01085     def is_editable(self,locator):
01086         """
01087         Determines whether the specified input element is editable, ie hasn't been disabled.
01088         This method will fail if the specified element isn't an input element.
01089         
01090         'locator' is an element locator
01091         """
01092         return self.get_boolean("isEditable", [locator,])
01093 
01094 
01095     def get_all_buttons(self):
01096         """
01097         Returns the IDs of all buttons on the page.
01098         
01099         If a given button has no ID, it will appear as "" in this array.
01100         
01101         
01102         """
01103         return self.get_string_array("getAllButtons", [])
01104 
01105 
01106     def get_all_links(self):
01107         """
01108         Returns the IDs of all links on the page.
01109         
01110         If a given link has no ID, it will appear as "" in this array.
01111         
01112         
01113         """
01114         return self.get_string_array("getAllLinks", [])
01115 
01116 
01117     def get_all_fields(self):
01118         """
01119         Returns the IDs of all input fields on the page.
01120         
01121         If a given field has no ID, it will appear as "" in this array.
01122         
01123         
01124         """
01125         return self.get_string_array("getAllFields", [])
01126 
01127 
01128     def get_attribute_from_all_windows(self,attributeName):
01129         """
01130         Returns every instance of some attribute from all known windows.
01131         
01132         'attributeName' is name of an attribute on the windows
01133         """
01134         return self.get_string_array("getAttributeFromAllWindows", [attributeName,])
01135 
01136 
01137     def dragdrop(self,locator,movementsString):
01138         """
01139         deprecated - use dragAndDrop instead
01140         
01141         'locator' is an element locator
01142         'movementsString' is offset in pixels from the current location to which the element should be moved, e.g., "+70,-300"
01143         """
01144         self.do_command("dragdrop", [locator,movementsString,])
01145 
01146 
01147     def drag_and_drop(self,locator,movementsString):
01148         """
01149         Drags an element a certain distance and then drops it
01150         
01151         'locator' is an element locator
01152         'movementsString' is offset in pixels from the current location to which the element should be moved, e.g., "+70,-300"
01153         """
01154         self.do_command("dragAndDrop", [locator,movementsString,])
01155 
01156 
01157     def drag_and_drop_to_object(self,locatorOfObjectToBeDragged,locatorOfDragDestinationObject):
01158         """
01159         Drags an element and drops it on another element
01160         
01161         'locatorOfObjectToBeDragged' is an element to be dragged
01162         'locatorOfDragDestinationObject' is an element whose location (i.e., whose top left corner) will be the point where locatorOfObjectToBeDragged  is dropped
01163         """
01164         self.do_command("dragAndDropToObject", [locatorOfObjectToBeDragged,locatorOfDragDestinationObject,])
01165 
01166 
01167     def window_focus(self,windowName):
01168         """
01169         Gives focus to a window
01170         
01171         'windowName' is name of the window to be given focus
01172         """
01173         self.do_command("windowFocus", [windowName,])
01174 
01175 
01176     def window_maximize(self,windowName):
01177         """
01178         Resize window to take up the entire screen
01179         
01180         'windowName' is name of the window to be enlarged
01181         """
01182         self.do_command("windowMaximize", [windowName,])
01183 
01184 
01185     def get_all_window_ids(self):
01186         """
01187         Returns the IDs of all windows that the browser knows about.
01188         
01189         """
01190         return self.get_string_array("getAllWindowIds", [])
01191 
01192 
01193     def get_all_window_names(self):
01194         """
01195         Returns the names of all windows that the browser knows about.
01196         
01197         """
01198         return self.get_string_array("getAllWindowNames", [])
01199 
01200 
01201     def get_all_window_titles(self):
01202         """
01203         Returns the titles of all windows that the browser knows about.
01204         
01205         """
01206         return self.get_string_array("getAllWindowTitles", [])
01207 
01208 
01209     def get_html_source(self):
01210         """
01211         Returns the entire HTML source between the opening and
01212         closing "html" tags.
01213         
01214         """
01215         return self.get_string("getHtmlSource", [])
01216 
01217 
01218     def set_cursor_position(self,locator,position):
01219         """
01220         Moves the text cursor to the specified position in the given input element or textarea.
01221         This method will fail if the specified element isn't an input element or textarea.
01222         
01223         'locator' is an element locator pointing to an input element or textarea
01224         'position' is the numerical position of the cursor in the field; position should be 0 to move the position to the beginning of the field.  You can also set the cursor to -1 to move it to the end of the field.
01225         """
01226         self.do_command("setCursorPosition", [locator,position,])
01227 
01228 
01229     def get_element_index(self,locator):
01230         """
01231         Get the relative index of an element to its parent (starting from 0). The comment node and empty text node
01232         will be ignored.
01233         
01234         'locator' is an element locator pointing to an element
01235         """
01236         return self.get_number("getElementIndex", [locator,])
01237 
01238 
01239     def is_ordered(self,locator1,locator2):
01240         """
01241         Check if these two elements have same parent and are ordered. Two same elements will
01242         not be considered ordered.
01243         
01244         'locator1' is an element locator pointing to the first element
01245         'locator2' is an element locator pointing to the second element
01246         """
01247         return self.get_boolean("isOrdered", [locator1,locator2,])
01248 
01249 
01250     def get_element_position_left(self,locator):
01251         """
01252         Retrieves the horizontal position of an element
01253         
01254         'locator' is an element locator pointing to an element OR an element itself
01255         """
01256         return self.get_number("getElementPositionLeft", [locator,])
01257 
01258 
01259     def get_element_position_top(self,locator):
01260         """
01261         Retrieves the vertical position of an element
01262         
01263         'locator' is an element locator pointing to an element OR an element itself
01264         """
01265         return self.get_number("getElementPositionTop", [locator,])
01266 
01267 
01268     def get_element_width(self,locator):
01269         """
01270         Retrieves the width of an element
01271         
01272         'locator' is an element locator pointing to an element
01273         """
01274         return self.get_number("getElementWidth", [locator,])
01275 
01276 
01277     def get_element_height(self,locator):
01278         """
01279         Retrieves the height of an element
01280         
01281         'locator' is an element locator pointing to an element
01282         """
01283         return self.get_number("getElementHeight", [locator,])
01284 
01285 
01286     def get_cursor_position(self,locator):
01287         """
01288         Retrieves the text cursor position in the given input element or textarea; beware, this may not work perfectly on all browsers.
01289         
01290         Specifically, if the cursor/selection has been cleared by JavaScript, this command will tend to
01291         return the position of the last location of the cursor, even though the cursor is now gone from the page.  This is filed as SEL-243.
01292         
01293         This method will fail if the specified element isn't an input element or textarea, or there is no cursor in the element.
01294         
01295         'locator' is an element locator pointing to an input element or textarea
01296         """
01297         return self.get_number("getCursorPosition", [locator,])
01298 
01299 
01300     def set_context(self,context,logLevelThreshold):
01301         """
01302         Writes a message to the status bar and adds a note to the browser-side
01303         log.
01304         
01305         If logLevelThreshold is specified, set the threshold for logging
01306         to that level (debug, info, warn, error).
01307         (Note that the browser-side logs will \ *not* be sent back to the
01308         server, and are invisible to the Client Driver.)
01309         
01310         
01311         'context' is the message to be sent to the browser
01312         'logLevelThreshold' is one of "debug", "info", "warn", "error", sets the threshold for browser-side logging
01313         """
01314         self.do_command("setContext", [context,logLevelThreshold,])
01315 
01316 
01317     def get_expression(self,expression):
01318         """
01319         Returns the specified expression.
01320         
01321         This is useful because of JavaScript preprocessing.
01322         It is used to generate commands like assertExpression and waitForExpression.
01323         
01324         
01325         'expression' is the value to return
01326         """
01327         return self.get_string("getExpression", [expression,])
01328 
01329 
01330     def wait_for_condition(self,script,timeout):
01331         """
01332         Runs the specified JavaScript snippet repeatedly until it evaluates to "true".
01333         The snippet may have multiple lines, but only the result of the last line
01334         will be considered.
01335         
01336         Note that, by default, the snippet will be run in the runner's test window, not in the window
01337         of your application.  To get the window of your application, you can use
01338         the JavaScript snippet ``selenium.browserbot.getCurrentWindow()``, and then
01339         run your JavaScript in there
01340         
01341         
01342         'script' is the JavaScript snippet to run
01343         'timeout' is a timeout in milliseconds, after which this command will return with an error
01344         """
01345         self.do_command("waitForCondition", [script,timeout,])
01346 
01347 
01348     def set_timeout(self,timeout):
01349         """
01350         Specifies the amount of time that Selenium will wait for actions to complete.
01351         
01352         Actions that require waiting include "open" and the "waitFor*" actions.
01353         
01354         The default timeout is 30 seconds.
01355         
01356         'timeout' is a timeout in milliseconds, after which the action will return with an error
01357         """
01358         self.do_command("setTimeout", [timeout,])
01359 
01360 
01361     def wait_for_page_to_load(self,timeout):
01362         """
01363         Waits for a new page to load.
01364         
01365         You can use this command instead of the "AndWait" suffixes, "clickAndWait", "selectAndWait", "typeAndWait" etc.
01366         (which are only available in the JS API).
01367         Selenium constantly keeps track of new pages loading, and sets a "newPageLoaded"
01368         flag when it first notices a page load.  Running any other Selenium command after
01369         turns the flag to false.  Hence, if you want to wait for a page to load, you must
01370         wait immediately after a Selenium command that caused a page-load.
01371         
01372         
01373         'timeout' is a timeout in milliseconds, after which this command will return with an error
01374         """
01375         self.do_command("waitForPageToLoad", [timeout,])
01376 
01377 
01378     def get_cookie(self):
01379         """
01380         Return all cookies of the current page under test.
01381         
01382         """
01383         return self.get_string("getCookie", [])
01384 
01385 
01386     def create_cookie(self,nameValuePair,optionsString):
01387         """
01388         Create a new cookie whose path and domain are same with those of current page
01389         under test, unless you specified a path for this cookie explicitly.
01390         
01391         'nameValuePair' is name and value of the cookie in a format "name=value"
01392         'optionsString' is options for the cookie. Currently supported options include 'path' and 'max_age'.      the optionsString's format is "path=/path/, max_age=60". The order of options are irrelevant, the unit      of the value of 'max_age' is second.
01393         """
01394         self.do_command("createCookie", [nameValuePair,optionsString,])
01395 
01396 
01397     def delete_cookie(self,name,path):
01398         """
01399         Delete a named cookie with specified path.
01400         
01401         'name' is the name of the cookie to be deleted
01402         'path' is the path property of the cookie to be deleted
01403         """
01404         self.do_command("deleteCookie", [name,path,])
01405