|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Defines an object that runs Selenium commands.
Element Locators tell Selenium which HTML element a command refers to. The format of a locator is:
locatorType=argument
We support the following strategies for locating elements:
- identifier=id
- Select the element with the specified @id attribute. If no match is found, select the first element whose @name attribute is id. (This is normally the default; see below.)
- id=id
- Select the element with the specified @id attribute.
- name=name
- Select the first element with the specified @name attribute.
- username
- name=username
- 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.
- name=flavour value=chocolate
- dom=javascriptExpression
- Find an element using JavaScript traversal of the HTML Document Object Model. DOM locators must begin with "document.".
- dom=document.forms['myForm'].myDropdown
- dom=document.images[56]
- xpath=xpathExpression
- Locate an element using an XPath expression.
- xpath=//img[@alt='The image alt text']
- xpath=//table[@id='table1']//tr[4]/td[2]
- link=textPattern
- Select the link (anchor) element which contains text matching the specified pattern.
- link=The link text
Without an explicit locator prefix, Selenium uses the following default strategies:
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.
Filters look much like locators, ie.
filterType=argumentSupported element-filters are:
value=valuePattern
Matches elements based on their values. This is particularly useful for refining a list of similarly-named toggle-buttons.index=index
Selects a single element based on its position in the list (offset from zero).
Various Pattern syntaxes are available for matching string values:
- glob:pattern
- Match a string against a "glob" (aka "wildmat") pattern. "Glob" is a kind of limited regular-expression syntax typically used in command-line shells. In a glob pattern, "*" represents any sequence of characters, and "?" represents any single character. Glob patterns match against the entire string.
- regexp:regexp
- Match a string using a regular-expression. The full power of JavaScript regular-expressions is available.
- exact:string
- Match a string exactly, verbatim, without any of that fancy wildcard stuff.
If no pattern prefix is specified, Selenium assumes that it's a "glob" pattern.
Method Summary | |
void |
addSelection(java.lang.String locator,
java.lang.String optionLocator)
Add a selection to the set of selected options in a multi-select element using an option locator. |
void |
answerOnNextPrompt(java.lang.String answer)
Instructs Selenium to return the specified answer string in response to the next JavaScript prompt [window.prompt()]. |
void |
check(java.lang.String locator)
Check a toggle-button (checkbox/radio) |
void |
chooseCancelOnNextConfirmation()
By default, Selenium's overridden window.confirm() function will return true, as if the user had manually clicked OK. |
void |
click(java.lang.String locator)
Clicks on a link, button, checkbox or radio button. |
void |
close()
Simulates the user clicking the "close" button in the titlebar of a popup window or tab. |
void |
fireEvent(java.lang.String locator,
java.lang.String eventName)
Explicitly simulate an event, to trigger the corresponding "onevent" handler. |
java.lang.String |
getAlert()
Retrieves the message of a JavaScript alert generated during the previous action, or fail if there were no alerts. |
java.lang.String[] |
getAllButtons()
Returns the IDs of all buttons on the page. |
java.lang.String[] |
getAllFields()
Returns the IDs of all input fields on the page. |
java.lang.String[] |
getAllLinks()
Returns the IDs of all links on the page. |
java.lang.String |
getAttribute(java.lang.String attributeLocator)
Gets the value of an element attribute. |
java.lang.String |
getBodyText()
Gets the entire text of the page. |
java.lang.String |
getConfirmation()
Retrieves the message of a JavaScript confirmation dialog generated during the previous action. |
java.lang.Number |
getCursorPosition(java.lang.String locator)
Retrieves the text cursor position in the given input element or textarea; beware, this may not work perfectly on all browsers. |
java.lang.String |
getEval(java.lang.String script)
Gets the result of evaluating the specified JavaScript snippet. |
java.lang.String |
getExpression(java.lang.String expression)
Returns the specified expression. |
java.lang.String |
getHtmlSource()
Returns the entire HTML source between the opening and closing "html" tags. |
java.lang.String |
getLocation()
Gets the absolute URL of the current page. |
java.lang.String |
getPrompt()
Retrieves the message of a JavaScript question prompt dialog generated during the previous action. |
java.lang.String |
getSelectedId(java.lang.String selectLocator)
Gets option element ID for selected option in the specified select element. |
java.lang.String[] |
getSelectedIds(java.lang.String selectLocator)
Gets all option element IDs for selected options in the specified select or multi-select element. |
java.lang.String |
getSelectedIndex(java.lang.String selectLocator)
Gets option index (option number, starting at 0) for selected option in the specified select element. |
java.lang.String[] |
getSelectedIndexes(java.lang.String selectLocator)
Gets all option indexes (option number, starting at 0) for selected options in the specified select or multi-select element. |
java.lang.String |
getSelectedLabel(java.lang.String selectLocator)
Gets option label (visible text) for selected option in the specified select element. |
java.lang.String[] |
getSelectedLabels(java.lang.String selectLocator)
Gets all option labels (visible text) for selected options in the specified select or multi-select element. |
java.lang.String |
getSelectedValue(java.lang.String selectLocator)
Gets option value (value attribute) for selected option in the specified select element. |
java.lang.String[] |
getSelectedValues(java.lang.String selectLocator)
Gets all option values (value attributes) for selected options in the specified select or multi-select element. |
java.lang.String[] |
getSelectOptions(java.lang.String selectLocator)
Gets all option labels in the specified select drop-down. |
java.lang.String |
getTable(java.lang.String tableCellAddress)
Gets the text from a cell of a table. |
java.lang.String |
getText(java.lang.String locator)
Gets the text of an element. |
java.lang.String |
getTitle()
Gets the title of the current page. |
java.lang.String |
getValue(java.lang.String locator)
Gets the (whitespace-trimmed) value of an input field (or anything else with a value parameter). |
void |
goBack()
Simulates the user clicking the "back" button on their browser. |
boolean |
isAlertPresent()
Has an alert occurred? |
boolean |
isChecked(java.lang.String locator)
Gets whether a toggle-button (checkbox/radio) is checked. |
boolean |
isConfirmationPresent()
Has confirm() been called? |
boolean |
isEditable(java.lang.String locator)
Determines whether the specified input element is editable, ie hasn't been disabled. |
boolean |
isElementPresent(java.lang.String locator)
Verifies that the specified element is somewhere on the page. |
boolean |
isPromptPresent()
Has a prompt occurred? |
boolean |
isSomethingSelected(java.lang.String selectLocator)
Determines whether some option in a drop-down menu is selected. |
boolean |
isTextPresent(java.lang.String pattern)
Verifies that the specified text pattern appears somewhere on the rendered page shown to the user. |
boolean |
isVisible(java.lang.String locator)
Determines if the specified element is visible. |
void |
keyDown(java.lang.String locator,
java.lang.String keycode)
Simulates a user pressing a key (without releasing it yet). |
void |
keyPress(java.lang.String locator,
java.lang.String keycode)
Simulates a user pressing and releasing a key. |
void |
keyUp(java.lang.String locator,
java.lang.String keycode)
Simulates a user releasing a key. |
void |
mouseDown(java.lang.String locator)
Simulates a user pressing the mouse button (without releasing it yet) on the specified element. |
void |
mouseOver(java.lang.String locator)
Simulates a user hovering a mouse over the specified element. |
void |
open(java.lang.String url)
Opens an URL in the test frame. |
void |
refresh()
Simulates the user clicking the "Refresh" button on their browser. |
void |
removeSelection(java.lang.String locator,
java.lang.String optionLocator)
Remove a selection from the set of selected options in a multi-select element using an option locator. |
void |
select(java.lang.String selectLocator,
java.lang.String optionLocator)
Select an option from a drop-down using an option locator. |
void |
selectWindow(java.lang.String windowID)
Selects a popup window; once a popup window has been selected, all commands go to that window. |
void |
setContext(java.lang.String context,
java.lang.String logLevelThreshold)
Writes a message to the status bar and adds a note to the browser-side log. |
void |
setCursorPosition(java.lang.String locator,
java.lang.String position)
Moves the text cursor to the specified position in the given input element or textarea. |
void |
setTimeout(java.lang.String timeout)
Specifies the amount of time that Selenium will wait for actions to complete. |
void |
start()
Launches the browser with a new Selenium session |
void |
stop()
Ends the test session, killing the browser |
void |
submit(java.lang.String formLocator)
Submit the specified form. |
void |
type(java.lang.String locator,
java.lang.String value)
Sets the value of an input field, as though you typed it in. |
void |
uncheck(java.lang.String locator)
Uncheck a toggle-button (checkbox/radio) |
void |
waitForCondition(java.lang.String script,
java.lang.String timeout)
Runs the specified JavaScript snippet repeatedly until it evaluates to "true". |
void |
waitForPageToLoad(java.lang.String timeout)
Waits for a new page to load. |
void |
waitForPopUp(java.lang.String windowID,
java.lang.String timeout)
Waits for a popup window to appear and load up. |
Method Detail |
public void start()
public void stop()
public void click(java.lang.String locator)
locator
- an element locatorpublic void fireEvent(java.lang.String locator, java.lang.String eventName)
locator
- an element locatoreventName
- the event name, e.g. "focus" or "blur"public void keyPress(java.lang.String locator, java.lang.String keycode)
locator
- an element locatorkeycode
- the numeric keycode of the key to be pressed, normally the
ASCII value of that key.public void keyDown(java.lang.String locator, java.lang.String keycode)
locator
- an element locatorkeycode
- the numeric keycode of the key to be pressed, normally the
ASCII value of that key.public void keyUp(java.lang.String locator, java.lang.String keycode)
locator
- an element locatorkeycode
- the numeric keycode of the key to be released, normally the
ASCII value of that key.public void mouseOver(java.lang.String locator)
locator
- an element locatorpublic void mouseDown(java.lang.String locator)
locator
- an element locatorpublic void type(java.lang.String locator, java.lang.String value)
Can also be used to set the value of combo boxes, check boxes, etc. In these cases, value should be the value of the option selected, not the visible text.
locator
- an element locatorvalue
- the value to typepublic void check(java.lang.String locator)
locator
- an element locatorpublic void uncheck(java.lang.String locator)
locator
- an element locatorpublic void select(java.lang.String selectLocator, java.lang.String optionLocator)
Option locators provide different ways of specifying options of an HTML Select element (e.g. for selecting a specific option, or for asserting that the selected option satisfies a specification). There are several forms of Select Option Locator.
If no option locator prefix is provided, the default behaviour is to match on label.
selectLocator
- an element locator identifying a drop-down menuoptionLocator
- an option locator (a label by default)public void addSelection(java.lang.String locator, java.lang.String optionLocator)
locator
- an element locator identifying a multi-select boxoptionLocator
- an option locator (a label by default)for details of option locators
public void removeSelection(java.lang.String locator, java.lang.String optionLocator)
locator
- an element locator identifying a multi-select boxoptionLocator
- an option locator (a label by default)for details of option locators
public void submit(java.lang.String formLocator)
formLocator
- an element locator for the form you want to submitpublic void open(java.lang.String url)
url
- the URL to open; may be relative or absolutepublic void selectWindow(java.lang.String windowID)
windowID
- the JavaScript window ID of the window to selectpublic void waitForPopUp(java.lang.String windowID, java.lang.String timeout)
windowID
- the JavaScript window ID of the window that will appeartimeout
- a timeout in milliseconds, after which the action will return with an errorpublic void chooseCancelOnNextConfirmation()
public void answerOnNextPrompt(java.lang.String answer)
answer
- the answer to give in response to the prompt pop-uppublic void goBack()
public void refresh()
public void close()
public boolean isAlertPresent()
This function never throws an exception
public boolean isPromptPresent()
This function never throws an exception
public boolean isConfirmationPresent()
This function never throws an exception
public java.lang.String getAlert()
Getting an alert has the same effect as manually clicking OK. If an alert is generated but you do not get/verify it, the next Selenium action will fail.
NOTE: under Selenium, JavaScript alerts will NOT pop up a visible alert dialog.
NOTE: Selenium does NOT support JavaScript alerts that are generated in a page's onload() event handler. In this case a visible dialog WILL be generated and Selenium will hang until someone manually clicks OK.
public java.lang.String getConfirmation()
By default, the confirm function will return true, having the same effect as manually clicking OK. This can be changed by prior execution of the chooseCancelOnNextConfirmation command. If an confirmation is generated but you do not get/verify it, the next Selenium action will fail.
NOTE: under Selenium, JavaScript confirmations will NOT pop up a visible dialog.
NOTE: Selenium does NOT support JavaScript confirmations that are generated in a page's onload() event handler. In this case a visible dialog WILL be generated and Selenium will hang until you manually click OK.
public java.lang.String getPrompt()
Successful handling of the prompt requires prior execution of the answerOnNextPrompt command. If a prompt is generated but you do not get/verify it, the next Selenium action will fail.
NOTE: under Selenium, JavaScript prompts will NOT pop up a visible dialog.
NOTE: Selenium does NOT support JavaScript prompts that are generated in a page's onload() event handler. In this case a visible dialog WILL be generated and Selenium will hang until someone manually clicks OK.
public java.lang.String getLocation()
public java.lang.String getTitle()
public java.lang.String getBodyText()
public java.lang.String getValue(java.lang.String locator)
locator
- an element locator
public java.lang.String getText(java.lang.String locator)
locator
- an element locator
public java.lang.String getEval(java.lang.String script)
Note that, by default, the snippet will run in the context of the "selenium"
object itself, so this
will refer to the Selenium object, and window
will
refer to the top-level runner test window, not the window of your application.
If you need a reference to the window of your application, you can refer
to this.browserbot.getCurrentWindow()
and if you need to use
a locator to refer to a single element in your application page, you can
use this.page().findElement("foo")
where "foo" is your locator.
script
- the JavaScript snippet to run
public boolean isChecked(java.lang.String locator)
locator
- an element locator pointing to a checkbox or radio button
public java.lang.String getTable(java.lang.String tableCellAddress)
tableCellAddress
- a cell address, e.g. "foo.1.4"
public java.lang.String[] getSelectedLabels(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String getSelectedLabel(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String[] getSelectedValues(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String getSelectedValue(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String[] getSelectedIndexes(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String getSelectedIndex(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String[] getSelectedIds(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String getSelectedId(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public boolean isSomethingSelected(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String[] getSelectOptions(java.lang.String selectLocator)
selectLocator
- an element locator identifying a drop-down menu
public java.lang.String getAttribute(java.lang.String attributeLocator)
attributeLocator
- an element locator followed by an
public boolean isTextPresent(java.lang.String pattern)
pattern
- a pattern to match with the text of the page
public boolean isElementPresent(java.lang.String locator)
locator
- an element locator
public boolean isVisible(java.lang.String locator)
locator
- an element locator
public boolean isEditable(java.lang.String locator)
locator
- an element locator
public java.lang.String[] getAllButtons()
If a given button has no ID, it will appear as "" in this array.
public java.lang.String[] getAllLinks()
If a given link has no ID, it will appear as "" in this array.
public java.lang.String[] getAllFields()
If a given field has no ID, it will appear as "" in this array.
public java.lang.String getHtmlSource()
public void setCursorPosition(java.lang.String locator, java.lang.String position)
locator
- an element locator pointing to an input element or textareaposition
- 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.public java.lang.Number getCursorPosition(java.lang.String locator)
Specifically, if the cursor/selection has been cleared by JavaScript, this command will tend to 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.
This method will fail if the specified element isn't an input element or textarea, or there is no cursor in the element.
locator
- an element locator pointing to an input element or textarea
public void setContext(java.lang.String context, java.lang.String logLevelThreshold)
If logLevelThreshold is specified, set the threshold for logging to that level (debug, info, warn, error).
(Note that the browser-side logs will not be sent back to the server, and are invisible to the Client Driver.)
context
- the message to be sent to the browserlogLevelThreshold
- one of "debug", "info", "warn", "error", sets the threshold for browser-side loggingpublic java.lang.String getExpression(java.lang.String expression)
This is useful because of JavaScript preprocessing. It is used to generate commands like assertExpression and waitForExpression.
expression
- the value to return
public void waitForCondition(java.lang.String script, java.lang.String timeout)
Note that, by default, the snippet will be run in the runner's test window, not in the window
of your application. To get the window of your application, you can use
the JavaScript snippet selenium.browserbot.getCurrentWindow()
, and then
run your JavaScript in there
script
- the JavaScript snippet to runtimeout
- a timeout in milliseconds, after which this command will return with an errorpublic void setTimeout(java.lang.String timeout)
Actions that require waiting include "open" and the "waitFor*" actions.
The default timeout is 30 seconds.
timeout
- a timeout in milliseconds, after which the action will return with an errorpublic void waitForPageToLoad(java.lang.String timeout)
You can use this command instead of the "AndWait" suffixes, "clickAndWait", "selectAndWait", "typeAndWait" etc. (which are only available in the JS API).
Selenium constantly keeps track of new pages loading, and sets a "newPageLoaded" flag when it first notices a page load. Running any other Selenium command after turns the flag to false. Hence, if you want to wait for a page to load, you must wait immediately after a Selenium command that caused a page-load.
timeout
- a timeout in milliseconds, after which this command will return with an error
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |