Selenium
Reference
Concepts
A command is what tells Selenium what to do.
Selenium commands come in three 'flavors': Actions, Accessors and Assertions.
Each command call is one line in the test table of the form:
|
command
|
target
|
value
|
Actions 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.
Many Actions can be called with the "AndWait" suffix,
e.g. "clickAndWait". This suffix tells Selenium that the action will
cause the browser to make a call to the server, and that Selenium should wait
for a new page to load.
Accessors examine the state of the application and store the results
in variables, e.g. "storeTitle". They are also used to automatically
generate Assertions.
Assertions 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".
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.
"waitFor" commands wait for some condition to become
true (which can be useful for testing Ajax applications). They will succeed
immediately if the condition is already true. However, they will fail and halt
the test if the condition does not become true within the current timeout
setting (see the setTimeout action below).
Element Locators 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.
Patterns 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.
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
css=cssSelectorSyntax
Select the element using
css selectors. Please refer to CSS2 selectors, CSS3
selectors for more information. You can also check the TestCssLocators
test in the selenium test suite for an example of usage, which is included in
the downloaded selenium core package.
·
css=a[href="#id3"]
·
css=span#firstChild + span
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).
Without an explicit locator prefix, Selenium uses the following
default strategies:
- dom, for locators starting with "document."
- xpath, for locators starting with "//"
- identifier, otherwise
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=argument
Supported 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.
Selenium Actions
Add a selection to the set
of selected options in a multi-select element using an option locator. @see
#doSelect for details of option locators
Arguments:
·
optionLocator - an option locator (a label by default)
Instructs Selenium to
return the specified answer string in response to the next JavaScript prompt
[window.prompt()].
Arguments:
·
answer - the answer to give in response to the prompt pop-up
Check a toggle-button
(checkbox/radio)
Arguments:
By default, Selenium's
overridden window.confirm() function will return true, as if the user had
manually clicked OK. After running this command, the next call to confirm()
will return false, as if the user had clicked Cancel.
Clicks on a link, button,
checkbox or radio button. If the click action causes a new page to load (like a
link usually does), call waitForPageToLoad.
Arguments:
·
locator - an element locator
Clicks on a link, button,
checkbox or radio button. If the click action causes a new page to load (like a
link usually does), call waitForPageToLoad. Beware of
http://jira.openqa.org/browse/SEL-280, which will lead some event handlers to
get null event arguments. Read the bug for more details, including a
workaround.
Arguments:
·
locator - an element locator
·
coordString - specifies the x,y position (i.e. - 10,20) of the
mouse event relative to the element returned by the locator.
Simulates the user clicking
the "close" button in the titlebar of a popup window or tab.
Create a new cookie whose
path and domain are same with those of current page under test, unless you
specified a path for this cookie explicitly.
Arguments:
·
nameValuePair - name and value of the cookie in a format
"name=value"
·
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.
Delete a named cookie with
specified path.
Arguments:
·
name - the name of the cookie to be deleted
·
path - the path property of the cookie to be deleted
Drags an element a certain
distance and then drops it Beware of http://jira.openqa.org/browse/SEL-280,
which will lead some event handlers to get null event arguments. Read the bug
for more details, including a workaround.
Arguments:
·
locator - an element locator
·
movementsString - offset in pixels from the current location to
which the element should be moved, e.g., "+70,-300"
Explicitly simulate an
event, to trigger the corresponding "onevent" handler.
Arguments:
·
eventName - the event name, e.g. "focus" or
"blur"
Simulates the user clicking
the "back" button on their browser.
Simulates a user pressing a
key (without releasing it yet).
Arguments:
·
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".
Simulates a user pressing
and releasing a key.
Arguments:
·
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".
Simulates a user releasing
a key.
Arguments:
·
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".
Simulates a user pressing
the mouse button (without releasing it yet) on the specified element.
Arguments:
Simulates a user pressing
the mouse button (without releasing it yet) on the specified element. Beware of
http://jira.openqa.org/browse/SEL-280, which will lead some event handlers to
get null event arguments. Read the bug for more details, including a
workaround.
Arguments:
·
coordString - specifies the x,y position (i.e. - 10,20) of the
mouse event relative to the element returned by the locator.
Simulates a user pressing
the mouse button (without releasing it yet) on the specified element.
Arguments:
Simulates a user pressing
the mouse button (without releasing it yet) on the specified element. Beware of
http://jira.openqa.org/browse/SEL-280, which will lead some event handlers to
get null event arguments. Read the bug for more details, including a
workaround.
Arguments:
·
coordString - specifies the x,y position (i.e. - 10,20) of the
mouse event relative to the element returned by the locator.
Simulates a user moving the
mouse pointer away from the specified element.
Arguments:
Simulates a user hovering a
mouse over the specified element.
Arguments:
Simulates a user pressing
the mouse button (without releasing it yet) on the specified element.
Arguments:
Simulates a user pressing
the mouse button (without releasing it yet) on the specified element. Beware of
http://jira.openqa.org/browse/SEL-280, which will lead some event handlers to
get null event arguments. Read the bug for more details, including a
workaround.
Arguments:
·
coordString - specifies the x,y position (i.e. - 10,20) of the
mouse event relative to the element returned by the locator.
Opens an URL in the test
frame. This accepts both relative and absolute URLs. The "open"
command waits for the page to load before proceeding, ie. the
"AndWait" suffix is implicit. Note: The URL must be on
the same domain as the runner HTML due to security restrictions in the browser
(Same Origin Policy). If you need to open an URL on another domain, use the
Selenium Server to start a new browser session on that domain.
Arguments:
·
url - the URL to open; may be relative or absolute
Simulates the user clicking
the "Refresh" button on their browser.
Remove a selection from the
set of selected options in a multi-select element using an option locator. @see
#doSelect for details of option locators
Arguments:
·
optionLocator - an option locator (a label by default)
Select an option from a
drop-down using an option locator.
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.
label=labelPattern
matches options based on
their labels, i.e. the visible text. (This is the default.)
·
label=regexp:^[Oo]ther
value=valuePattern
matches options based on
their values.
·
value=other
id=id
matches options based on
their ids.
·
id=option1
index=index
matches an option based on
its index (offset from zero).
·
index=2
If no option locator prefix is provided, the default behaviour is
to match on label.
Arguments:
·
optionLocator - an option locator (a label by default)
Selects a frame within the
current window. (You may invoke this command multiple times to select nested
frames.) To select the parent frame, use "relative=parent" as a
locator; to select the top frame, use "relative=top".
You may also use a DOM expression to identify the frame you want
directly, like this: dom=frames["main"].frames["subframe"]
Arguments:
Selects a popup window;
once a popup window has been selected, all commands go to that window. To
select the main window again, use "null" as the target.
Arguments:
·
windowID - the JavaScript window ID of the window to select
Writes a message to the
status bar and adds a note to the browser-side log.
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.)
Arguments:
·
context - the message to be sent to the browser
·
logLevelThreshold - one of "debug", "info",
"warn", "error", sets the threshold for browser-side
logging
Moves the text cursor to
the specified position in the given input element or textarea. This method will
fail if the specified element isn't an input element or textarea.
Arguments:
·
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.
Specifies the amount of
time that Selenium will wait for actions to complete.
Actions that require waiting include "open" and the
"waitFor*" actions.
The default timeout is 30
seconds.
Arguments:
·
timeout - a timeout in milliseconds, after which the action will
return with an error
Submit the specified form.
This is particularly useful for forms without submit buttons, e.g. single-input
"Search" forms.
Arguments:
Sets the value of an input
field, as though you typed it in.
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.
Arguments:
·
value - the value to type
Uncheck a toggle-button (checkbox/radio)
Arguments:
Runs the specified
JavaScript snippet repeatedly until it evaluates to "true". The
snippet may have multiple lines, but only the result of the last line will be
considered.
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 snippetselenium.browserbot.getCurrentWindow(), and then run your
JavaScript in there
Arguments:
·
script - the JavaScript snippet to run
·
timeout - a timeout in milliseconds, after which this command will
return with an error
Waits for a new page to
load.
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.
Arguments:
·
timeout - a timeout in milliseconds, after which this command will
return with an error
Waits for a popup window to
appear and load up.
Arguments:
·
windowID - the JavaScript window ID of the window that will appear
·
timeout - a timeout in milliseconds, after which the action will
return with an error
Gives focus to a window
Arguments:
·
windowName - name of the window to be given focus
Resize window to take up
the entire screen
Arguments:
·
windowName - name of the window to be enlarged
Selenium Accessors
Retrieves the message of a
JavaScript alert generated during the previous action, or fail if there were no
alerts.
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.
Returns:
The message of the most
recent JavaScript alert
Related Assertions, automatically generated:
Returns the IDs of all
buttons on the page.
If a given button has no ID, it will appear as "" in
this array.
Returns:
the IDs of all buttons on
the page
Related Assertions, automatically generated:
Returns the IDs of all
input fields on the page.
If a given field has no ID, it will appear as "" in this
array.
Returns:
the IDs of all field on the
page
Related Assertions, automatically generated:
Returns the IDs of all
links on the page.
If a given link has no ID, it will appear as "" in this
array.
Returns:
the IDs of all links on the
page
Related Assertions, automatically generated:
Returns the IDs of all
windows that the browser knows about.
Returns:
the IDs of all windows that
the browser knows about.
Related Assertions, automatically generated:
Returns the names of all
windows that the browser knows about.
Returns:
the names of all windows
that the browser knows about.
Related Assertions, automatically generated:
Returns the titles of all
windows that the browser knows about.
Returns:
the titles of all windows
that the browser knows about.
Related Assertions, automatically generated:
Gets the value of an
element attribute. Beware of http://jira.openqa.org/browse/SEL-280, which will
lead some event handlers to get null event arguments. Read the bug for more
details, including a workaround.
Arguments:
·
attributeLocator - an element locator followed by an
Returns:
the value of the specified
attribute
Related Assertions, automatically generated:
Returns every instance of
some attribute from all known windows.
Arguments:
·
attributeName - name of an attribute on the windows
Returns:
the set of values of this
attribute from all known windows.
Related Assertions, automatically generated:
Gets the entire text of the
page.
Returns:
the entire text of the page
Related Assertions, automatically generated:
Retrieves the message of a
JavaScript confirmation dialog generated during the previous action.
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.
Returns:
the message of the most
recent JavaScript confirmation dialog
Related Assertions, automatically generated:
Return all cookies of the
current page under test.
Returns:
all cookies of the current
page under test
Related Assertions, automatically generated:
Retrieves the text cursor
position in the given input element or textarea; beware, this may not work
perfectly on all browsers.
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
asSEL-243.
This method will fail if
the specified element isn't an input element or textarea, or there is no cursor
in the element.
Arguments:
Returns:
the numerical position of
the cursor in the field
Related Assertions, automatically generated:
Retrieves the height of an
element
Arguments:
Returns:
height of an element in
pixels
Related Assertions, automatically generated:
Get the relative index of
an element to its parent (starting from 0). The comment node and empty text
node will be ignored.
Arguments:
Returns:
of relative index of the
element to its parent (starting from 0)
Related Assertions, automatically generated:
Retrieves the horizontal
position of an element
Arguments:
Returns:
of pixels from the edge of
the frame.
Related Assertions, automatically generated:
Retrieves the vertical
position of an element
Arguments:
Returns:
of pixels from the edge of
the frame.
Related Assertions, automatically generated:
Retrieves the width of an
element
Arguments:
Returns:
width of an element in
pixels
Related Assertions, automatically generated:
Gets the result of
evaluating the specified JavaScript snippet. The snippet may have multiple
lines, but only the result of the last line will be returned.
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.
Arguments:
·
script - the JavaScript snippet to run
Returns:
the results of evaluating
the snippet
Related Assertions, automatically generated:
Returns the specified
expression.
This is useful because of JavaScript preprocessing. It is used to
generate commands like assertExpression and waitForExpression.
Arguments:
·
expression - the value to return
Returns:
the value passed in
Related Assertions, automatically generated:
Returns the entire HTML
source between the opening and closing "html" tags.
Returns:
the entire HTML source
Related Assertions, automatically generated:
Gets the absolute URL of
the current page.
Returns:
the absolute URL of the
current page
Related Assertions, automatically generated:
Return the contents of the
log.
This is a placeholder intended to make the code generator make
this API available to clients. The selenium server will intercept this call,
however, and return its recordkeeping of log messages since the last call to
this API. Thus this code in JavaScript will never be called.
The reason I opted for a servercentric solution is to be able to
support multiple frames served from different domains, which would break a
centralized JavaScript logging mechanism under some conditions.
Returns:
all log messages seen since
the last call to this API
Related Assertions, automatically generated:
Retrieves the message of a
JavaScript question prompt dialog generated during the previous action.
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.
Returns:
the message of the most
recent JavaScript question prompt
Related Assertions, automatically generated:
Gets option element ID for
selected option in the specified select element.
Arguments:
Returns:
the selected option ID in
the specified select drop-down
Related Assertions, automatically generated:
Gets all option element IDs
for selected options in the specified select or multi-select element.
Arguments:
Returns:
an array of all selected
option IDs in the specified select drop-down
Related Assertions, automatically generated:
Gets option index (option
number, starting at 0) for selected option in the specified select element.
Arguments:
Returns:
the selected option index
in the specified select drop-down
Related Assertions, automatically generated:
Gets all option indexes
(option number, starting at 0) for selected options in the specified select or
multi-select element.
Arguments:
Returns:
an array of all selected
option indexes in the specified select drop-down
Related Assertions, automatically generated:
Gets option label (visible
text) for selected option in the specified select element.
Arguments:
Returns:
the selected option label
in the specified select drop-down
Related Assertions, automatically generated:
Gets all option labels
(visible text) for selected options in the specified select or multi-select element.
Arguments:
Returns:
an array of all selected
option labels in the specified select drop-down
Related Assertions, automatically generated:
Gets option value (value
attribute) for selected option in the specified select element.
Arguments:
Returns:
the selected option value
in the specified select drop-down
Related Assertions, automatically generated:
Gets all option values
(value attributes) for selected options in the specified select or multi-select
element.
Arguments:
Returns:
an array of all selected
option values in the specified select drop-down
Related Assertions, automatically generated:
Gets all option labels in
the specified select drop-down.
Arguments:
Returns:
an array of all option
labels in the specified select drop-down
Related Assertions, automatically generated:
Gets the text from a cell
of a table. The cellAddress syntax tableLocator.row.column, where row and
column start at 0.
Arguments:
·
tableCellAddress - a cell address, e.g. "foo.1.4"
Returns:
the text from the specified
cell
Related Assertions, automatically generated:
Gets the text of an
element. This works for any element that contains text. This command uses
either the textContent (Mozilla-like browsers) or the innerText (IE-like
browsers) of the element, which is the rendered text shown to the user.
Arguments:
Returns:
the text of the element
Related Assertions, automatically generated:
Gets the title of the
current page.
Returns:
the title of the current
page
Related Assertions, automatically generated:
Gets the
(whitespace-trimmed) value of an input field (or anything else with a value
parameter). For checkbox/radio elements, the value will be "on" or
"off" depending on whether the element is checked or not.
Arguments:
Returns:
the element value, or
"on/off" for checkbox/radio elements
Related Assertions, automatically generated:
Determine whether
current/locator identify the frame containing this running code.
This is useful in proxy injection mode, where this code runs in
every browser frame and window, and sometimes the selenium server needs to
identify the "current" frame. In this case, when the test calls
selectFrame, this routine is called for each frame to figure out which one has
been selected. The selected frame will return true, while all others will
return false.
Arguments:
·
currentFrameString - starting frame
·
target - new frame (which might be relative to the current one)
Returns:
true if the new frame is
this code's window
Related Assertions, automatically generated:
·
assertWhetherThisFrameMatchFrameExpression ( currentFrameString,
target )
·
assertNotWhetherThisFrameMatchFrameExpression (
currentFrameString, target )
·
verifyWhetherThisFrameMatchFrameExpression ( currentFrameString,
target )
·
verifyNotWhetherThisFrameMatchFrameExpression (
currentFrameString, target )
·
waitForWhetherThisFrameMatchFrameExpression ( currentFrameString,
target )
·
waitForNotWhetherThisFrameMatchFrameExpression (
currentFrameString, target )
Has an alert occurred?
This function never throws an exception
Returns:
true if there is an alert
Related Assertions, automatically generated:
·
assertAlertPresent ( )
·
assertAlertNotPresent ( )
·
verifyAlertPresent ( )
·
verifyAlertNotPresent ( )
·
waitForAlertPresent ( )
·
waitForAlertNotPresent ( )
Gets whether a
toggle-button (checkbox/radio) is checked. Fails if the specified element
doesn't exist or isn't a toggle-button.
Arguments:
Returns:
true if the checkbox is
checked, false otherwise
Related Assertions, automatically generated:
·
assertChecked ( locator )
·
assertNotChecked ( locator )
·
verifyChecked ( locator )
·
verifyNotChecked ( locator )
·
waitForChecked ( locator )
·
waitForNotChecked ( locator )
Has confirm() been called?
This function never throws an exception
Returns:
true if there is a pending
confirmation
Related Assertions, automatically generated:
·
assertConfirmationPresent ( )
·
assertConfirmationNotPresent ( )
·
verifyConfirmationPresent ( )
·
verifyConfirmationNotPresent ( )
·
waitForConfirmationPresent ( )
·
waitForConfirmationNotPresent ( )
Determines whether the
specified input element is editable, ie hasn't been disabled. This method will
fail if the specified element isn't an input element.
Arguments:
Returns:
true if the input element
is editable, false otherwise
Related Assertions, automatically generated:
·
assertEditable ( locator )
·
assertNotEditable ( locator )
·
verifyEditable ( locator )
·
verifyNotEditable ( locator )
·
waitForEditable ( locator )
·
waitForNotEditable ( locator )
Verifies that the specified
element is somewhere on the page.
Arguments:
Returns:
true if the element is
present, false otherwise
Related Assertions, automatically generated:
·
assertElementPresent ( locator )
·
assertElementNotPresent ( locator )
·
verifyElementPresent ( locator )
·
verifyElementNotPresent ( locator )
·
waitForElementPresent ( locator )
·
waitForElementNotPresent ( locator )
Check if these two elements
have same parent and are ordered. Two same elements will not be considered
ordered.
Arguments:
Returns:
true if two elements are
ordered and have same parent, false otherwise
Related Assertions, automatically generated:
·
assertOrdered ( locator1, locator2 )
·
assertNotOrdered ( locator1, locator2 )
·
verifyOrdered ( locator1, locator2 )
·
verifyNotOrdered ( locator1, locator2 )
·
waitForOrdered ( locator1, locator2 )
·
waitForNotOrdered ( locator1, locator2 )
Has a prompt occurred?
This function never throws an exception
Returns:
true if there is a pending
prompt
Related Assertions, automatically generated:
·
assertPromptPresent ( )
·
assertPromptNotPresent ( )
·
verifyPromptPresent ( )
·
verifyPromptNotPresent ( )
·
waitForPromptPresent ( )
·
waitForPromptNotPresent ( )
Determines whether some
option in a drop-down menu is selected.
Arguments:
Returns:
true if some option has
been selected, false otherwise
Related Assertions, automatically generated:
·
assertSomethingSelected ( selectLocator )
·
assertNotSomethingSelected ( selectLocator )
·
verifySomethingSelected ( selectLocator )
·
verifyNotSomethingSelected ( selectLocator )
·
waitForSomethingSelected ( selectLocator )
·
waitForNotSomethingSelected ( selectLocator )
Verifies that the specified
text pattern appears somewhere on the rendered page shown to the user.
Arguments:
Returns:
true if the pattern matches
the text, false otherwise
Related Assertions, automatically generated:
·
assertTextPresent ( pattern )
·
assertTextNotPresent ( pattern )
·
verifyTextPresent ( pattern )
·
verifyTextNotPresent ( pattern )
·
waitForTextPresent ( pattern )
·
waitForTextNotPresent ( pattern )
Determines if the specified
element is visible. An element can be rendered invisible by setting the CSS
"visibility" property to "hidden", or the
"display" property to "none", either for the element itself
or one if its ancestors. This method will fail if the element is not present.
Arguments:
Returns:
true if the specified
element is visible, false otherwise
Related Assertions, automatically generated:
·
assertVisible ( locator )
·
assertNotVisible ( locator )
·
verifyVisible ( locator )
·
verifyNotVisible ( locator )
·
waitForVisible ( locator )
·
waitForNotVisible ( locator )
All Selenium command parameters can be constructed using both
simple variable substitution as well as full javascript. Both of these
mechanisms can access previously stored variables, but do so using different
syntax.
The commands store, storeValue and storeText can
be used to store a variable value for later access. Internally, these variables
are stored in a map called "storedVars", with values keyed by the
variable name. These commands are documented in the command reference.
Variable substitution
Variable substitution provides a simple way to include a
previously stored variable in a command parameter. This is a simple mechanism,
by which the variable to substitute is indicated by ${variableName}. Multiple
variables can be substituted, and intermixed with static text.
Example:
|
store
|
Mr
|
title
|
|
storeValue
|
nameField
|
surname
|
|
store
|
${title} ${surname}
|
fullname
|
|
type
|
textElement
|
Full name is: ${fullname}
|
Javascript evaluation
Javascript evaluation provides the full power of javascript in
constructing a command parameter. To use this mechanism, the entire parameter
value must be prefixed by 'javascript{' with a trailing '}'. The text inside
the braces is evaluated as a javascript expression, and can access previously
stored variables using the storedVars map detailed above. Note
that variable substitution cannot be combined with javascript evaluation.
Example:
|
store
|
javascript{'merchant'
+ (new Date()).getTime()}
|
merchantId
|
|
type
|
textElement
|
javascript{storedVars['merchantId'].toUpperCase()}
|
It can be quite simple to extend Selenium, adding your own
actions, assertions and locator-strategies. This is done with javascript by adding
methods to the Selenium object prototype, and the PageBot object prototype. On
startup, Selenium will automatically look through methods on these prototypes,
using name patterns to recognise which ones are actions, assertions and
locators.
The following examples try to give an indication of how Selenium
can be extended with javascript.
Actions
All doFoo methods on the Selenium prototype are
added as actions. For each action foo there is also an action fooAndWait registered.
An action method can take up to 2 parameters, which will be passed the second
and third column values in the test.
Example: Add a "typeRepeated" action to Selenium, which
types the text twice into a text box.
Selenium.prototype.doTypeRepeated = function(locator,
text) {
// All locator-strategies
are automatically handled by "findElement"
var element =
this.page().findElement(locator);
// Create the
text to type
var valueToType
= text + text;
// Replace the
element text with the new text
this.page().replaceText(element,
valueToType);
};
Accessors/Assertions
All getFoo and isFoo methods on
the Selenium prototype are added as accessors (storeFoo). For each accessor
there is an assertFoo, verifyFoo and waitForFoo registered.
An assert method can take up to 2 parameters, which will be passed the second
and third column values in the test. You can also define your own assertions
literally as simple "assert" methods, which will also auto-generate
"verify" and "waitFor" commands.
Example: Add a valueRepeated assertion, that
makes sure that the element value consists of the supplied text repeated. The 2
commands that would be available in tests would be assertValueRepeated andverifyValueRepeated.
Selenium.prototype.assertValueRepeated =
function(locator, text) {
// All
locator-strategies are automatically handled by "findElement"
var element =
this.page().findElement(locator);
// Create the
text to verify
var
expectedValue = text + text;
// Get the
actual element value
var actualValue
= element.value;
// Make sure
the actual value matches the expected
Assert.matches(expectedValue, actualValue);
};
Automatic availability of storeFoo, assertFoo, assertNotFoo,
waitForFoo and waitForNotFoo for every getFoo
All getFoo and isFoo methods on
the Selenium prototype automatically result in the availability of storeFoo,
assertFoo, assertNotFoo, verifyFoo, verifyNotFoo, waitForFoo, and waitForNotFoo
commands.
Example, if you add a getTextLength() method, the following commands
will automatically be available: storeTextLength, assertTextLength,
assertNotTextLength, verifyTextLength, verifyNotTextLength, waitForTextLength,
and waitForNotTextLength commands.
Selenium.prototype.getTextLength = function(locator,
text) {
return
this.getText(locator).length;
};
Also note that the assertValueRepeated method
described above could have been implemented using isValueRepeated, with the
added benefit of also automatically getting assertNotValueRepeated,
storeValueRepeated, waitForValueRepeated and waitForNotValueRepeated.
Locator Strategies
All locateElementByFoo methods on the PageBot
prototype are added as locator-strategies. A locator strategy takes 2
parameters, the first being the locator string (minus the prefix), and the
second being the document in which to search.
Example: Add a "valuerepeated=" locator, that finds the
first element a value attribute equal to the the supplied value repeated.
// The "inDocument" is a the document you are
searching.
PageBot.prototype.locateElementByValueRepeated =
function(text, inDocument) {
// Create the
text to search for
var expectedValue
= text + text;
// Loop through
all elements, looking for ones that have
// a value ===
our expected value
var allElements
= inDocument.getElementsByTagName("*");
for (var i = 0;
i < allElements.length; i++) {
var testElement
= allElements[i];
if
(testElement.value && testElement.value === expectedValue) {
return
testElement;
}
}
return null;
};
user-extensions.js
By default, Selenium looks for a file called
"user-extensions.js", and loads the javascript code found in that
file. This file provides a convenient location for adding features to Selenium,
without needing to modify the core Selenium sources.
In the standard distibution, this file does not exist. Users can
create this file and place their extension code in this common location,
removing the need to modify the Selenium sources, and hopefully assisting with
the upgrade process.
No comments:
Post a Comment