\Testing_Selenium

Defines an object that runs Selenium commands.

<p>
<b>Element Locators</b>
</p><p>

Element Locators tell Selenium which HTML element a command refers to.
The format of a locator is:
</p><p>

<i>locatorType</i><b>=</b><i>argument</i>
</p>
<p>

We support the following strategies for locating elements:

</p>
<ul>

<li>
<b>identifier</b>=<i>id</i>:
Select the element with the specified @id attribute. If no match is
found, select the first element whose @name attribute is <i>id</i>.
(This is normally the default; see below.)
</li>
<li>
<b>id</b>=<i>id</i>:
Select the element with the specified @id attribute.
</li>
<li>
<b>name</b>=<i>name</i>:
Select the first element with the specified @name attribute.

<ul>

<li>
username
</li>
<li>
name=username
</li>
</ul>
>
The name may optionally be followed by one or more <i>element-filters</i>, separated from the name by whitespace. If the <i>filterType</i> is not specified, <b>value</b> is assumed.
</p>
<ul>

<li>
name=flavour value=chocolate
</li>
</ul>
</li>
<li>
<b>dom</b>=<i>javascriptExpression</i>:

Find an element by evaluating the specified string. This allows you to traverse the HTML Document Object
Model using JavaScript. Note that you must not return a value in this string; simply make it the last expression in the block.

<ul>

<li>
dom=document.forms['myForm'].myDropdown
</li>
<li>
dom=document.images[56]
</li>
<li>
dom=function foo() { return document.links[1]; }; foo();
</li>
</ul>
</li>
<li>
<b>xpath</b>=<i>xpathExpression</i>:
Locate an element using an XPath expression.

<ul>

<li>
xpath=//img[@alt='The image alt text']
</li>
<li>
xpath=//table[@id='table1']//tr[4]/td[2]
</li>
<li>
xpath=//a[contains(@href,'#id1')]
</li>
<li>
xpath=//a[contains(@href,'#id1')]/@class
</li>
<li>
xpath=(//table[@class='stylee'])//th[text()='theHeaderText']/../td
</li>
<li>
xpath=//input[@name='name2' and @value='yes']
</li>
<li>
xpath=//*[text()="right"]
</li>
</ul>
</li>
<li>
<b>link</b>=<i>textPattern</i>:
Select the link (anchor) element which contains text matching the
specified <i>pattern</i>.

<ul>

<li>
link=The link text
</li>
</ul>
</li>
<li>
<b>css</b>=<i>cssSelectorSyntax</i>:
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.

<ul>

<li>
css=a[href="#id3"]
</li>
<li>
css=span#firstChild + span
</li>
</ul>
>
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>
</li>
<li>
<b>ui</b>=<i>uiSpecifierString</i>:
Locate an element by resolving the UI specifier string to another locator, and evaluating it. See the Selenium UI-Element Reference for more details.

<ul>

<li>
ui=loginPages::loginButton()
</li>
<li>
ui=settingsPages::toggle(label=Hide Email)
</li>
<li>
ui=forumPages::postBody(index=2)//a[2]
</li>
</ul>
</li>
</ul><p>

Without an explicit locator prefix, Selenium uses the following default
strategies:

</p>
<ul>

<li>
<b>dom</b>, for locators starting with "document."
</li>
<li>
<b>xpath</b>, for locators starting with "//"
</li>
<li>
<b>identifier</b>, otherwise
</li>
</ul>
<p>
<b>Element Filters</b>
</p><p>

<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>
>
Filters look much like locators, ie.
</p>
>

<i>filterType</i><b>=</b><i>argument</i>
</p>
<p>
Supported element-filters are:
</p>
>
<b>value=</b><i>valuePattern</i>
</p>
>


Matches elements based on their values. This is particularly useful for refining a list of similarly-named toggle-buttons.
</p>
<p>
<b>index=</b><i>index</i>
</p>
>


Selects a single element based on its position in the list (offset from zero).
</p>

</p>

<p>
<b>String-match Patterns</b>
</p><p>

Various Pattern syntaxes are available for matching string values:

</p>
<ul>

<li>
<b>glob:</b><i>pattern</i>:
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.
</li>
<li>
<b>regexp:</b><i>regexp</i>:
Match a string using a regular-expression. The full power of JavaScript
regular-expressions is available.
</li>
<li>
<b>regexpi:</b><i>regexpi</i>:
Match a string using a case-insensitive regular-expression.
</li>
<li>
<b>exact:</b><i>string</i>:

Match a string exactly, verbatim, without any of that fancy wildcard
stuff.
</li>
</ul><p>

If no pattern prefix is specified, Selenium assumes that it's a "glob"
pattern.

</p><p>

For commands that return multiple values (such as verifySelectOptions),
the string being matched is a comma-separated list of the return values,
where both commas and backslashes in the values are backslash-escaped.
When providing a pattern, the optional matching syntax (i.e. glob,
regexp, etc.) is specified once, as usual, at the beginning of the
pattern.

</p>

Synopsis

class Testing_Selenium {
}

Members

private

  • $browser — string
  • $browserUrl — string
  • $host — string
  • $port — int
  • $sessionId — string
  • $timeout — string

Methods

private

protected

public

  • __construct() — Constructor
  • addLocationStrategy() — Defines a new function for Selenium to locate elements on the page.
  • addScript() — Loads script content into a new script tag in the Selenium document. This differs from the runScript command in that runScript adds the script tag to the document of the AUT, not the Selenium document. The following entities in the script content are replaced by the characters they represent:
  • addSelection() — Add a selection to the set of selected options in a multi-select element using an option locator.
  • allowNativeXpath() — Specifies whether Selenium should use the native in-browser implementation of XPath (if any native version is available); if you pass "false" to this function, we will always use our pure-JavaScript xpath library.
  • altKeyDown() — Press the alt key and hold it down until doAltUp() is called or a new page is loaded.
  • altKeyUp() — Release the alt key.
  • answerOnNextPrompt() — Instructs Selenium to return the specified answer string in response to the next JavaScript prompt [window.prompt()].
  • assignId() — Temporarily sets the "id" attribute of the specified element, so you can locate it in the future using its ID rather than a slow/complicated XPath. This ID will disappear once the page is reloaded.
  • attachFile() — Sets a file input (upload) field to the file listed in fileLocator
  • captureEntirePageScreenshot() — Saves the entire contents of the current window canvas to a PNG file.
  • captureEntirePageScreenshotToString() — Downloads a screenshot of the browser current window canvas to a based 64 encoded PNG file. The <i>entire</i> windows canvas is captured, including parts rendered outside of the current view port.
  • captureScreenshot() — Captures a PNG screenshot to the specified file.
  • captureScreenshotToString() — Capture a PNG screenshot. It then returns the file as a base 64 encoded string.
  • check() — Check a toggle-button (checkbox/radio)
  • chooseCancelOnNextConfirmation() — <p>
  • chooseOkOnNextConfirmation() — <p>
  • click() — 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.
  • clickAt() — 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.
  • close() — Simulates the user clicking the "close" button in the titlebar of a popup window or tab.
  • contextMenu() — Simulates opening the context menu for the specified element (as might happen if the user "right-clicked" on the element).
  • contextMenuAt() — Simulates opening the context menu for the specified element (as might happen if the user "right-clicked" on the element).
  • controlKeyDown() — Press the control key and hold it down until doControlUp() is called or a new page is loaded.
  • controlKeyUp() — Release the control key.
  • createCookie() — 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.
  • deleteAllVisibleCookies() — Calls deleteCookie with recurse=true on all cookies visible to the current page.
  • deleteCookie() — Delete a named cookie with specified path and domain. Be careful; to delete a cookie, you need to delete it using the exact same path and domain that were used to create the cookie.
  • deselectPopUp() — Selects the main window. Functionally equivalent to using <code>selectWindow()</code> and specifying no value for <code>windowID</code>.
  • doubleClick() — Double clicks on a link, button, checkbox or radio button. If the double click action causes a new page to load (like a link usually does), call waitForPageToLoad.
  • doubleClickAt() — Doubleclicks on a link, button, checkbox or radio button. If the action causes a new page to load (like a link usually does), call waitForPageToLoad.
  • dragAndDrop() — Drags an element a certain distance and then drops it
  • dragAndDropToObject() — Drags an element and drops it on another element
  • dragdrop() — deprecated - use dragAndDrop instead
  • fireEvent() — Explicitly simulate an event, to trigger the corresponding "on<i>event</i>" handler.
  • focus() — Move the focus to the specified element; for example, if the element is an input field, move the cursor to that field.
  • getAlert() — Retrieves the message of a JavaScript alert generated during the previous action, or fail if there were no alerts.
  • getAllButtons() — Returns the IDs of all buttons on the page.
  • getAllFields() — Returns the IDs of all input fields on the page.
  • getAllWindowIds() — Returns the IDs of all windows that the browser knows about in an array.
  • getAllWindowNames() — Returns the names of all windows that the browser knows about in an array.
  • getAllWindowTitles() — Returns the titles of all windows that the browser knows about in an array.
  • getAttribute() — Gets the value of an element attribute. The value of the attribute may differ across browsers (this is the case for the "style" attribute, for example).
  • getAttributeFromAllWindows() — Returns an array of JavaScript property values from all known windows having one.
  • getBodyText() — Gets the entire text of the page.
  • getConfirmation() — Retrieves the message of a JavaScript confirmation dialog generated during the previous action.
  • getCookie() — Return all cookies of the current page under test.
  • getCookieByName() — Returns the value of the cookie with the specified name, or throws an error if the cookie is not present.
  • getCursorPosition() — Retrieves the text cursor position in the given input element or textarea; beware, this may not work perfectly on all browsers.
  • getElementHeight() — Retrieves the height of an element
  • getElementIndex() — Get the relative index of an element to its parent (starting from 0). The comment node and empty text node will be ignored.
  • getElementPositionLeft() — Retrieves the horizontal position of an element
  • getElementPositionTop() — Retrieves the vertical position of an element
  • getElementWidth() — Retrieves the width of an element
  • getEval() — 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.
  • getExpression() — Returns the specified expression.
  • getHtmlSource() — Returns the entire HTML source between the opening and closing "html" tags.
  • getLocation() — Gets the absolute URL of the current page.
  • getMouseSpeed() — Returns the number of pixels between "mousemove" events during dragAndDrop commands (default=10).
  • getPrompt() — Retrieves the message of a JavaScript question prompt dialog generated during the previous action.
  • getSelectOptions() — Gets all option labels in the specified select drop-down.
  • getSelectedId() — Gets option element ID for selected option in the specified select element.
  • getSelectedIds() — Gets all option element IDs for selected options in the specified select or multi-select element.
  • getSelectedIndex() — Gets option index (option number, starting at 0) for selected option in the specified select element.
  • getSelectedIndexes() — Gets all option indexes (option number, starting at 0) for selected options in the specified select or multi-select element.
  • getSelectedLabel() — Gets option label (visible text) for selected option in the specified select element.
  • getSelectedLabels() — Gets all option labels (visible text) for selected options in the specified select or multi-select element.
  • getSelectedValue() — Gets option value (value attribute) for selected option in the specified select element.
  • getSelectedValues() — Gets all option values (value attributes) for selected options in the specified select or multi-select element.
  • getSpeed() — 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., the delay is 0 milliseconds.
  • getTable() — Gets the text from a cell of a table. The cellAddress syntax tableLocator.row.column, where row and column start at 0.
  • getText() — 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.
  • getTitle() — Gets the title of the current page.
  • getValue() — Gets the (whitespace-trimmed) value of an input field (or anything else with a value parameter).
  • getWhetherThisFrameMatchFrameExpression() — Determine whether current/locator identify the frame containing this running code.
  • getWhetherThisWindowMatchWindowExpression() — Determine whether currentWindowString plus target identify the window containing this running code.
  • getXpathCount() — Returns the number of nodes that match the specified xpath, eg. "//table" would give the number of tables.
  • goBack() — Simulates the user clicking the "back" button on their browser.
  • highlight() — Briefly changes the backgroundColor of the specified element yellow. Useful for debugging.
  • ignoreAttributesWithoutValue() — Specifies whether Selenium will ignore xpath attributes that have no value, i.e. are the empty string, when using the non-native xpath evaluation engine. You'd want to do this for performance reasons in IE.
  • isAlertPresent() — Has an alert occurred?
  • isChecked() — Gets whether a toggle-button (checkbox/radio) is checked. Fails if the specified element doesn't exist or isn't a toggle-button.
  • isConfirmationPresent() — Has confirm() been called?
  • isCookiePresent() — Returns true if a cookie with the specified name is present, or false otherwise.
  • isEditable() — Determines whether the specified input element is editable, ie hasn't been disabled.
  • isElementPresent() — Verifies that the specified element is somewhere on the page.
  • isOrdered() — Check if these two elements have same parent and are ordered siblings in the DOM. Two same elements will not be considered ordered.
  • isPromptPresent() — Has a prompt occurred?
  • isSomethingSelected() — Determines whether some option in a drop-down menu is selected.
  • isTextPresent() — Verifies that the specified text pattern appears somewhere on the rendered page shown to the user.
  • isVisible() — 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.
  • keyDown() — Simulates a user pressing a key (without releasing it yet).
  • keyDownNative() — Simulates a user pressing a key (without releasing it yet) by sending a native operating system keystroke.
  • keyPress() — Simulates a user pressing and releasing a key.
  • keyPressNative() — Simulates a user pressing and releasing a key by sending a native operating system keystroke.
  • keyUp() — Simulates a user releasing a key.
  • keyUpNative() — Simulates a user releasing a key by sending a native operating system keystroke.
  • metaKeyDown() — Press the meta key and hold it down until doMetaUp() is called or a new page is loaded.
  • metaKeyUp() — Release the meta key.
  • mouseDown() — Simulates a user pressing the left mouse button (without releasing it yet) on the specified element.
  • mouseDownAt() — Simulates a user pressing the left mouse button (without releasing it yet) at the specified location.
  • mouseDownRight() — Simulates a user pressing the right mouse button (without releasing it yet) on the specified element.
  • mouseDownRightAt() — Simulates a user pressing the right mouse button (without releasing it yet) at the specified location.
  • mouseMove() — Simulates a user pressing the mouse button (without releasing it yet) on the specified element.
  • mouseMoveAt() — Simulates a user pressing the mouse button (without releasing it yet) on the specified element.
  • mouseOut() — Simulates a user moving the mouse pointer away from the specified element.
  • mouseOver() — Simulates a user hovering a mouse over the specified element.
  • mouseUp() — Simulates the event that occurs when the user releases the mouse button (i.e., stops holding the button down) on the specified element.
  • mouseUpAt() — Simulates the event that occurs when the user releases the mouse button (i.e., stops holding the button down) at the specified location.
  • mouseUpRight() — Simulates the event that occurs when the user releases the right mouse button (i.e., stops holding the button down) on the specified element.
  • mouseUpRightAt() — Simulates the event that occurs when the user releases the right mouse button (i.e., stops holding the button down) at the specified location.
  • open() — Opens an URL in the test frame. This accepts both relative and absolute URLs.
  • openWindow() — Opens a popup window (if a window with that ID isn't already open).
  • refresh() — Simulates the user clicking the "Refresh" button on their browser.
  • removeAllSelections() — Unselects all of the selected options in a multi-select element.
  • removeScript() — Removes a script tag from the Selenium document identified by the given id. Does nothing if the referenced tag doesn't exist.
  • removeSelection() — Remove a selection from the set of selected options in a multi-select element using an option locator.
  • retrieveLastRemoteControlLogs() — Retrieve the last messages logged on a specific remote control. Useful for error reports, especially when running multiple remote controls in a distributed environment. The maximum number of log messages that can be retrieve is configured on remote control startup.
  • rollup() — Executes a command rollup, which is a series of commands with a unique name, and optionally arguments that control the generation of the set of commands. If any one of the rolled-up commands fails, the rollup is considered to have failed. Rollups may also contain nested rollups.
  • runScript() — 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() — Select an option from a drop-down using an option locator.
  • selectFrame() — 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".
  • selectPopUp() — Simplifies the process of selecting a popup window (and does not offer functionality beyond what <code>selectWindow()</code> already provides).
  • selectWindow() — Selects a popup window using a window locator; once a popup window has been selected, all commands go to that window. To select the main window again, use null as the target.
  • setBrowserLogLevel() — Sets the threshold for browser-side logging messages; log messages beneath this threshold will be discarded.
  • setContext() — Writes a message to the status bar and adds a note to the browser-side log.
  • setCursorPosition() — Moves the text cursor to the specified position in the given input element or textarea.
  • setMouseSpeed() — Configure the number of pixels between "mousemove" events during dragAndDrop commands (default=10).
  • setSpeed() — 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., the delay is 0 milliseconds.
  • setTimeout() — Specifies the amount of time that Selenium will wait for actions to complete.
  • shiftKeyDown() — Press the shift key and hold it down until doShiftUp() is called or a new page is loaded.
  • shiftKeyUp() — Release the shift key.
  • shutDownSeleniumServer() — Kills the running Selenium Server and all browser sessions. After you run this command, you will no longer be able to send commands to the server; you can't remotely start the server once it has been stopped. Normally you should prefer to run the "stop" command, which terminates the current browser session, rather than shutting down the entire server.
  • start() — Run the browser and set session id.
  • stop() — Close the browser and set session id null
  • submit() — Submit the specified form. This is particularly useful for forms without submit buttons, e.g. single-input "Search" forms.
  • type() — Sets the value of an input field, as though you typed it in.
  • typeKeys() — Simulates keystroke events on the specified element, as though you typed the value key-by-key.
  • uncheck() — Uncheck a toggle-button (checkbox/radio)
  • useXpathLibrary() — Allows choice of one of the available libraries.
  • waitForCondition() — Runs the specified JavaScript snippet repeatedly until it evaluates to "true".
  • waitForFrameToLoad() — Waits for a new frame to load.
  • waitForPageToLoad() — Waits for a new page to load.
  • waitForPopUp() — Waits for a popup window to appear and load up.
  • windowFocus() — Gives focus to the currently selected window
  • windowMaximize() — Resize currently selected window to take up the entire screen