Defines an object that runs Selenium commands.
Element Locators tell Selenium which HTML element a command refers to. The format of a locator is:
We support the following strategies for locating elements:
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.)
Select the element with the specified @id attribute.
Select the first element with the specified @name attribute.
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.
Find an element by evaluating the specified string. This allows you to traverse the HTML Document Object
Select the link (anchor) element which contains text matching the
link=The link text
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=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 "//"
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. </p>
filterType=argument </p> Supported element-filters are:
Matches elements based on their values. This is particularly useful for refining a list of similarly-named toggle-buttons. </p> index=index
Selects a single element based on its position in the list (offset from zero). </p>
Various Pattern syntaxes are available for matching string values:
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
regular-expressions is available.
Match a string exactly, verbatim, without any of that fancy wildcard
If no pattern prefix is specified, Selenium assumes that it's a "glob" pattern.
Defines a new function for Selenium to locate elements on the page.
For example, if you define the strategy "foo", and someone runs click("foo=blah"), we'll run your function, passing you the string "blah", and click on the element that your function returns, or throw an "Element not found" error if your function returns null.
We'll pass three arguments to your function:
locator: the string the user passed in
inWindow: the currently selected window
inDocument: the currently selected document
The function must return null if the element can't be found.
the name of the strategy to define; this should use only letters [a-zA-Z] with no spaces or other punctuation.
Using the pure-JS xpath library can improve the consistency of xpath element locators between different browser vendors, but the pure-JS version is much slower than the native implementations.
boolean, true means we'll prefer to use native XPath; false means we'll only use JS XPath
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. Selenium will then resume using the default behavior for future confirmations, automatically returning true (OK) unless/until you explicitly call this command for each confirmation.
Undo the effect of calling chooseCancelOnNextConfirmation. Note
that Selenium's overridden window.confirm() function will normally automatically return true, as if the user had manually clicked OK, so you shouldn't need to use this command unless for some reason you need to change your mind prior to the next confirmation. After any confirmation, Selenium will resume using the default behavior for future confirmations, automatically returning true (OK) unless/until you explicitly call chooseCancelOnNextConfirmation for each confirmation.
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.
name and value of the cookie in a format "name=value"
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.
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.
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.
Retrieves the text cursor position in the given input element or textarea; beware, this may not work perfectly on all browsers.
This method will fail if the specified element isn't an input element or textarea, or there is no cursor in the element.
Return: the numerical position of the cursor in the field
an element locator pointing to an input element or textarea
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.
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.
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.
Return: true if the new frame is this code's window
new frame (which might be relative to the current one)
Determine whether currentWindowString plus target identify the window 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" window. In this case, when the test calls selectWindow, this routine is called for each window to figure out which one has been selected. The selected window will return true, while all others will return false.
Return: true if the new window is this code's window
new window (which might be relative to the current one, e.g., "_parent")
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.
Return: true if the specified element is visible, false otherwise
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.
Opens a popup window (if a window with that ID isn't already open).
After opening the window, you'll need to select it using the selectWindow command.
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). In those cases, you can force Selenium to notice the open window's name by using the Selenium openWindow command, using an empty (blank) url, like this: openWindow("", "myFunnyWindow"). </p>
Creates a new "script" tag in the body of the current test window, and
adds the specified text into the body of the command. Scripts run in this way can often be debugged more easily than scripts executed using Selenium's "getEval" command. Beware that JS exceptions thrown in these script tags aren't managed by Selenium, so you should probably wrap your script in try/catch blocks if there is any chance that the script will throw an exception.
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.
matches options based on their labels, i.e. the visible text. (This
is the default.)
matches options based on their values.
matches options based on their ids.
matches an option based on its index (offset from zero).
If no option locator prefix is provided, the default behaviour is to match on label.
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 can also select a frame by its 0-based index number; select the first frame with "index=0", or the third frame with "index=2".
You may also use a DOM expression to identify the frame you want directly, like this:
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.
Selenium has several strategies for finding the window object referred to by the "windowID" parameter.
1.) if windowID is null, (or the string "null") then it is assumed the user is referring to the original window instantiated by the browser).
3.) Otherwise, selenium looks in a hash it maintains that maps string names to window "names".
4.) If that fails, we'll try looping over all of the known windows to try to find the appropriate "title". Since "title" is not necessarily unique, this may have unexpected behavior.
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 which identify the names of windows created via window.open (and therefore intercepted by selenium). You will see messages like the following for each window as it is opened:
debug: window.open call intercepted; window ID (which you can use with selectWindow()) is "myNewWindow"
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). (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 an empty (blank) url, like this: openWindow("", "myFunnyWindow").
Configure the number of pixels between "mousemove" events during dragAndDrop commands (default=10).
If the mouse speed is greater than the distance between the two dragged objects, we'll just send one "mousemove" at the start location and then one final one at the end location.
Simulates keystroke events on the specified element, as though you typed the value key-by-key.
This is a convenience method for calling keyDown, keyUp, keyPress for every character in the specified string; this is useful for dynamic UI widgets (like auto-completing combo boxes) that require explicit key events.
Unlike the simple "type" command, which forces the specified value into the page directly, this command may or may not have any visible effect, even in cases where typing keys would normally have a visible effect. For example, if you use "typeKeys" on a form element, you may or may not see the results of what you typed in the field.
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 send the keystroke events corresponding to what you just typed.
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.
a timeout in milliseconds, after which this command will return with an error