← Back to branch summary

~ubuntu-branches/ubuntu/karmic/phppgadmin/karmic

« back to all changes in this revision

Viewing changes to selenium/iedoc-core.xml

  • Committer: Bazaar Package Importer
  • Author(s): Peter Eisentraut
  • Date: 2008-12-31 19:32:22 UTC
  • mfrom: (1.3.1 upstream) (8.1.2 sid)
  • mto: (8.1.4 sid)
  • mto: This revision was merged to the branch mainline in revision 17.
  • Revision ID: james.westby@ubuntu.com-20081231193222-swr5hb1fie1enl4l
http://bugs.debian.org/508026
http://bugs.debian.org/508026
* New upstream release
  - Fixes local file inclusion vulnerability (CVE-2008-5587) (closes: #508026)
* Removed register_globals from debian/apache.conf (closes: #508026)

Show diffs side-by-side

added added

removed removed

Lines of Context:
selenium/iedoc-core.xml
1
 
<?xml version="1.0" encoding="UTF-8"?>
2
 
 
3
 
<apidoc>
4
 
 
5
 
<top>Defines an object that runs Selenium commands.
6
 
 
7
 
<h3><a name="locators"></a>Element Locators</h3>
8
 
<p>
9
 
Element Locators tell Selenium which HTML element a command refers to.
10
 
The format of a locator is:</p>
11
 
<blockquote>
12
 
<em>locatorType</em><strong>=</strong><em>argument</em>
13
 
</blockquote>
14
 
 
15
 
<p>
16
 
We support the following strategies for locating elements:
17
 
</p>
18
 
 
19
 
<ul>
20
 
<li><strong>identifier</strong>=<em>id</em>: 
21
 
Select the element with the specified &#64;id attribute. If no match is
22
 
found, select the first element whose &#64;name attribute is <em>id</em>.
23
 
(This is normally the default; see below.)</li>
24
 
<li><strong>id</strong>=<em>id</em>:
25
 
Select the element with the specified &#64;id attribute.</li>
26
 
 
27
 
<li><strong>name</strong>=<em>name</em>:
28
 
Select the first element with the specified &#64;name attribute.
29
 
<ul class="first last simple">
30
 
<li>username</li>
31
 
<li>name=username</li>
32
 
</ul>
33
 
 
34
 
<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>
35
 
 
36
 
<ul class="first last simple">
37
 
<li>name=flavour value=chocolate</li>
38
 
</ul>
39
 
</li>
40
 
<li><strong>dom</strong>=<em>javascriptExpression</em>: 
41
 
 
42
 
Find an element by evaluating the specified string.  This allows you to traverse the HTML Document Object
43
 
Model using JavaScript.  Note that you must not return a value in this string; simply make it the last expression in the block.
44
 
<ul class="first last simple">
45
 
<li>dom=document.forms['myForm'].myDropdown</li>
46
 
<li>dom=document.images[56]</li>
47
 
<li>dom=function foo() { return document.links[1]; }; foo();</li>
48
 
</ul>
49
 
 
50
 
</li>
51
 
 
52
 
<li><strong>xpath</strong>=<em>xpathExpression</em>: 
53
 
Locate an element using an XPath expression.
54
 
<ul class="first last simple">
55
 
<li>xpath=//img[&#64;alt='The image alt text']</li>
56
 
<li>xpath=//table[&#64;id='table1']//tr[4]/td[2]</li>
57
 
<li>xpath=//a[contains(&#64;href,'#id1')]</li>
58
 
<li>xpath=//a[contains(&#64;href,'#id1')]/&#64;class</li>
59
 
<li>xpath=(//table[&#64;class='stylee'])//th[text()='theHeaderText']/../td</li>
60
 
<li>xpath=//input[&#64;name='name2' and &#64;value='yes']</li>
61
 
<li>xpath=//*[text()="right"]</li>
62
 
 
63
 
</ul>
64
 
</li>
65
 
<li><strong>link</strong>=<em>textPattern</em>:
66
 
Select the link (anchor) element which contains text matching the
67
 
specified <em>pattern</em>.
68
 
<ul class="first last simple">
69
 
<li>link=The link text</li>
70
 
</ul>
71
 
 
72
 
</li>
73
 
 
74
 
<li><strong>css</strong>=<em>cssSelectorSyntax</em>:
75
 
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.
76
 
<ul class="first last simple">
77
 
<li>css=a[href="#id3"]</li>
78
 
<li>css=span#firstChild + span</li>
79
 
</ul>
80
 
<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>
81
 
</li>
82
 
</ul>
83
 
 
84
 
<p>
85
 
Without an explicit locator prefix, Selenium uses the following default
86
 
strategies:
87
 
</p>
88
 
 
89
 
<ul class="simple">
90
 
<li><strong>dom</strong>, for locators starting with &quot;document.&quot;</li>
91
 
<li><strong>xpath</strong>, for locators starting with &quot;//&quot;</li>
92
 
<li><strong>identifier</strong>, otherwise</li>
93
 
</ul>
94
 
 
95
 
<h3><a name="element-filters">Element Filters</a></h3>
96
 
<blockquote>
97
 
<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>
98
 
<p>Filters look much like locators, ie.</p>
99
 
<blockquote>
100
 
<em>filterType</em><strong>=</strong><em>argument</em></blockquote>
101
 
 
102
 
<p>Supported element-filters are:</p>
103
 
<p><strong>value=</strong><em>valuePattern</em></p>
104
 
<blockquote>
105
 
Matches elements based on their values.  This is particularly useful for refining a list of similarly-named toggle-buttons.</blockquote>
106
 
<p><strong>index=</strong><em>index</em></p>
107
 
<blockquote>
108
 
Selects a single element based on its position in the list (offset from zero).</blockquote>
109
 
</blockquote>
110
 
 
111
 
<h3><a name="patterns"></a>String-match Patterns</h3>
112
 
 
113
 
<p>
114
 
Various Pattern syntaxes are available for matching string values:
115
 
</p>
116
 
<ul>
117
 
<li><strong>glob:</strong><em>pattern</em>:
118
 
Match a string against a "glob" (aka "wildmat") pattern. "Glob" is a
119
 
kind of limited regular-expression syntax typically used in command-line
120
 
shells. In a glob pattern, "*" represents any sequence of characters, and "?"
121
 
represents any single character. Glob patterns match against the entire
122
 
string.</li>
123
 
<li><strong>regexp:</strong><em>regexp</em>:
124
 
Match a string using a regular-expression. The full power of JavaScript
125
 
regular-expressions is available.</li>
126
 
<li><strong>exact:</strong><em>string</em>:
127
 
 
128
 
Match a string exactly, verbatim, without any of that fancy wildcard
129
 
stuff.</li>
130
 
</ul>
131
 
<p>
132
 
If no pattern prefix is specified, Selenium assumes that it's a "glob"
133
 
pattern.
134
 
</p></top>
135
 
 
136
 
<function name="click">
137
 
 
138
 
<param name="locator">an element locator</param>
139
 
 
140
 
<comment>Clicks on a link, button, checkbox or radio button. If the click action
141
 
causes a new page to load (like a link usually does), call
142
 
waitForPageToLoad.</comment>
143
 
 
144
 
</function>
145
 
 
146
 
<function name="doubleClick">
147
 
 
148
 
<param name="locator">an element locator</param>
149
 
 
150
 
<comment>Double clicks on a link, button, checkbox or radio button. If the double click action
151
 
causes a new page to load (like a link usually does), call
152
 
waitForPageToLoad.</comment>
153
 
 
154
 
</function>
155
 
 
156
 
<function name="clickAt">
157
 
 
158
 
<param name="locator">an element locator</param>
159
 
 
160
 
<param name="coordString">specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.</param>
161
 
 
162
 
<comment>Clicks on a link, button, checkbox or radio button. If the click action
163
 
causes a new page to load (like a link usually does), call
164
 
waitForPageToLoad.</comment>
165
 
 
166
 
</function>
167
 
 
168
 
<function name="doubleClickAt">
169
 
 
170
 
<param name="locator">an element locator</param>
171
 
 
172
 
<param name="coordString">specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.</param>
173
 
 
174
 
<comment>Doubleclicks on a link, button, checkbox or radio button. If the action
175
 
causes a new page to load (like a link usually does), call
176
 
waitForPageToLoad.</comment>
177
 
 
178
 
</function>
179
 
 
180
 
<function name="fireEvent">
181
 
 
182
 
<param name="locator">an <a href="#locators">element locator</a></param>
183
 
 
184
 
<param name="eventName">the event name, e.g. "focus" or "blur"</param>
185
 
 
186
 
<comment>Explicitly simulate an event, to trigger the corresponding &quot;on<em>event</em>&quot;
187
 
handler.</comment>
188
 
 
189
 
</function>
190
 
 
191
 
<function name="keyPress">
192
 
 
193
 
<param name="locator">an <a href="#locators">element locator</a></param>
194
 
 
195
 
<param name="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".</param>
196
 
 
197
 
<comment>Simulates a user pressing and releasing a key.</comment>
198
 
 
199
 
</function>
200
 
 
201
 
<function name="shiftKeyDown">
202
 
 
203
 
<comment>Press the shift key and hold it down until doShiftUp() is called or a new page is loaded.</comment>
204
 
 
205
 
</function>
206
 
 
207
 
<function name="shiftKeyUp">
208
 
 
209
 
<comment>Release the shift key.</comment>
210
 
 
211
 
</function>
212
 
 
213
 
<function name="metaKeyDown">
214
 
 
215
 
<comment>Press the meta key and hold it down until doMetaUp() is called or a new page is loaded.</comment>
216
 
 
217
 
</function>
218
 
 
219
 
<function name="metaKeyUp">
220
 
 
221
 
<comment>Release the meta key.</comment>
222
 
 
223
 
</function>
224
 
 
225
 
<function name="altKeyDown">
226
 
 
227
 
<comment>Press the alt key and hold it down until doAltUp() is called or a new page is loaded.</comment>
228
 
 
229
 
</function>
230
 
 
231
 
<function name="altKeyUp">
232
 
 
233
 
<comment>Release the alt key.</comment>
234
 
 
235
 
</function>
236
 
 
237
 
<function name="controlKeyDown">
238
 
 
239
 
<comment>Press the control key and hold it down until doControlUp() is called or a new page is loaded.</comment>
240
 
 
241
 
</function>
242
 
 
243
 
<function name="controlKeyUp">
244
 
 
245
 
<comment>Release the control key.</comment>
246
 
 
247
 
</function>
248
 
 
249
 
<function name="keyDown">
250
 
 
251
 
<param name="locator">an <a href="#locators">element locator</a></param>
252
 
 
253
 
<param name="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".</param>
254
 
 
255
 
<comment>Simulates a user pressing a key (without releasing it yet).</comment>
256
 
 
257
 
</function>
258
 
 
259
 
<function name="keyUp">
260
 
 
261
 
<param name="locator">an <a href="#locators">element locator</a></param>
262
 
 
263
 
<param name="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".</param>
264
 
 
265
 
<comment>Simulates a user releasing a key.</comment>
266
 
 
267
 
</function>
268
 
 
269
 
<function name="mouseOver">
270
 
 
271
 
<param name="locator">an <a href="#locators">element locator</a></param>
272
 
 
273
 
<comment>Simulates a user hovering a mouse over the specified element.</comment>
274
 
 
275
 
</function>
276
 
 
277
 
<function name="mouseOut">
278
 
 
279
 
<param name="locator">an <a href="#locators">element locator</a></param>
280
 
 
281
 
<comment>Simulates a user moving the mouse pointer away from the specified element.</comment>
282
 
 
283
 
</function>
284
 
 
285
 
<function name="mouseDown">
286
 
 
287
 
<param name="locator">an <a href="#locators">element locator</a></param>
288
 
 
289
 
<comment>Simulates a user pressing the mouse button (without releasing it yet) on
290
 
the specified element.</comment>
291
 
 
292
 
</function>
293
 
 
294
 
<function name="mouseDownAt">
295
 
 
296
 
<param name="locator">an <a href="#locators">element locator</a></param>
297
 
 
298
 
<param name="coordString">specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.</param>
299
 
 
300
 
<comment>Simulates a user pressing the mouse button (without releasing it yet) on
301
 
the specified element.</comment>
302
 
 
303
 
</function>
304
 
 
305
 
<function name="mouseUp">
306
 
 
307
 
<param name="locator">an <a href="#locators">element locator</a></param>
308
 
 
309
 
<comment>Simulates a user pressing the mouse button (without releasing it yet) on
310
 
the specified element.</comment>
311
 
 
312
 
</function>
313
 
 
314
 
<function name="mouseUpAt">
315
 
 
316
 
<param name="locator">an <a href="#locators">element locator</a></param>
317
 
 
318
 
<param name="coordString">specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.</param>
319
 
 
320
 
<comment>Simulates a user pressing the mouse button (without releasing it yet) on
321
 
the specified element.</comment>
322
 
 
323
 
</function>
324
 
 
325
 
<function name="mouseMove">
326
 
 
327
 
<param name="locator">an <a href="#locators">element locator</a></param>
328
 
 
329
 
<comment>Simulates a user pressing the mouse button (without releasing it yet) on
330
 
the specified element.</comment>
331
 
 
332
 
</function>
333
 
 
334
 
<function name="mouseMoveAt">
335
 
 
336
 
<param name="locator">an <a href="#locators">element locator</a></param>
337
 
 
338
 
<param name="coordString">specifies the x,y position (i.e. - 10,20) of the mouse      event relative to the element returned by the locator.</param>
339
 
 
340
 
<comment>Simulates a user pressing the mouse button (without releasing it yet) on
341
 
the specified element.</comment>
342
 
 
343
 
</function>
344
 
 
345
 
<function name="type">
346
 
 
347
 
<param name="locator">an <a href="#locators">element locator</a></param>
348
 
 
349
 
<param name="value">the value to type</param>
350
 
 
351
 
<comment>Sets the value of an input field, as though you typed it in.
352
 
 
353
 
<p>Can also be used to set the value of combo boxes, check boxes, etc. In these cases,
354
 
value should be the value of the option selected, not the visible text.</p></comment>
355
 
 
356
 
</function>
357
 
 
358
 
<function name="typeKeys">
359
 
 
360
 
<param name="locator">an <a href="#locators">element locator</a></param>
361
 
 
362
 
<param name="value">the value to type</param>
363
 
 
364
 
<comment>Simulates keystroke events on the specified element, as though you typed the value key-by-key.
365
 
 
366
 
<p>This is a convenience method for calling keyDown, keyUp, keyPress for every character in the specified string;
367
 
this is useful for dynamic UI widgets (like auto-completing combo boxes) that require explicit key events.</p>
368
 
 
369
 
<p>Unlike the simple "type" command, which forces the specified value into the page directly, this command
370
 
may or may not have any visible effect, even in cases where typing keys would normally have a visible effect.
371
 
For example, if you use "typeKeys" on a form element, you may or may not see the results of what you typed in
372
 
the field.</p>
373
 
<p>In some cases, you may need to use the simple "type" command to set the value of the field and then the "typeKeys" command to
374
 
send the keystroke events corresponding to what you just typed.</p></comment>
375
 
 
376
 
</function>
377
 
 
378
 
<function name="setSpeed">
379
 
 
380
 
<param name="value">the number of milliseconds to pause after operation</param>
381
 
 
382
 
<comment>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.,
383
 
the delay is 0 milliseconds.</comment>
384
 
 
385
 
</function>
386
 
 
387
 
<function name="getSpeed">
388
 
 
389
 
<comment>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.,
390
 
the delay is 0 milliseconds.
391
 
 
392
 
See also setSpeed.</comment>
393
 
 
394
 
</function>
395
 
 
396
 
<function name="check">
397
 
 
398
 
<param name="locator">an <a href="#locators">element locator</a></param>
399
 
 
400
 
<comment>Check a toggle-button (checkbox/radio)</comment>
401
 
 
402
 
</function>
403
 
 
404
 
<function name="uncheck">
405
 
 
406
 
<param name="locator">an <a href="#locators">element locator</a></param>
407
 
 
408
 
<comment>Uncheck a toggle-button (checkbox/radio)</comment>
409
 
 
410
 
</function>
411
 
 
412
 
<function name="select">
413
 
 
414
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
415
 
 
416
 
<param name="optionLocator">an option locator (a label by default)</param>
417
 
 
418
 
<comment>Select an option from a drop-down using an option locator.
419
 
 
420
 
<p>
421
 
Option locators provide different ways of specifying options of an HTML
422
 
Select element (e.g. for selecting a specific option, or for asserting
423
 
that the selected option satisfies a specification). There are several
424
 
forms of Select Option Locator.
425
 
</p>
426
 
<ul>
427
 
<li><strong>label</strong>=<em>labelPattern</em>:
428
 
matches options based on their labels, i.e. the visible text. (This
429
 
is the default.)
430
 
<ul class="first last simple">
431
 
<li>label=regexp:^[Oo]ther</li>
432
 
</ul>
433
 
</li>
434
 
<li><strong>value</strong>=<em>valuePattern</em>:
435
 
matches options based on their values.
436
 
<ul class="first last simple">
437
 
<li>value=other</li>
438
 
</ul>
439
 
 
440
 
 
441
 
</li>
442
 
<li><strong>id</strong>=<em>id</em>:
443
 
 
444
 
matches options based on their ids.
445
 
<ul class="first last simple">
446
 
<li>id=option1</li>
447
 
</ul>
448
 
</li>
449
 
<li><strong>index</strong>=<em>index</em>:
450
 
matches an option based on its index (offset from zero).
451
 
<ul class="first last simple">
452
 
 
453
 
<li>index=2</li>
454
 
</ul>
455
 
</li>
456
 
</ul>
457
 
<p>
458
 
If no option locator prefix is provided, the default behaviour is to match on <strong>label</strong>.
459
 
</p></comment>
460
 
 
461
 
</function>
462
 
 
463
 
<function name="addSelection">
464
 
 
465
 
<param name="locator">an <a href="#locators">element locator</a> identifying a multi-select box</param>
466
 
 
467
 
<param name="optionLocator">an option locator (a label by default)</param>
468
 
 
469
 
<comment>Add a selection to the set of selected options in a multi-select element using an option locator.
470
 
 
471
 
@see #doSelect for details of option locators</comment>
472
 
 
473
 
</function>
474
 
 
475
 
<function name="removeSelection">
476
 
 
477
 
<param name="locator">an <a href="#locators">element locator</a> identifying a multi-select box</param>
478
 
 
479
 
<param name="optionLocator">an option locator (a label by default)</param>
480
 
 
481
 
<comment>Remove a selection from the set of selected options in a multi-select element using an option locator.
482
 
 
483
 
@see #doSelect for details of option locators</comment>
484
 
 
485
 
</function>
486
 
 
487
 
<function name="removeAllSelections">
488
 
 
489
 
<param name="locator">an <a href="#locators">element locator</a> identifying a multi-select box</param>
490
 
 
491
 
<comment>Unselects all of the selected options in a multi-select element.</comment>
492
 
 
493
 
</function>
494
 
 
495
 
<function name="submit">
496
 
 
497
 
<param name="formLocator">an <a href="#locators">element locator</a> for the form you want to submit</param>
498
 
 
499
 
<comment>Submit the specified form. This is particularly useful for forms without
500
 
submit buttons, e.g. single-input "Search" forms.</comment>
501
 
 
502
 
</function>
503
 
 
504
 
<function name="open">
505
 
 
506
 
<param name="url">the URL to open; may be relative or absolute</param>
507
 
 
508
 
<comment>Opens an URL in the test frame. This accepts both relative and absolute
509
 
URLs.
510
 
 
511
 
The &quot;open&quot; command waits for the page to load before proceeding,
512
 
ie. the &quot;AndWait&quot; suffix is implicit.
513
 
 
514
 
<em>Note</em>: The URL must be on the same domain as the runner HTML
515
 
due to security restrictions in the browser (Same Origin Policy). If you
516
 
need to open an URL on another domain, use the Selenium Server to start a
517
 
new browser session on that domain.</comment>
518
 
 
519
 
</function>
520
 
 
521
 
<function name="openWindow">
522
 
 
523
 
<param name="url">the URL to open, which can be blank</param>
524
 
 
525
 
<param name="windowID">the JavaScript window ID of the window to select</param>
526
 
 
527
 
<comment>Opens a popup window (if a window with that ID isn't already open).
528
 
After opening the window, you'll need to select it using the selectWindow
529
 
command.
530
 
 
531
 
<p>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).
532
 
In those cases, you can force Selenium to notice the open window's name by using the Selenium openWindow command, using
533
 
an empty (blank) url, like this: openWindow("", "myFunnyWindow").</p></comment>
534
 
 
535
 
</function>
536
 
 
537
 
<function name="selectWindow">
538
 
 
539
 
<param name="windowID">the JavaScript window ID of the window to select</param>
540
 
 
541
 
<comment>Selects a popup window; once a popup window has been selected, all
542
 
commands go to that window. To select the main window again, use null
543
 
as the target.
544
 
 
545
 
<p>Selenium has several strategies for finding the window object referred to by the "windowID" parameter.</p>
546
 
 
547
 
<p>1.) if windowID is null, then it is assumed the user is referring to the original window instantiated by the browser).</p>
548
 
<p>2.) if the value of the "windowID" parameter is a JavaScript variable name in the current application window, then it is assumed
549
 
that this variable contains the return value from a call to the JavaScript window.open() method.</p>
550
 
<p>3.) Otherwise, selenium looks in a hash it maintains that maps string names to window objects.  Each of these string 
551
 
names matches the second parameter "windowName" past to the JavaScript method  window.open(url, windowName, windowFeatures, replaceFlag)
552
 
(which selenium intercepts).</p>
553
 
 
554
 
<p>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
555
 
which identify the names of windows created via window.open (and therefore intercepted by selenium).  You will see messages
556
 
like the following for each window as it is opened:</p>
557
 
 
558
 
<p><code>debug: window.open call intercepted; window ID (which you can use with selectWindow()) is "myNewWindow"</code></p>
559
 
 
560
 
<p>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).
561
 
(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
562
 
an empty (blank) url, like this: openWindow("", "myFunnyWindow").</p></comment>
563
 
 
564
 
</function>
565
 
 
566
 
<function name="selectFrame">
567
 
 
568
 
<param name="locator">an <a href="#locators">element locator</a> identifying a frame or iframe</param>
569
 
 
570
 
<comment>Selects a frame within the current window.  (You may invoke this command
571
 
multiple times to select nested frames.)  To select the parent frame, use
572
 
"relative=parent" as a locator; to select the top frame, use "relative=top".
573
 
 
574
 
<p>You may also use a DOM expression to identify the frame you want directly,
575
 
like this: <code>dom=frames["main"].frames["subframe"]</code></p></comment>
576
 
 
577
 
</function>
578
 
 
579
 
<function name="getLogMessages">
580
 
 
581
 
<return type="string">all log messages seen since the last call to this API</return>
582
 
 
583
 
<comment>Return the contents of the log.
584
 
 
585
 
<p>This is a placeholder intended to make the code generator make this API
586
 
available to clients.  The selenium server will intercept this call, however,
587
 
and return its recordkeeping of log messages since the last call to this API.
588
 
Thus this code in JavaScript will never be called.</p>
589
 
 
590
 
<p>The reason I opted for a servercentric solution is to be able to support
591
 
multiple frames served from different domains, which would break a
592
 
centralized JavaScript logging mechanism under some conditions.</p></comment>
593
 
 
594
 
</function>
595
 
 
596
 
<function name="getWhetherThisFrameMatchFrameExpression">
597
 
 
598
 
<return type="boolean">true if the new frame is this code's window</return>
599
 
 
600
 
<param name="currentFrameString">starting frame</param>
601
 
 
602
 
<param name="target">new frame (which might be relative to the current one)</param>
603
 
 
604
 
<comment>Determine whether current/locator identify the frame containing this running code.
605
 
 
606
 
<p>This is useful in proxy injection mode, where this code runs in every
607
 
browser frame and window, and sometimes the selenium server needs to identify
608
 
the "current" frame.  In this case, when the test calls selectFrame, this
609
 
routine is called for each frame to figure out which one has been selected.
610
 
The selected frame will return true, while all others will return false.</p></comment>
611
 
 
612
 
</function>
613
 
 
614
 
<function name="getWhetherThisWindowMatchWindowExpression">
615
 
 
616
 
<return type="boolean">true if the new window is this code's window</return>
617
 
 
618
 
<param name="currentWindowString">starting window</param>
619
 
 
620
 
<param name="target">new window (which might be relative to the current one, e.g., "_parent")</param>
621
 
 
622
 
<comment>Determine whether currentWindowString plus target identify the window containing this running code.
623
 
 
624
 
<p>This is useful in proxy injection mode, where this code runs in every
625
 
browser frame and window, and sometimes the selenium server needs to identify
626
 
the "current" window.  In this case, when the test calls selectWindow, this
627
 
routine is called for each window to figure out which one has been selected.
628
 
The selected window will return true, while all others will return false.</p></comment>
629
 
 
630
 
</function>
631
 
 
632
 
<function name="waitForPopUp">
633
 
 
634
 
<param name="windowID">the JavaScript window ID of the window that will appear</param>
635
 
 
636
 
<param name="timeout">a timeout in milliseconds, after which the action will return with an error</param>
637
 
 
638
 
<comment>Waits for a popup window to appear and load up.</comment>
639
 
 
640
 
</function>
641
 
 
642
 
<function name="chooseCancelOnNextConfirmation">
643
 
 
644
 
<comment>By default, Selenium's overridden window.confirm() function will
645
 
return true, as if the user had manually clicked OK.  After running
646
 
this command, the next call to confirm() will return false, as if
647
 
the user had clicked Cancel.</comment>
648
 
 
649
 
</function>
650
 
 
651
 
<function name="answerOnNextPrompt">
652
 
 
653
 
<param name="answer">the answer to give in response to the prompt pop-up</param>
654
 
 
655
 
<comment>Instructs Selenium to return the specified answer string in response to
656
 
the next JavaScript prompt [window.prompt()].</comment>
657
 
 
658
 
</function>
659
 
 
660
 
<function name="goBack">
661
 
 
662
 
<comment>Simulates the user clicking the "back" button on their browser.</comment>
663
 
 
664
 
</function>
665
 
 
666
 
<function name="refresh">
667
 
 
668
 
<comment>Simulates the user clicking the "Refresh" button on their browser.</comment>
669
 
 
670
 
</function>
671
 
 
672
 
<function name="close">
673
 
 
674
 
<comment>Simulates the user clicking the "close" button in the titlebar of a popup
675
 
window or tab.</comment>
676
 
 
677
 
</function>
678
 
 
679
 
<function name="isAlertPresent">
680
 
 
681
 
<return type="boolean">true if there is an alert</return>
682
 
 
683
 
<comment>Has an alert occurred?
684
 
 
685
 
<p>
686
 
This function never throws an exception
687
 
</p></comment>
688
 
 
689
 
</function>
690
 
 
691
 
<function name="isPromptPresent">
692
 
 
693
 
<return type="boolean">true if there is a pending prompt</return>
694
 
 
695
 
<comment>Has a prompt occurred?
696
 
 
697
 
<p>
698
 
This function never throws an exception
699
 
</p></comment>
700
 
 
701
 
</function>
702
 
 
703
 
<function name="isConfirmationPresent">
704
 
 
705
 
<return type="boolean">true if there is a pending confirmation</return>
706
 
 
707
 
<comment>Has confirm() been called?
708
 
 
709
 
<p>
710
 
This function never throws an exception
711
 
</p></comment>
712
 
 
713
 
</function>
714
 
 
715
 
<function name="getAlert">
716
 
 
717
 
<return type="string">The message of the most recent JavaScript alert</return>
718
 
 
719
 
<comment>Retrieves the message of a JavaScript alert generated during the previous action, or fail if there were no alerts.
720
 
 
721
 
<p>Getting an alert has the same effect as manually clicking OK. If an
722
 
alert is generated but you do not get/verify it, the next Selenium action
723
 
will fail.</p>
724
 
 
725
 
<p>NOTE: under Selenium, JavaScript alerts will NOT pop up a visible alert
726
 
dialog.</p>
727
 
 
728
 
<p>NOTE: Selenium does NOT support JavaScript alerts that are generated in a
729
 
page's onload() event handler. In this case a visible dialog WILL be
730
 
generated and Selenium will hang until someone manually clicks OK.</p></comment>
731
 
 
732
 
</function>
733
 
 
734
 
<function name="getConfirmation">
735
 
 
736
 
<return type="string">the message of the most recent JavaScript confirmation dialog</return>
737
 
 
738
 
<comment>Retrieves the message of a JavaScript confirmation dialog generated during
739
 
the previous action.
740
 
 
741
 
<p>
742
 
By default, the confirm function will return true, having the same effect
743
 
as manually clicking OK. This can be changed by prior execution of the
744
 
chooseCancelOnNextConfirmation command. If an confirmation is generated
745
 
but you do not get/verify it, the next Selenium action will fail.
746
 
</p>
747
 
 
748
 
<p>
749
 
NOTE: under Selenium, JavaScript confirmations will NOT pop up a visible
750
 
dialog.
751
 
</p>
752
 
 
753
 
<p>
754
 
NOTE: Selenium does NOT support JavaScript confirmations that are
755
 
generated in a page's onload() event handler. In this case a visible
756
 
dialog WILL be generated and Selenium will hang until you manually click
757
 
OK.
758
 
</p></comment>
759
 
 
760
 
</function>
761
 
 
762
 
<function name="getPrompt">
763
 
 
764
 
<return type="string">the message of the most recent JavaScript question prompt</return>
765
 
 
766
 
<comment>Retrieves the message of a JavaScript question prompt dialog generated during
767
 
the previous action.
768
 
 
769
 
<p>Successful handling of the prompt requires prior execution of the
770
 
answerOnNextPrompt command. If a prompt is generated but you
771
 
do not get/verify it, the next Selenium action will fail.</p>
772
 
 
773
 
<p>NOTE: under Selenium, JavaScript prompts will NOT pop up a visible
774
 
dialog.</p>
775
 
 
776
 
<p>NOTE: Selenium does NOT support JavaScript prompts that are generated in a
777
 
page's onload() event handler. In this case a visible dialog WILL be
778
 
generated and Selenium will hang until someone manually clicks OK.</p></comment>
779
 
 
780
 
</function>
781
 
 
782
 
<function name="getLocation">
783
 
 
784
 
<return type="string">the absolute URL of the current page</return>
785
 
 
786
 
<comment>Gets the absolute URL of the current page.</comment>
787
 
 
788
 
</function>
789
 
 
790
 
<function name="getTitle">
791
 
 
792
 
<return type="string">the title of the current page</return>
793
 
 
794
 
<comment>Gets the title of the current page.</comment>
795
 
 
796
 
</function>
797
 
 
798
 
<function name="getBodyText">
799
 
 
800
 
<return type="string">the entire text of the page</return>
801
 
 
802
 
<comment>Gets the entire text of the page.</comment>
803
 
 
804
 
</function>
805
 
 
806
 
<function name="getValue">
807
 
 
808
 
<return type="string">the element value, or "on/off" for checkbox/radio elements</return>
809
 
 
810
 
<param name="locator">an <a href="#locators">element locator</a></param>
811
 
 
812
 
<comment>Gets the (whitespace-trimmed) value of an input field (or anything else with a value parameter).
813
 
For checkbox/radio elements, the value will be "on" or "off" depending on
814
 
whether the element is checked or not.</comment>
815
 
 
816
 
</function>
817
 
 
818
 
<function name="getText">
819
 
 
820
 
<return type="string">the text of the element</return>
821
 
 
822
 
<param name="locator">an <a href="#locators">element locator</a></param>
823
 
 
824
 
<comment>Gets the text of an element. This works for any element that contains
825
 
text. This command uses either the textContent (Mozilla-like browsers) or
826
 
the innerText (IE-like browsers) of the element, which is the rendered
827
 
text shown to the user.</comment>
828
 
 
829
 
</function>
830
 
 
831
 
<function name="highlight">
832
 
 
833
 
<param name="locator">an <a href="#locators">element locator</a></param>
834
 
 
835
 
<comment>Briefly changes the backgroundColor of the specified element yellow.  Useful for debugging.</comment>
836
 
 
837
 
</function>
838
 
 
839
 
<function name="getEval">
840
 
 
841
 
<return type="string">the results of evaluating the snippet</return>
842
 
 
843
 
<param name="script">the JavaScript snippet to run</param>
844
 
 
845
 
<comment>Gets the result of evaluating the specified JavaScript snippet.  The snippet may
846
 
have multiple lines, but only the result of the last line will be returned.
847
 
 
848
 
<p>Note that, by default, the snippet will run in the context of the "selenium"
849
 
object itself, so <code>this</code> will refer to the Selenium object, and <code>window</code> will
850
 
refer to the top-level runner test window, not the window of your application.</p>
851
 
 
852
 
<p>If you need a reference to the window of your application, you can refer
853
 
to <code>this.browserbot.getCurrentWindow()</code> and if you need to use
854
 
a locator to refer to a single element in your application page, you can
855
 
use <code>this.browserbot.findElement("foo")</code> where "foo" is your locator.</p></comment>
856
 
 
857
 
</function>
858
 
 
859
 
<function name="isChecked">
860
 
 
861
 
<return type="boolean">true if the checkbox is checked, false otherwise</return>
862
 
 
863
 
<param name="locator">an <a href="#locators">element locator</a> pointing to a checkbox or radio button</param>
864
 
 
865
 
<comment>Gets whether a toggle-button (checkbox/radio) is checked.  Fails if the specified element doesn't exist or isn't a toggle-button.</comment>
866
 
 
867
 
</function>
868
 
 
869
 
<function name="getTable">
870
 
 
871
 
<return type="string">the text from the specified cell</return>
872
 
 
873
 
<param name="tableCellAddress">a cell address, e.g. "foo.1.4"</param>
874
 
 
875
 
<comment>Gets the text from a cell of a table. The cellAddress syntax
876
 
tableLocator.row.column, where row and column start at 0.</comment>
877
 
 
878
 
</function>
879
 
 
880
 
<function name="getSelectedLabels">
881
 
 
882
 
<return type="string[]">an array of all selected option labels in the specified select drop-down</return>
883
 
 
884
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
885
 
 
886
 
<comment>Gets all option labels (visible text) for selected options in the specified select or multi-select element.</comment>
887
 
 
888
 
</function>
889
 
 
890
 
<function name="getSelectedLabel">
891
 
 
892
 
<return type="string">the selected option label in the specified select drop-down</return>
893
 
 
894
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
895
 
 
896
 
<comment>Gets option label (visible text) for selected option in the specified select element.</comment>
897
 
 
898
 
</function>
899
 
 
900
 
<function name="getSelectedValues">
901
 
 
902
 
<return type="string[]">an array of all selected option values in the specified select drop-down</return>
903
 
 
904
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
905
 
 
906
 
<comment>Gets all option values (value attributes) for selected options in the specified select or multi-select element.</comment>
907
 
 
908
 
</function>
909
 
 
910
 
<function name="getSelectedValue">
911
 
 
912
 
<return type="string">the selected option value in the specified select drop-down</return>
913
 
 
914
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
915
 
 
916
 
<comment>Gets option value (value attribute) for selected option in the specified select element.</comment>
917
 
 
918
 
</function>
919
 
 
920
 
<function name="getSelectedIndexes">
921
 
 
922
 
<return type="string[]">an array of all selected option indexes in the specified select drop-down</return>
923
 
 
924
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
925
 
 
926
 
<comment>Gets all option indexes (option number, starting at 0) for selected options in the specified select or multi-select element.</comment>
927
 
 
928
 
</function>
929
 
 
930
 
<function name="getSelectedIndex">
931
 
 
932
 
<return type="string">the selected option index in the specified select drop-down</return>
933
 
 
934
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
935
 
 
936
 
<comment>Gets option index (option number, starting at 0) for selected option in the specified select element.</comment>
937
 
 
938
 
</function>
939
 
 
940
 
<function name="getSelectedIds">
941
 
 
942
 
<return type="string[]">an array of all selected option IDs in the specified select drop-down</return>
943
 
 
944
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
945
 
 
946
 
<comment>Gets all option element IDs for selected options in the specified select or multi-select element.</comment>
947
 
 
948
 
</function>
949
 
 
950
 
<function name="getSelectedId">
951
 
 
952
 
<return type="string">the selected option ID in the specified select drop-down</return>
953
 
 
954
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
955
 
 
956
 
<comment>Gets option element ID for selected option in the specified select element.</comment>
957
 
 
958
 
</function>
959
 
 
960
 
<function name="isSomethingSelected">
961
 
 
962
 
<return type="boolean">true if some option has been selected, false otherwise</return>
963
 
 
964
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
965
 
 
966
 
<comment>Determines whether some option in a drop-down menu is selected.</comment>
967
 
 
968
 
</function>
969
 
 
970
 
<function name="getSelectOptions">
971
 
 
972
 
<return type="string[]">an array of all option labels in the specified select drop-down</return>
973
 
 
974
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
975
 
 
976
 
<comment>Gets all option labels in the specified select drop-down.</comment>
977
 
 
978
 
</function>
979
 
 
980
 
<function name="getAttribute">
981
 
 
982
 
<return type="string">the value of the specified attribute</return>
983
 
 
984
 
<param name="attributeLocator">an element locator followed by an</param>
985
 
 
986
 
<comment>Gets the value of an element attribute.</comment>
987
 
 
988
 
</function>
989
 
 
990
 
<function name="isTextPresent">
991
 
 
992
 
<return type="boolean">true if the pattern matches the text, false otherwise</return>
993
 
 
994
 
<param name="pattern">a <a href="#patterns">pattern</a> to match with the text of the page</param>
995
 
 
996
 
<comment>Verifies that the specified text pattern appears somewhere on the rendered page shown to the user.</comment>
997
 
 
998
 
</function>
999
 
 
1000
 
<function name="isElementPresent">
1001
 
 
1002
 
<return type="boolean">true if the element is present, false otherwise</return>
1003
 
 
1004
 
<param name="locator">an <a href="#locators">element locator</a></param>
1005
 
 
1006
 
<comment>Verifies that the specified element is somewhere on the page.</comment>
1007
 
 
1008
 
</function>
1009
 
 
1010
 
<function name="isVisible">
1011
 
 
1012
 
<return type="boolean">true if the specified element is visible, false otherwise</return>
1013
 
 
1014
 
<param name="locator">an <a href="#locators">element locator</a></param>
1015
 
 
1016
 
<comment>Determines if the specified element is visible. An
1017
 
element can be rendered invisible by setting the CSS "visibility"
1018
 
property to "hidden", or the "display" property to "none", either for the
1019
 
element itself or one if its ancestors.  This method will fail if
1020
 
the element is not present.</comment>
1021
 
 
1022
 
</function>
1023
 
 
1024
 
<function name="isEditable">
1025
 
 
1026
 
<return type="boolean">true if the input element is editable, false otherwise</return>
1027
 
 
1028
 
<param name="locator">an <a href="#locators">element locator</a></param>
1029
 
 
1030
 
<comment>Determines whether the specified input element is editable, ie hasn't been disabled.
1031
 
This method will fail if the specified element isn't an input element.</comment>
1032
 
 
1033
 
</function>
1034
 
 
1035
 
<function name="getAllButtons">
1036
 
 
1037
 
<return type="string[]">the IDs of all buttons on the page</return>
1038
 
 
1039
 
<comment>Returns the IDs of all buttons on the page.
1040
 
 
1041
 
<p>If a given button has no ID, it will appear as "" in this array.</p></comment>
1042
 
 
1043
 
</function>
1044
 
 
1045
 
<function name="getAllLinks">
1046
 
 
1047
 
<return type="string[]">the IDs of all links on the page</return>
1048
 
 
1049
 
<comment>Returns the IDs of all links on the page.
1050
 
 
1051
 
<p>If a given link has no ID, it will appear as "" in this array.</p></comment>
1052
 
 
1053
 
</function>
1054
 
 
1055
 
<function name="getAllFields">
1056
 
 
1057
 
<return type="string[]">the IDs of all field on the page</return>
1058
 
 
1059
 
<comment>Returns the IDs of all input fields on the page.
1060
 
 
1061
 
<p>If a given field has no ID, it will appear as "" in this array.</p></comment>
1062
 
 
1063
 
</function>
1064
 
 
1065
 
<function name="getAttributeFromAllWindows">
1066
 
 
1067
 
<return type="string[]">the set of values of this attribute from all known windows.</return>
1068
 
 
1069
 
<param name="attributeName">name of an attribute on the windows</param>
1070
 
 
1071
 
<comment>Returns every instance of some attribute from all known windows.</comment>
1072
 
 
1073
 
</function>
1074
 
 
1075
 
<function name="dragdrop">
1076
 
 
1077
 
<param name="locator">an element locator</param>
1078
 
 
1079
 
<param name="movementsString">offset in pixels from the current location to which the element should be moved, e.g., "+70,-300"</param>
1080
 
 
1081
 
<comment>deprecated - use dragAndDrop instead</comment>
1082
 
 
1083
 
</function>
1084
 
 
1085
 
<function name="setMouseSpeed">
1086
 
 
1087
 
<param name="pixels">the number of pixels between "mousemove" events</param>
1088
 
 
1089
 
<comment>Configure the number of pixels between "mousemove" events during dragAndDrop commands (default=10).
1090
 
<p>Setting this value to 0 means that we'll send a "mousemove" event to every single pixel
1091
 
in between the start location and the end location; that can be very slow, and may
1092
 
cause some browsers to force the JavaScript to timeout.</p>
1093
 
 
1094
 
<p>If the mouse speed is greater than the distance between the two dragged objects, we'll
1095
 
just send one "mousemove" at the start location and then one final one at the end location.</p></comment>
1096
 
 
1097
 
</function>
1098
 
 
1099
 
<function name="getMouseSpeed">
1100
 
 
1101
 
<return type="number">the number of pixels between "mousemove" events during dragAndDrop commands (default=10)</return>
1102
 
 
1103
 
<comment>Returns the number of pixels between "mousemove" events during dragAndDrop commands (default=10).</comment>
1104
 
 
1105
 
</function>
1106
 
 
1107
 
<function name="dragAndDrop">
1108
 
 
1109
 
<param name="locator">an element locator</param>
1110
 
 
1111
 
<param name="movementsString">offset in pixels from the current location to which the element should be moved, e.g., "+70,-300"</param>
1112
 
 
1113
 
<comment>Drags an element a certain distance and then drops it</comment>
1114
 
 
1115
 
</function>
1116
 
 
1117
 
<function name="dragAndDropToObject">
1118
 
 
1119
 
<param name="locatorOfObjectToBeDragged">an element to be dragged</param>
1120
 
 
1121
 
<param name="locatorOfDragDestinationObject">an element whose location (i.e., whose center-most pixel) will be the point where locatorOfObjectToBeDragged  is dropped</param>
1122
 
 
1123
 
<comment>Drags an element and drops it on another element</comment>
1124
 
 
1125
 
</function>
1126
 
 
1127
 
<function name="windowFocus">
1128
 
 
1129
 
<param name="windowName">name of the window to be given focus</param>
1130
 
 
1131
 
<comment>Gives focus to a window</comment>
1132
 
 
1133
 
</function>
1134
 
 
1135
 
<function name="windowMaximize">
1136
 
 
1137
 
<param name="windowName">name of the window to be enlarged</param>
1138
 
 
1139
 
<comment>Resize window to take up the entire screen</comment>
1140
 
 
1141
 
</function>
1142
 
 
1143
 
<function name="getAllWindowIds">
1144
 
 
1145
 
<return type="string[]">the IDs of all windows that the browser knows about.</return>
1146
 
 
1147
 
<comment>Returns the IDs of all windows that the browser knows about.</comment>
1148
 
 
1149
 
</function>
1150
 
 
1151
 
<function name="getAllWindowNames">
1152
 
 
1153
 
<return type="string[]">the names of all windows that the browser knows about.</return>
1154
 
 
1155
 
<comment>Returns the names of all windows that the browser knows about.</comment>
1156
 
 
1157
 
</function>
1158
 
 
1159
 
<function name="getAllWindowTitles">
1160
 
 
1161
 
<return type="string[]">the titles of all windows that the browser knows about.</return>
1162
 
 
1163
 
<comment>Returns the titles of all windows that the browser knows about.</comment>
1164
 
 
1165
 
</function>
1166
 
 
1167
 
<function name="getHtmlSource">
1168
 
 
1169
 
<return type="string">the entire HTML source</return>
1170
 
 
1171
 
<comment>Returns the entire HTML source between the opening and
1172
 
closing "html" tags.</comment>
1173
 
 
1174
 
</function>
1175
 
 
1176
 
<function name="setCursorPosition">
1177
 
 
1178
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an input element or textarea</param>
1179
 
 
1180
 
<param name="position">the numerical position of the cursor in the field; position should be 0 to move the position to the beginning of the field.  You can also set the cursor to -1 to move it to the end of the field.</param>
1181
 
 
1182
 
<comment>Moves the text cursor to the specified position in the given input element or textarea.
1183
 
This method will fail if the specified element isn't an input element or textarea.</comment>
1184
 
 
1185
 
</function>
1186
 
 
1187
 
<function name="getElementIndex">
1188
 
 
1189
 
<return type="number">of relative index of the element to its parent (starting from 0)</return>
1190
 
 
1191
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an element</param>
1192
 
 
1193
 
<comment>Get the relative index of an element to its parent (starting from 0). The comment node and empty text node
1194
 
will be ignored.</comment>
1195
 
 
1196
 
</function>
1197
 
 
1198
 
<function name="isOrdered">
1199
 
 
1200
 
<return type="boolean">true if two elements are ordered and have same parent, false otherwise</return>
1201
 
 
1202
 
<param name="locator1">an <a href="#locators">element locator</a> pointing to the first element</param>
1203
 
 
1204
 
<param name="locator2">an <a href="#locators">element locator</a> pointing to the second element</param>
1205
 
 
1206
 
<comment>Check if these two elements have same parent and are ordered. Two same elements will
1207
 
not be considered ordered.</comment>
1208
 
 
1209
 
</function>
1210
 
 
1211
 
<function name="getElementPositionLeft">
1212
 
 
1213
 
<return type="number">of pixels from the edge of the frame.</return>
1214
 
 
1215
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an element OR an element itself</param>
1216
 
 
1217
 
<comment>Retrieves the horizontal position of an element</comment>
1218
 
 
1219
 
</function>
1220
 
 
1221
 
<function name="getElementPositionTop">
1222
 
 
1223
 
<return type="number">of pixels from the edge of the frame.</return>
1224
 
 
1225
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an element OR an element itself</param>
1226
 
 
1227
 
<comment>Retrieves the vertical position of an element</comment>
1228
 
 
1229
 
</function>
1230
 
 
1231
 
<function name="getElementWidth">
1232
 
 
1233
 
<return type="number">width of an element in pixels</return>
1234
 
 
1235
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an element</param>
1236
 
 
1237
 
<comment>Retrieves the width of an element</comment>
1238
 
 
1239
 
</function>
1240
 
 
1241
 
<function name="getElementHeight">
1242
 
 
1243
 
<return type="number">height of an element in pixels</return>
1244
 
 
1245
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an element</param>
1246
 
 
1247
 
<comment>Retrieves the height of an element</comment>
1248
 
 
1249
 
</function>
1250
 
 
1251
 
<function name="getCursorPosition">
1252
 
 
1253
 
<return type="number">the numerical position of the cursor in the field</return>
1254
 
 
1255
 
<param name="locator">an <a href="#locators">element locator</a> pointing to an input element or textarea</param>
1256
 
 
1257
 
<comment>Retrieves the text cursor position in the given input element or textarea; beware, this may not work perfectly on all browsers.
1258
 
 
1259
 
<p>Specifically, if the cursor/selection has been cleared by JavaScript, this command will tend to
1260
 
return the position of the last location of the cursor, even though the cursor is now gone from the page.  This is filed as <a href="http://jira.openqa.org/browse/SEL-243">SEL-243</a>.</p>
1261
 
This method will fail if the specified element isn't an input element or textarea, or there is no cursor in the element.</comment>
1262
 
 
1263
 
</function>
1264
 
 
1265
 
<function name="setContext">
1266
 
 
1267
 
<param name="context">the message to be sent to the browser</param>
1268
 
 
1269
 
<param name="logLevelThreshold">one of "debug", "info", "warn", "error", sets the threshold for browser-side logging</param>
1270
 
 
1271
 
<comment>Writes a message to the status bar and adds a note to the browser-side
1272
 
log.
1273
 
 
1274
 
<p>If logLevelThreshold is specified, set the threshold for logging
1275
 
to that level (debug, info, warn, error).</p>
1276
 
 
1277
 
<p>(Note that the browser-side logs will <i>not</i> be sent back to the
1278
 
server, and are invisible to the Client Driver.)</p></comment>
1279
 
 
1280
 
</function>
1281
 
 
1282
 
<function name="getExpression">
1283
 
 
1284
 
<return type="string">the value passed in</return>
1285
 
 
1286
 
<param name="expression">the value to return</param>
1287
 
 
1288
 
<comment>Returns the specified expression.
1289
 
 
1290
 
<p>This is useful because of JavaScript preprocessing.
1291
 
It is used to generate commands like assertExpression and waitForExpression.</p></comment>
1292
 
 
1293
 
</function>
1294
 
 
1295
 
<function name="waitForCondition">
1296
 
 
1297
 
<param name="script">the JavaScript snippet to run</param>
1298
 
 
1299
 
<param name="timeout">a timeout in milliseconds, after which this command will return with an error</param>
1300
 
 
1301
 
<comment>Runs the specified JavaScript snippet repeatedly until it evaluates to "true".
1302
 
The snippet may have multiple lines, but only the result of the last line
1303
 
will be considered.
1304
 
 
1305
 
<p>Note that, by default, the snippet will be run in the runner's test window, not in the window
1306
 
of your application.  To get the window of your application, you can use
1307
 
the JavaScript snippet <code>selenium.browserbot.getCurrentWindow()</code>, and then
1308
 
run your JavaScript in there</p></comment>
1309
 
 
1310
 
</function>
1311
 
 
1312
 
<function name="setTimeout">
1313
 
 
1314
 
<param name="timeout">a timeout in milliseconds, after which the action will return with an error</param>
1315
 
 
1316
 
<comment>Specifies the amount of time that Selenium will wait for actions to complete.
1317
 
 
1318
 
<p>Actions that require waiting include "open" and the "waitFor*" actions.</p>
1319
 
The default timeout is 30 seconds.</comment>
1320
 
 
1321
 
</function>
1322
 
 
1323
 
<function name="waitForPageToLoad">
1324
 
 
1325
 
<param name="timeout">a timeout in milliseconds, after which this command will return with an error</param>
1326
 
 
1327
 
<comment>Waits for a new page to load.
1328
 
 
1329
 
<p>You can use this command instead of the "AndWait" suffixes, "clickAndWait", "selectAndWait", "typeAndWait" etc.
1330
 
(which are only available in the JS API).</p>
1331
 
 
1332
 
<p>Selenium constantly keeps track of new pages loading, and sets a "newPageLoaded"
1333
 
flag when it first notices a page load.  Running any other Selenium command after
1334
 
turns the flag to false.  Hence, if you want to wait for a page to load, you must
1335
 
wait immediately after a Selenium command that caused a page-load.</p></comment>
1336
 
 
1337
 
</function>
1338
 
 
1339
 
<function name="getCookie">
1340
 
 
1341
 
<return type="string">all cookies of the current page under test</return>
1342
 
 
1343
 
<comment>Return all cookies of the current page under test.</comment>
1344
 
 
1345
 
</function>
1346
 
 
1347
 
<function name="createCookie">
1348
 
 
1349
 
<param name="nameValuePair">name and value of the cookie in a format "name=value"</param>
1350
 
 
1351
 
<param name="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.</param>
1352
 
 
1353
 
<comment>Create a new cookie whose path and domain are same with those of current page
1354
 
under test, unless you specified a path for this cookie explicitly.</comment>
1355
 
 
1356
 
</function>
1357
 
 
1358
 
<function name="deleteCookie">
1359
 
 
1360
 
<param name="name">the name of the cookie to be deleted</param>
1361
 
 
1362
 
<param name="path">the path property of the cookie to be deleted</param>
1363
 
 
1364
 
<comment>Delete a named cookie with specified path.</comment>
1365
 
 
1366
 
</function>
1367
 
 
1368
 
<function name="pause">
1369
 
 
1370
 
<param name="waitTime">the amount of time to sleep (in milliseconds)</param>
1371
 
 
1372
 
<comment>Wait for the specified amount of time (in milliseconds)</comment>
1373
 
 
1374
 
</function>
1375
 
 
1376
 
<function name="break">
1377
 
 
1378
 
<comment>Halt the currently running test, and wait for the user to press the Continue button.
1379
 
This command is useful for debugging, but be careful when using it, because it will
1380
 
force automated tests to hang until a user intervenes manually.</comment>
1381
 
 
1382
 
</function>
1383
 
 
1384
 
<function name="store">
1385
 
 
1386
 
<param name="expression">the value to store</param>
1387
 
 
1388
 
<param name="variableName">the name of a <a href="#storedVars">variable</a> in which the result is to be stored.</param>
1389
 
 
1390
 
<comment>This command is a synonym for storeExpression.</comment>
1391
 
 
1392
 
</function>
1393
 
 
1394
 
<function name="echo">
1395
 
 
1396
 
<param name="message">the message to print</param>
1397
 
 
1398
 
<comment>Prints the specified message into the third table cell in your Selenese tables.
1399
 
Useful for debugging.</comment>
1400
 
 
1401
 
</function>
1402
 
 
1403
 
<function name="assertSelected">
1404
 
 
1405
 
<param name="selectLocator">an <a href="#locators">element locator</a> identifying a drop-down menu</param>
1406
 
 
1407
 
<param name="optionLocator">an option locator, typically just an option label (e.g. "John Smith")</param>
1408
 
 
1409
 
<comment>Verifies that the selected option of a drop-down satisfies the optionSpecifier.  <i>Note that this command is deprecated; you should use assertSelectedLabel, assertSelectedValue, assertSelectedIndex, or assertSelectedId instead.</i>
1410
 
 
1411
 
<p>See the select command for more information about option locators.</p></comment>
1412
 
 
1413
 
</function>
1414
 
 
1415
 
<function name="assertFailureOnNext">
1416
 
 
1417
 
<param name="message">The failure message we should expect.  This command will fail if the wrong failure message appears.</param>
1418
 
 
1419
 
<comment>Tell Selenium to expect a failure on the next command execution.</comment>
1420
 
 
1421
 
</function>
1422
 
 
1423
 
<function name="assertErrorOnNext">
1424
 
 
1425
 
<param name="message">The error message we should expect.  This command will fail if the wrong error message appears.</param>
1426
 
 
1427
 
<comment>Tell Selenium to expect an error on the next command execution.</comment>
1428
 
 
1429
 
</function>
1430
 
 
1431
 
</apidoc>