Line # Revision Author
1 583 dhwang <html>
2 <head>
3 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
4 <title>Selenium Reference</title>
5 </head>
6 <body>
7 <h1>Selenium Reference</h1>
8 <h2>Concepts</h2>
9 <p>A <strong>command</strong> is what tells Selenium what to do. Selenium commands come in three 'flavors': <strong>Actions</strong>, <strong>Accessors</strong> and <strong>Assertions</strong>.
10 Each command call is one line in the test table of the form:</p>
11 <blockquote>
12 <table border="1" class="table">
13 <colgroup>
14 <col width="39%">
15 <col width="33%">
16 <col width="28%">
17 </colgroup>
18 <tbody valign="top">
19 <tr>
20 <td>command</td><td>target</td><td>value</td>
21 </tr>
22 </tbody>
23 </table>
24 </blockquote>
25 <p>
26 <strong>Actions</strong> are commands that generally manipulate the state of the application. They do things like "click this link" and "select that option". If an Action fails, or has an error, the execution of the current test is stopped.</p>
27 <p>Many Actions can be called with the "AndWait" suffix, e.g. "clickAndWait".
28 This suffix tells Selenium that the action will cause the browser to make a call to the server,
29 and that Selenium should wait for a new page to load.</p>
30 <p>
31 <strong>Accessors</strong> examine the state of the application and store the results in variables, e.g. "storeTitle". They are also used to automatically generate Assertions.</p>
32 <p>
33 <strong>Assertions</strong> are like Accessors, but they verify that the state of the application conforms to what is expected. Examples include "make sure the page title is X" and "verify that this checkbox is checked".</p>
34 <p>All Selenium Assertions can be used in 3 modes: "assert", "verify", and "waitFor". For example, you can "assertText", "verifyText" and "waitForText". When an "assert" fails, the test is aborted. When a "verify" fails, the test will continue execution, logging the failure. This allows a single "assert" to ensure that the application is on the correct page, followed by a bunch of "verify" assertions to test form field values, labels, etc.</p>
35 <p>"waitFor" commands wait for some condition to become true (which can be useful for testing Ajax applications).
36 They will succeed immediately if the condition is already true.
37 However, they will fail and halt the test if the condition does not become true within the current timeout setting
38 (see the <strong>setTimeout</strong> action below).
39 </p>
40 <p>
41 <strong>Element Locators</strong> tell Selenium which HTML element a command refers to. Many commands require an Element Locator as the "target" attribute. Examples of Element Locators include "elementId" and "document.forms[0].element". These are described more clearly in the next section.</p>
42 <p>
43 <strong>Patterns</strong> are used for various reasons, e.g. to specify the expected value of an input field, or identify a select option. Selenium supports various types of pattern, including regular-expressions, all of which are described in more detail below.</p>Defines an object that runs Selenium commands.
44
45 <h3>
46 <a name="locators"></a>Element Locators</h3>
47 <p>
48 Element Locators tell Selenium which HTML element a command refers to.
49 The format of a locator is:</p>
50 <blockquote>
51 <em>locatorType</em><strong>=</strong><em>argument</em>
52 </blockquote>
53 <p>
54 We support the following strategies for locating elements:
55 </p>
56 <ul>
57 <li>
58 <strong>identifier</strong>=<em>id</em>:
59 Select the element with the specified @id attribute. If no match is
60 found, select the first element whose @name attribute is <em>id</em>.
61 (This is normally the default; see below.)</li>
62 <li>
63 <strong>id</strong>=<em>id</em>:
64 Select the element with the specified @id attribute.</li>
65 <li>
66 <strong>name</strong>=<em>name</em>:
67 Select the first element with the specified @name attribute.
68 <ul class="first last simple">
69 <li>username</li>
70 <li>name=username</li>
71 </ul>
72 <p>The name may optionally be followed by one or more <em>element-filters</em>, separated from the name by whitespace. If the <em>filterType</em> is not specified, <strong>value</strong> is assumed.</p>
73 <ul class="first last simple">
74 <li>name=flavour value=chocolate</li>
75 </ul>
76 </li>
77 <li>
78 <strong>dom</strong>=<em>javascriptExpression</em>:
79
80 Find an element by evaluating the specified string. This allows you to traverse the HTML Document Object
81 Model using JavaScript. Note that you must not return a value in this string; simply make it the last expression in the block.
82 <ul class="first last simple">
83 <li>dom=document.forms['myForm'].myDropdown</li>
84 <li>dom=document.images[56]</li>
85 <li>dom=function foo() { return document.links[1]; }; foo();</li>
86 </ul>
87 </li>
88 <li>
89 <strong>xpath</strong>=<em>xpathExpression</em>:
90 Locate an element using an XPath expression.
91 <ul class="first last simple">
92 <li>xpath=//img[@alt='The image alt text']</li>
93 <li>xpath=//table[@id='table1']//tr[4]/td[2]</li>
94 <li>xpath=//a[contains(@href,'#id1')]</li>
95 <li>xpath=//a[contains(@href,'#id1')]/@class</li>
96 <li>xpath=(//table[@class='stylee'])//th[text()='theHeaderText']/../td</li>
97 <li>xpath=//input[@name='name2' and @value='yes']</li>
98 <li>xpath=//*[text()="right"]</li>
99 </ul>
100 </li>
101 <li>
102 <strong>link</strong>=<em>textPattern</em>:
103 Select the link (anchor) element which contains text matching the
104 specified <em>pattern</em>.
105 <ul class="first last simple">
106 <li>link=The link text</li>
107 </ul>
108 </li>
109 <li>
110 <strong>css</strong>=<em>cssSelectorSyntax</em>:
111 Select the element using css selectors. Please refer to <a href="http://www.w3.org/TR/REC-CSS2/selector.html">CSS2 selectors</a>, <a href="http://www.w3.org/TR/2001/CR-css3-selectors-20011113/">CSS3 selectors</a> 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.
112 <ul class="first last simple">
113 <li>css=a[href="#id3"]</li>
114 <li>css=span#firstChild + span</li>
115 </ul>
116 <p>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). </p>
117 </li>
118 </ul>
119 <p>
120 Without an explicit locator prefix, Selenium uses the following default
121 strategies:
122 </p>
123 <ul class="simple">
124 <li>
125 <strong>dom</strong>, for locators starting with "document."</li>
126 <li>
127 <strong>xpath</strong>, for locators starting with "//"</li>
128 <li>
129 <strong>identifier</strong>, otherwise</li>
130 </ul>
131 <h3>
132 <a name="element-filters">Element Filters</a>
133 </h3>
134 <blockquote>
135 <p>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.</p>
136 <p>Filters look much like locators, ie.</p>
137 <blockquote>
138 <em>filterType</em><strong>=</strong><em>argument</em>
139 </blockquote>
140 <p>Supported element-filters are:</p>
141 <p>
142 <strong>value=</strong><em>valuePattern</em>
143 </p>
144 <blockquote>
145 Matches elements based on their values. This is particularly useful for refining a list of similarly-named toggle-buttons.</blockquote>
146 <p>
147 <strong>index=</strong><em>index</em>
148 </p>
149 <blockquote>
150 Selects a single element based on its position in the list (offset from zero).</blockquote>
151 </blockquote>
152 <h3>
153 <a name="patterns"></a>String-match Patterns</h3>
154 <p>
155 Various Pattern syntaxes are available for matching string values:
156 </p>
157 <ul>
158 <li>
159 <strong>glob:</strong><em>pattern</em>:
160 Match a string against a "glob" (aka "wildmat") pattern. "Glob" is a
161 kind of limited regular-expression syntax typically used in command-line
162 shells. In a glob pattern, "*" represents any sequence of characters, and "?"
163 represents any single character. Glob patterns match against the entire
164 string.</li>
165 <li>
166 <strong>regexp:</strong><em>regexp</em>:
167 Match a string using a regular-expression. The full power of JavaScript
168 regular-expressions is available.</li>
169 <li>
170 <strong>exact:</strong><em>string</em>:
171
172 Match a string exactly, verbatim, without any of that fancy wildcard
173 stuff.</li>
174 </ul>
175 <p>
176 If no pattern prefix is specified, Selenium assumes that it's a "glob"
177 pattern.
178 </p>
179 <h2>Selenium Actions</h2>
180 <dl>
181 <dt>
182 <strong><a name="addSelection"></a>addSelection
183 (
184 locator,optionLocator
185 )
186 </strong>
187 </dt>
188 <dd>Add a selection to the set of selected options in a multi-select element using an option locator.
189
190 @see #doSelect for details of option locators<p>Arguments:</p>
191 <ul>
192 <li>locator - an <a href="#locators">element locator</a> identifying a multi-select box</li>
193 <li>optionLocator - an option locator (a label by default)</li>
194 </ul>
195 </dd>
196 <br>
197 <dt>
198 <strong><a name="altKeyDown"></a>altKeyDown
199 (
200
201 )
202 </strong>
203 </dt>
204 <dd>Press the alt key and hold it down until doAltUp() is called or a new page is loaded.</dd>
205 <br>
206 <dt>
207 <strong><a name="altKeyUp"></a>altKeyUp
208 (
209
210 )
211 </strong>
212 </dt>
213 <dd>Release the alt key.</dd>
214 <br>
215 <dt>
216 <strong><a name="answerOnNextPrompt"></a>answerOnNextPrompt
217 (
218 answer
219 )
220 </strong>
221 </dt>
222 <dd>Instructs Selenium to return the specified answer string in response to
223 the next JavaScript prompt [window.prompt()].<p>Arguments:</p>
224 <ul>
225 <li>answer - the answer to give in response to the prompt pop-up</li>
226 </ul>
227 </dd>
228 <br>
229 <dt>
230 <strong><a name="break"></a>break
231 (
232
233 )
234 </strong>
235 </dt>
236 <dd>Halt the currently running test, and wait for the user to press the Continue button.
237 This command is useful for debugging, but be careful when using it, because it will
238 force automated tests to hang until a user intervenes manually.</dd>
239 <br>
240 <dt>
241 <strong><a name="check"></a>check
242 (
243 locator
244 )
245 </strong>
246 </dt>
247 <dd>Check a toggle-button (checkbox/radio)<p>Arguments:</p>
248 <ul>
249 <li>locator - an <a href="#locators">element locator</a>
250 </li>
251 </ul>
252 </dd>
253 <br>
254 <dt>
255 <strong><a name="chooseCancelOnNextConfirmation"></a>chooseCancelOnNextConfirmation
256 (
257
258 )
259 </strong>
260 </dt>
261 <dd>By default, Selenium's overridden window.confirm() function will
262 return true, as if the user had manually clicked OK. After running
263 this command, the next call to confirm() will return false, as if
264 the user had clicked Cancel.</dd>
265 <br>
266 <dt>
267 <strong><a name="click"></a>click
268 (
269 locator
270 )
271 </strong>
272 </dt>
273 <dd>Clicks on a link, button, checkbox or radio button. If the click action
274 causes a new page to load (like a link usually does), call
275 waitForPageToLoad.<p>Arguments:</p>
276 <ul>
277 <li>locator - an element locator</li>
278 </ul>
279 </dd>
280 <br>
281 <dt>
282 <strong><a name="clickAt"></a>clickAt
283 (
284 locator,coordString
285 )
286 </strong>
287 </dt>
288 <dd>Clicks on a link, button, checkbox or radio button. If the click action
289 causes a new page to load (like a link usually does), call
290 waitForPageToLoad.<p>Arguments:</p>
291 <ul>
292 <li>locator - an element locator</li>
293 <li>coordString - specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator.</li>
294 </ul>
295 </dd>
296 <br>
297 <dt>
298 <strong><a name="close"></a>close
299 (
300
301 )
302 </strong>
303 </dt>
304 <dd>Simulates the user clicking the "close" button in the titlebar of a popup
305 window or tab.</dd>
306 <br>
307 <dt>
308 <strong><a name="controlKeyDown"></a>controlKeyDown
309 (
310
311 )
312 </strong>
313 </dt>
314 <dd>Press the control key and hold it down until doControlUp() is called or a new page is loaded.</dd>
315 <br>
316 <dt>
317 <strong><a name="controlKeyUp"></a>controlKeyUp
318 (
319
320 )
321 </strong>
322 </dt>
323 <dd>Release the control key.</dd>
324 <br>
325 <dt>
326 <strong><a name="createCookie"></a>createCookie
327 (
328 nameValuePair,optionsString
329 )
330 </strong>
331 </dt>
332 <dd>Create a new cookie whose path and domain are same with those of current page
333 under test, unless you specified a path for this cookie explicitly.<p>Arguments:</p>
334 <ul>
335 <li>nameValuePair - name and value of the cookie in a format "name=value"</li>
336 <li>optionsString - options for the cookie. Currently supported options include 'path' and 'max_age'. the optionsString's format is "path=/path/, max_age=60". The order of options are irrelevant, the unit of the value of 'max_age' is second.</li>
337 </ul>
338 </dd>
339 <br>
340 <dt>
341 <strong><a name="deleteCookie"></a>deleteCookie
342 (
343 name,path
344 )
345 </strong>
346 </dt>
347 <dd>Delete a named cookie with specified path.<p>Arguments:</p>
348 <ul>
349 <li>name - the name of the cookie to be deleted</li>
350 <li>path - the path property of the cookie to be deleted</li>
351 </ul>
352 </dd>
353 <br>
354 <dt>
355 <strong><a name="doubleClick"></a>doubleClick
356 (
357 locator
358 )
359 </strong>
360 </dt>
361 <dd>Double clicks on a link, button, checkbox or radio button. If the double click action
362 causes a new page to load (like a link usually does), call
363 waitForPageToLoad.<p>Arguments:</p>
364 <ul>
365 <li>locator - an element locator</li>
366 </ul>
367 </dd>
368 <br>
369 <dt>
370 <strong><a name="doubleClickAt"></a>doubleClickAt
371 (
372 locator,coordString
373 )
374 </strong>
375 </dt>
376 <dd>Doubleclicks on a link, button, checkbox or radio button. If the action
377 causes a new page to load (like a link usually does), call
378 waitForPageToLoad.<p>Arguments:</p>
379 <ul>
380 <li>locator - an element locator</li>
381 <li>coordString - specifies the x,y position (i.e. - 10,20) of the mouse event relative to the element returned by the locator.</li>
382 </ul>
383 </dd>
384 <br>
385 <dt>
386 <strong><a name="dragAndDrop"></a>dragAndDrop
387 (
388 locator,movementsString
389 )
390 </strong>
391 </dt>
392 <dd>Drags an element a certain distance and then drops it<p>Arguments:</p>
393 <ul>
394 <li>locator - an element locator</li>
395 <li>movementsString - offset in pixels from the current location to which the element should be moved, e.g., "+70,-300"</li>
396 </ul>
397 </dd>
398 <br>
399 <dt>
400 <strong><a name="dragAndDropToObject"></a>dragAndDropToObject
401 (
402 locatorOfObjectToBeDragged,locatorOfDragDestinationObject
403 )
404 </strong>
405 </dt>
406 <dd>Drags an element and drops it on another element<p>Arguments:</p>
407 <ul>
408 <li>locatorOfObjectToBeDragged - an element to be dragged</li>
409 <li>locatorOfDragDestinationObject - an element whose location (i.e., whose center-most pixel) will be the point where locatorOfObjectToBeDragged is dropped</li>
410 </ul>
411 </dd>
412 <br>
413 <dt>
414 <strong><a name="dragdrop"></a>dragdrop
415 (
416 locator,movementsString
417 )
418 </strong>
419 </dt>
420 <dd>deprecated - use dragAndDrop instead<p>Arguments:</p>
421 <ul>
422 <li>locator - an element locator</li>
423 <li>movementsString - offset in pixels from the current location to which the element should be moved, e.g., "+70,-300"</li>
424 </ul>
425 </dd>
426 <br>
427 <dt>
428 <strong><a name="echo"></a>echo
429 (
430 message
431 )
432 </strong>
433 </dt>
434 <dd>Prints the specified message into the third table cell in your Selenese tables.
435 Useful for debugging.<p>Arguments:</p>
436 <ul>
437 <li>message - the message to print</li>
438 </ul>
439 </dd>
440 <br>
441 <dt>
442 <strong><a name="fireEvent"></a>fireEvent
443 (
444 locator,eventName
445 )
446 </strong>
447 </dt>
448 <dd>Explicitly simulate an event, to trigger the corresponding "on<em>event</em>"
449 handler.<p>Arguments:</p>
450 <ul>
451 <li>locator - an <a href="#locators">element locator</a>
452 </li>
453 <li>eventName - the event name, e.g. "focus" or "blur"</li>
454 </ul>
455 </dd>
456 <br>
457 <dt>
458 <strong><a name="getSpeed"></a>getSpeed
459 (
460
461 )
462 </strong>
463 </dt>
464 <dd>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.,
465 the delay is 0 milliseconds.
466
467 See also setSpeed.</dd>
468 <br>
469 <dt>
470 <strong><a name="goBack"></a>goBack
471 (
472
473 )
474 </strong>
475 </dt>
476 <dd>Simulates the user clicking the "back" button on their browser.</dd>
477 <br>
478 <dt>
479 <strong><a name="highlight"></a>highlight
480 (
481 locator
482 )
483 </strong>
484 </dt>
485 <dd>Briefly changes the backgroundColor of the specified element yellow. Useful for debugging.<p>Arguments:</p>
486 <ul>
487 <li>locator - an <a href="#locators">element locator</a>
488 </li>
489 </ul>
490 </dd>
491 <br>
492 <dt>
493 <strong><a name="keyDown"></a>keyDown
494 (
495 locator,keySequence
496 )
497 </strong>
498 </dt>
499 <dd>Simulates a user pressing a key (without releasing it yet).<p>Arguments:</p>
500 <ul>
501 <li>locator - an <a href="#locators">element locator</a>
502 </li>
503 <li>keySequence - Either be a string("\" followed by the numeric keycode of the key to be pressed, normally the ASCII value of that key), or a single character. For example: "w", "\119".</li>
504 </ul>
505 </dd>
506 <br>
507 <dt>
508 <strong><a name="keyPress"></a>keyPress
509 (
510 locator,keySequence
511 )
512 </strong>
513 </dt>
514 <dd>Simulates a user pressing and releasing a key.<p>Arguments:</p>
515 <ul>
516 <li>locator - an <a href="#locators">element locator</a>
517 </li>
518 <li>keySequence - Either be a string("\" followed by the numeric keycode of the key to be pressed, normally the ASCII value of that key), or a single character. For example: "w", "\119".</li>
519 </ul>
520 </dd>
521 <br>
522 <dt>
523 <strong><a name="keyUp"></a>keyUp
524 (
525 locator,keySequence
526 )
527 </strong>
528 </dt>
529 <dd>Simulates a user releasing a key.<p>Arguments:</p>
530 <ul>
531 <li>locator - an <a href="#locators">element locator</a>
532 </li>
533 <li>keySequence - Either be a string("\" followed by the numeric keycode of the key to be pressed, normally the ASCII value of that key), or a single character. For example: "w", "\119".</li>
534 </ul>
535 </dd>
536 <br>
537 <dt>
538 <strong><a name="metaKeyDown"></a>metaKeyDown
539 (
540
541 )
542 </strong>
543 </dt>
544 <dd>Press the meta key and hold it down until doMetaUp() is called or a new page is loaded.</dd>
545 <br>
546 <dt>
547 <strong><a name="metaKeyUp"></a>metaKeyUp
548 (
549
550 )
551 </strong>
552 </dt>
553 <dd>Release the meta key.</dd>
554 <br>
555 <dt>
556 <strong><a name="mouseDown"></a>mouseDown
557 (
558 locator
559 )
560 </strong>
561 </dt>
562 <dd>Simulates a user pressing the mouse button (without releasing it yet) on
563 the specified element.<p>Arguments:</p>
564 <ul>
565 <li>locator - an <a href="#locators">element locator</a>
566 </li>
567 </ul>
568 </dd>
569 <br>
570