<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.3.5: http://docutils.sourceforge.net/" /> <title>Selenium Reference</title> <link rel="stylesheet" href="default.css" type="text/css" /> </head> <body> <h1 class="title">Selenium Reference</h1> <div class="document" id="selenium-reference"> <blockquote> <p>A <strong>command</strong> is what tells Selenium what to do. Selenium commands come in two 'flavors', <strong>Actions</strong> and <strong>Assertions</strong>. Each command call is one line in the test table of the form:</p> <blockquote> <table border="1" class="table"> <colgroup> <col width="39%" /> <col width="33%" /> <col width="28%" /> </colgroup> <tbody valign="top"> <tr><td>command</td> <td>target</td> <td>value</td> </tr> </tbody> </table> </blockquote> <p><strong>Actions</strong> 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.</p> <p><strong>Checks</strong> verify the state of the application conforms to what is expected. Examples include "make sure the page title is X" and "check that this checkbox is checked". It is possible to tell Selenium to stop the test when an Assertion fails, or to simply record the failure and continue.</p> <p><strong>Element Locators</strong> 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.</p> <p><strong>Patterns</strong> 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.</p> </blockquote> <div class="section" id="element-locators"> <h1><a name="element-locators">Element Locators</a></h1> <blockquote> <p>Element Locators allow Selenium to identify which HTML element a command refers to. We support the following strategies for locating elements:</p> <dl> <dt><strong>id=</strong><em>id</em></dt> <dd>Select the element with the specified @id attribute.</dd> <dt><strong>name=</strong><em>name</em></dt> <dd>Select the first element with the specified @name attribute.</dd> <dt><strong>identifier=</strong><em>id</em></dt> <dd>Select the element with the specified @id attribute. If no match is found, select the first element whose @name attribute is <em>id</em>.</dd> <dt><strong>dom=</strong><em>javascriptExpression</em></dt> <dd><dl class="first last"> <dt>Find an element using JavaScript traversal of the HTML Document Object Model. DOM locators <em>must</em> begin with "document.".</dt> <dd><ul class="first last simple"> <li>dom=document.forms['myForm'].myDropdown</li> <li>dom=document.images[56]</li> </ul> </dd> </dl> </dd> <dt><strong>xpath=</strong><em>xpathExpression</em></dt> <dd><dl class="first last"> <dt>Locate an element using an XPath expression. XPath locators <em>must</em> begin with "//".</dt> <dd><ul class="first last simple"> <li>xpath=//img[@alt='The image alt text']</li> <li>xpath=//table[@id='table1']//tr[4]/td[2]</li> </ul> </dd> </dl> </dd> <dt><strong>link=</strong><em>textPattern</em></dt> <dd><dl class="first last"> <dt>Select the link (anchor) element which contains text matching the specified <em>pattern</em>.</dt> <dd><ul class="first last simple"> <li>link=The link text</li> </ul> </dd> </dl> </dd> </dl> <p>Without a locator prefix, Selenium uses:</p> <ul class="simple"> <li><strong>dom</strong>, for locators starting with "document."</li> <li><strong>xpath</strong>, for locators starting with "//"</li> <li><strong>identifier</strong>, otherwise</li> </ul> </blockquote> </div> <div class="section" id="select-option-specifiers"> <h1><a name="select-option-specifiers">Select Option Specifiers</a></h1> <blockquote> <p>Select Option Specifiers 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 Specifier.</p> <dl> <dt><strong>label=</strong><em>labelPattern</em></dt> <dd><dl class="first last"> <dt>matches options based on their labels, i.e. the visible text. </dt> <dd><ul class="first last simple"> <li>label=regexp:^[Oo]ther</li> </ul> </dd> </dl> </dd> <dt><strong>value=</strong><em>valuePattern</em></dt> <dd><dl class="first last"> <dt>matches options based on their values. </dt> <dd><ul class="first last simple"> <li>value=other</li> </ul> </dd> </dl> </dd> <dt><strong>id=</strong><em>id</em></dt> <dd><dl class="first last"> <dt>matches options based on their ids. </dt> <dd><ul class="first last simple"> <li>id=option1</li> </ul> </dd> </dl> </dd> <dt><strong>index=</strong><em>index</em></dt> <dd><dl class="first last"> <dt>matches an option based on its index (offset from zero).</dt> <dd><ul class="first last simple"> <li>index=2</li> </ul> </dd> </dl> </dd> </dl> <p>Without a prefix, the default behaviour is to only match on labels.</p> </blockquote> </div> <div class="section" id="string-match-patterns"> <h1><a name="string-match-patterns">String-match Patterns</a></h1> <blockquote> <p>Various Pattern syntaxes are available for matching string values:</p> <dl> <dt><strong>glob:</strong><em>pattern</em></dt> <dd>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.</dd> <dt><strong>regexp:</strong><em>regexp</em></dt> <dd>Match a string using a regular-expression. The full power of JavaScript regular-expressions is available.</dd> <dt><strong>exact:</strong><em>string</em></dt> <dd>Match a string exactly, verbatim, without any of that fancy wildcard stuff.</dd> </dl> <p>If no pattern prefix is specified, Selenium assumes that it's a "glob" pattern.</p> </blockquote> </div> <div class="section" id="selenium-actions"> <h1><a name="selenium-actions">Selenium Actions</a></h1> <blockquote> <p>Actions tell Selenium to do something in the application. They generally represent something a user would do.</p> <p>Many <strong>Actions</strong> can be called with the "AndWait" suffix. 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. The exceptions to this pattern are the "open" and "click" actions, which will both wait for a page to load by default.</p> <p><strong>open</strong>( <em>url</em> )</p> <blockquote> <p>Opens a URL in the test frame. This accepts both relative and absolute URLs.</p> <p><em>Note</em>: The URL must be on the same site as Selenium due to security restrictions in the browser (Cross Site Scripting).</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="15%" /> <col width="65%" /> <col width="19%" /> </colgroup> <tbody valign="top"> <tr><td>open</td> <td>/mypage</td> <td> </td> </tr> <tr><td>open</td> <td><a class="reference" href="http://localhost/">http://localhost/</a></td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>click</strong>( <em>elementLocator</em> )</p> <blockquote> <p>Clicks on a link, button, checkbox or radio button. If the click action causes a new page to load (like a link usually does), use "clickAndWait".</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="34%" /> <col width="51%" /> <col width="14%" /> </colgroup> <tbody valign="top"> <tr><td>click</td> <td>aCheckbox</td> <td> </td> </tr> <tr><td>clickAndWait</td> <td>submitButton</td> <td> </td> </tr> <tr><td>clickAndWait</td> <td>anyLink</td> <td> </td> </tr> </tbody> </table> </blockquote> <dl> <dt><strong>note:</strong></dt> <dd>Selenium will <em>always</em> automatically click on a popup dialog raised by the alert() or confirm() methods. (The exception is those raised during 'onload', which are not yet handled by Selenium). You <em>must</em> use [verify|assert]Alert or [verify|assert]Confirmation to tell Selenium that you expect the popup dialog. You may use chooseCancelOnNextConfirmation to click 'cancel' on the next confirmation dialog instead of clicking 'OK'.</dd> </dl> </blockquote> <p><strong>type</strong>( <em>inputLocator</em>, <em>value</em> )</p> <blockquote> <p>Sets the <em>value</em> of an input field, as though you typed it in.</p> <p>Can also be used to set the value of combo boxes, check boxes, etc. In these cases, <em>value</em> should be the value of the option selected, not the visible text.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="23%" /> <col width="55%" /> <col width="21%" /> </colgroup> <tbody valign="top"> <tr><td>type</td> <td>nameField</td> <td>John Smith</td> </tr> <tr><td>typeAndWait</td> <td>textBoxThatSubmitsOnChange</td> <td>newValue</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>select</strong>( <em>dropDownLocator</em>, <em>optionSpecifier</em> )</p> <blockquote> <p>Select an option from a drop-down, based on the <em>optionSpecifier</em>. If more than one option matches the specifier (e.g. due to the use of globs like "f*b*", or due to more than one option having the same label or value), then the first matches is selected.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="27%" /> <col width="33%" /> <col width="40%" /> </colgroup> <tbody valign="top"> <tr><td>select</td> <td>dropDown</td> <td>Australian Dollars</td> </tr> <tr><td>select</td> <td>dropDown</td> <td>index=0</td> </tr> <tr><td>selectAndWait</td> <td>currencySelector</td> <td>value=AUD</td> </tr> <tr><td>selectAndWait</td> <td>currencySelector</td> <td>label=Aus*lian D*rs</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>selectWindow</strong>( <em>windowId</em> )</p> <blockquote> <p>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.</p> <p><strong>target:</strong> The id of the window to select.</p> <p><strong>value:</strong> <em>ignored</em></p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="40%" /> <col width="43%" /> <col width="17%" /> </colgroup> <tbody valign="top"> <tr><td>selectWindow</td> <td>myPopupWindow</td> <td> </td> </tr> <tr><td>selectWindow</td> <td>null</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>goBack</strong>()</p> <blockquote> <p>Simulates the user clicking the "back" button on their browser.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="40%" /> <col width="27%" /> <col width="33%" /> </colgroup> <tbody valign="top"> <tr><td>goBack</td> <td> </td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>close</strong>()</p> <blockquote> <p>Simulates the user clicking the "close" button in the titlebar of a popup window.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="40%" /> <col width="27%" /> <col width="33%" /> </colgroup> <tbody valign="top"> <tr><td>close</td> <td> </td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>pause</strong>( <em>milliseconds</em> )</p> <blockquote> <p>Pauses the execution of the test script for a specified amount of time. This is useful for debugging a script or pausing to wait for some server side action.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="36%" /> <col width="29%" /> <col width="36%" /> </colgroup> <tbody valign="top"> <tr><td>pause</td> <td>5000</td> <td> </td> </tr> <tr><td>pause</td> <td>2000</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>fireEvent</strong>( <em>elementLocator</em>, <em>eventName</em> )</p> <blockquote> <p>Explicitly simulate an event, to trigger the corresponding "on<em>event</em>" handler.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="32%" /> <col width="39%" /> <col width="29%" /> </colgroup> <tbody valign="top"> <tr><td>fireEvent</td> <td>textField</td> <td>focus</td> </tr> <tr><td>fireEvent</td> <td>dropDown</td> <td>blur</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>waitForValue</strong>( <em>inputLocator</em>, <em>value</em> )</p> <blockquote> <p>Waits for a specified input (e.g. a hidden field) to have a specified <em>value</em>. Will succeed immediately if the input already has the value. This is implemented by polling for the value. Warning: can block indefinitely if the input never has the specified value.</p> <p><strong>example:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="32%" /> <col width="42%" /> <col width="26%" /> </colgroup> <tbody valign="top"> <tr><td>waitForValue</td> <td>finishIndication</td> <td>isfinished</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>store</strong>( <em>valueToStore</em>, <em>variableName</em> )</p> <blockquote> <p>Stores a value into a variable. The value can be constructed using either variable substitution or javascript evaluation, as detailed in 'Parameter construction and Variables' (below).</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="16%" /> <col width="70%" /> <col width="14%" /> </colgroup> <tbody valign="top"> <tr><td>store</td> <td>Mr John Smith</td> <td>fullname</td> </tr> <tr><td>store</td> <td>${title} ${firstname} ${surname}</td> <td>fullname</td> </tr> <tr><td>store</td> <td>javascript{Math.round(Math.PI * 100) / 100}</td> <td>PI</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>storeValue</strong>( <em>inputLocator</em>, <em>variableName</em> )</p> <blockquote> <p>Stores the value of an input field into a variable.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="36%" /> <col width="32%" /> <col width="32%" /> </colgroup> <tbody valign="top"> <tr><td>storeValue</td> <td>userName</td> <td>userID</td> </tr> <tr><td>type</td> <td>userName</td> <td>${userID}</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>storeText</strong>( <em>elementLocator</em>, <em>variableName</em> )</p> <blockquote> <p>Stores the text of an element into a variable.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="26%" /> <col width="26%" /> <col width="48%" /> </colgroup> <tbody valign="top"> <tr><td>storeText</td> <td>currentDate</td> <td>expectedStartDate</td> </tr> <tr><td>verifyValue</td> <td>startDate</td> <td>${expectedStartDate}</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>storeAttribute</strong>( <em>elementLocator</em>@<em>attributeName</em>, <em>variableName</em> )</p> <blockquote> <p>Stores the value of an element attribute into a variable.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="31%" /> <col width="29%" /> <col width="41%" /> </colgroup> <tbody valign="top"> <tr><td>storeAttribute</td> <td>input1@class</td> <td>classOfInput1</td> </tr> <tr><td>verifyAttribute</td> <td>input2@class</td> <td>${classOfInput1}</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>chooseCancelOnNextConfirmation</strong>()</p> <blockquote> <p>Instructs Selenium to click <strong>Cancel</strong> on the next javascript confirmation dialog to be raised. By default, the confirm function will return true, having the same effect as manually clicking OK. After running this command, the next confirmation will behave as if the user had clicked Cancel.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="75%" /> <col width="13%" /> <col width="13%" /> </colgroup> <tbody valign="top"> <tr><td>chooseCancelOnNextConfirmation</td> <td> </td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>answerOnNextPrompt</strong>( <em>answerString</em> )</p> <blockquote> <p>Instructs Selenium to return the specified <em>answerString</em> in response to the next prompt.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="65%" /> <col width="23%" /> <col width="13%" /> </colgroup> <tbody valign="top"> <tr><td>answerOnNextPrompt</td> <td>Kangaroo</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> </blockquote> </div> <div class="section" id="selenium-checks"> <h1><a name="selenium-checks">Selenium Checks</a></h1> <blockquote> <p>Checks are used to verify the state of the application. They can be used to check the value of a form field, the presense of some text, or the URL of the current page.</p> <p>All Selenium Checks can be used in 2 modes, "assert" and "verify". These behave identically, except that when an "assert" check fails, the test is aborted. When a "verify" check fails, the test will continue execution. This allows a single "assert" to ensure that the application is on the correct page, followed by a bunch of "verify" checks to test form field values, labels, etc.</p> <p><strong>assertLocation</strong>( <em>relativeLocation</em> )</p> <blockquote> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="54%" /> <col width="27%" /> <col width="19%" /> </colgroup> <tbody valign="top"> <tr><td>verifyLocation</td> <td>/mypage</td> <td> </td> </tr> <tr><td>assertLocation</td> <td>/mypage</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertTitle</strong>( <em>titlePattern</em> )</p> <blockquote> <p>Verifies the title of the current page.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="48%" /> <col width="30%" /> <col width="22%" /> </colgroup> <tbody valign="top"> <tr><td>verifyTitle</td> <td>My Page</td> <td> </td> </tr> <tr><td>assertTitle</td> <td>My Page</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertValue</strong>( <em>inputLocator</em>, <em>valuePattern</em> )</p> <blockquote> <p>Verifies the 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.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="23%" /> <col width="56%" /> <col width="21%" /> </colgroup> <tbody valign="top"> <tr><td>verifyValue</td> <td>nameField</td> <td>John Smith</td> </tr> <tr><td>assertValue</td> <td>document.forms[2].nameField</td> <td>John Smith</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertSelected</strong>( <em>selectLocator</em>, <em>optionSpecifier</em> )</p> <blockquote> <p>Verifies that the selected option of a drop-down satisfies the <em>optionSpecifier</em>.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="25%" /> <col width="49%" /> <col width="25%" /> </colgroup> <tbody valign="top"> <tr><td>verifySelected</td> <td>dropdown2</td> <td>John Smith</td> </tr> <tr><td>verifySelected</td> <td>dropdown2</td> <td>value=js*123</td> </tr> <tr><td>assertSelected</td> <td>document.forms[2].dropDown</td> <td>label=J* Smith</td> </tr> <tr><td>assertSelected</td> <td>document.forms[2].dropDown</td> <td>index=0</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertSelectOptions</strong>( <em>selectLocator</em>, <em>optionLabelList</em> )</p> <blockquote> <p>Verifies the labels of all options in a drop-down against a comma-separated list. Commas in an expected option can be escaped as ",".</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="29%" /> <col width="41%" /> <col width="30%" /> </colgroup> <tbody valign="top"> <tr><td>verifySelectOptions</td> <td>dropdown2</td> <td>John Smith,Dave Bird</td> </tr> <tr><td>assertSelectOptions</td> <td>document.forms[2].dropDown</td> <td>Smith\, J,Bird\, D</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertText</strong>( <em>elementLocator</em>, <em>textPattern</em> )</p> <blockquote> <p>Verifies 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.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="25%" /> <col width="50%" /> <col width="25%" /> </colgroup> <tbody valign="top"> <tr><td>verifyText</td> <td>statusMessage</td> <td>Successful</td> </tr> <tr><td>assertText</td> <td>//div[@id='foo']//h1</td> <td>Successful</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertAttribute</strong>( <em>elementLocator</em>@<em>attributeName</em>, <em>valuePattern</em> )</p> <blockquote> <p>Verifies the value of an element attribute.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="32%" /> <col width="47%" /> <col width="21%" /> </colgroup> <tbody valign="top"> <tr><td>verifyAttribute</td> <td>txt1@class</td> <td>bigAndBold</td> </tr> <tr><td>assertAttribute</td> <td>document.images[0]@alt</td> <td>alt-text</td> </tr> <tr><td>verifyAttribute</td> <td>//img[@id='foo']/@alt</td> <td>alt-text</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertTextPresent</strong>( <em>text</em> )</p> <blockquote> <p>Verifies that the specified text appears somewhere on the rendered page shown to the user.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="39%" /> <col width="50%" /> <col width="11%" /> </colgroup> <tbody valign="top"> <tr><td>verifyTextPresent</td> <td>You are now logged in.</td> <td> </td> </tr> <tr><td>assertTextPresent</td> <td>You are now logged in.</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertTextNotPresent</strong>( <em>text</em> )</p> <blockquote> Verifies that the specified text does NOT appear anywhere on the rendered page.</blockquote> <p><strong>assertElementPresent</strong>( <em>elementLocator</em> )</p> <blockquote> <p>Verifies that the specified element is somewhere on the page.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="48%" /> <col width="40%" /> <col width="12%" /> </colgroup> <tbody valign="top"> <tr><td>verifyElementPresent</td> <td>submitButton</td> <td> </td> </tr> <tr><td>assertElementPresent</td> <td>//img[@alt='foo']</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertElementNotPresent</strong>( <em>elementLocator</em> )</p> <blockquote> <p>Verifies that the specified element is NOT on the page.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="58%" /> <col width="30%" /> <col width="13%" /> </colgroup> <tbody valign="top"> <tr><td>verifyElementNotPresent</td> <td>cancelButton</td> <td> </td> </tr> <tr><td>assertElementNotPresent</td> <td>cancelButton</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertTable</strong>( <em>cellAddress</em>, <em>valuePattern</em> )</p> <blockquote> <p>Verifies the text in a cell of a table. The <em>cellAddress</em> syntax <em>tableName.row.column</em>, where row and column start at 0.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="35%" /> <col width="35%" /> <col width="29%" /> </colgroup> <tbody valign="top"> <tr><td>verifyTable</td> <td>myTable.1.6</td> <td>Submitted</td> </tr> <tr><td>assertTable</td> <td>results.0.2</td> <td>13</td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertVisible</strong>( <em>elementLocator</em> )</p> <blockquote> <p>Verifies that the specified element is both present <em>and</em> 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.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="50%" /> <col width="31%" /> <col width="19%" /> </colgroup> <tbody valign="top"> <tr><td>verifyVisible</td> <td>postcode</td> <td> </td> </tr> <tr><td>assertVisible</td> <td>postcode</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertNotVisible</strong>( <em>elementLocator</em> )</p> <blockquote> <p>Verifies that the specified element is NOT visible. Elements that are simply not present are also considered invisible.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="55%" /> <col width="28%" /> <col width="17%" /> </colgroup> <tbody valign="top"> <tr><td>verifyNotVisible</td> <td>postcode</td> <td> </td> </tr> <tr><td>assertNotVisible</td> <td>postcode</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>verifyEditable / assertEditable</strong>( <em>inputLocator</em> )</p> <blockquote> <p>Verifies that the specified element is editable, ie. it's an input element, and hasn't been disabled.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="52%" /> <col width="30%" /> <col width="19%" /> </colgroup> <tbody valign="top"> <tr><td>verifyEditable</td> <td>shape</td> <td> </td> </tr> <tr><td>assertEditable</td> <td>colour</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertNotEditable</strong>( <em>inputLocator</em> )</p> <blockquote> Verifies that the specified element is NOT editable, ie. it's NOT an input element, or has been disabled.</blockquote> <p><strong>assertAlert</strong>( <em>messagePattern</em> )</p> <blockquote> <p>Verifies that a javascript alert with the specified message was generated. Alerts must be verified in the same order that they were generated.</p> <p>Verifying an alert has the same effect as manually clicking OK. If an alert is generated but you do not verify it, the next Selenium action will fail.</p> <p>NOTE: under Selenium, javascript alerts will NOT pop up a visible alert dialog.</p> <p>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 you manually click OK.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="36%" /> <col width="51%" /> <col width="13%" /> </colgroup> <tbody valign="top"> <tr><td>verifyAlert</td> <td>Invalid Phone Number</td> <td> </td> </tr> <tr><td>assertAlert</td> <td>Invalid Phone Number</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertConfirmation</strong>( <em>messagePattern</em> )</p> <blockquote> <p>Verifies that a javascript confirmation dialog with the specified message was generated. Like alerts, confirmations must be verified in the same order that they were generated.</p> <p>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 <strong>chooseCancelOnNextConfirmation</strong> command (see above). If an confirmation is generated but you do not verify it, the next Selenium action will fail.</p> <p>NOTE: under Selenium, javascript confirmations will NOT pop up a visible dialog.</p> <p>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.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="42%" /> <col width="47%" /> <col width="12%" /> </colgroup> <tbody valign="top"> <tr><td>assertConfirmation</td> <td>Remove this user?</td> <td> </td> </tr> <tr><td>verifyConfirmation</td> <td>Are you sure?</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> <p><strong>assertPrompt</strong>( <em>messagePattern</em> )</p> <blockquote> <p>Verifies that a javascript prompt dialog with the specified message was generated. Like alerts, prompts must be verified in the same order that they were generated.</p> <p>Successful handling of the prompt requires prior execution of the <strong>answerOnNextPrompt</strong> command (see above). If a prompt is generated but you do not verify it, the next Selenium action will fail.</p> <p><strong>examples:</strong></p> <blockquote> <table border="1" class="table"> <colgroup> <col width="35%" /> <col width="56%" /> <col width="10%" /> </colgroup> <tbody valign="top"> <tr><td>answerOnNextPrompt</td> <td>Joe</td> <td> </td> </tr> <tr><td>click</td> <td>id=delegate</td> <td> </td> </tr> <tr><td>verifyPrompt</td> <td>Delegate to who?</td> <td> </td> </tr> </tbody> </table> </blockquote> </blockquote> </blockquote> </div> <div class="section" id="parameter-construction-and-variables"> <h1><a name="parameter-construction-and-variables">Parameter construction and Variables</a></h1> <blockquote> <p>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.</p> <p><strong>Stored Variables</strong></p> <p>The commands <em>store</em>, <em>storeValue</em> and <em>storeText</em> 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.</p> <p><strong>Variable substitution</strong></p> <p>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.</p> <p>Example:</p> <blockquote> <table border="1" class="table"> <colgroup> <col width="18%" /> <col width="36%" /> <col width="45%" /> </colgroup> <tbody valign="top"> <tr><td>store</td> <td>Mr</td> <td>title</td> </tr> <tr><td>storeValue</td> <td>nameField</td> <td>surname</td> </tr> <tr><td>store</td> <td>${title} ${surname}</td> <td>fullname</td> </tr> <tr><td>type</td> <td>textElement</td> <td>Full name is: ${fullname}</td> </tr> </tbody> </table> </blockquote> <p><strong>Javascript evaluation</strong></p> <p>Javascript evaluation provides the full power of javascript in constructing a command parameter. To use this mechanism, the <em>entire</em> 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 <em>storedVars</em> map detailed above. Note that variable substitution cannot be combined with javascript evaluation.</p> <p>Example:</p> <blockquote> <table border="1" class="table"> <colgroup> <col width="9%" /> <col width="44%" /> <col width="46%" /> </colgroup> <tbody valign="top"> <tr><td>store</td> <td>javascript{'merchant' + (new Date()).getTime()}</td> <td>merchantId</td> </tr> <tr><td>type</td> <td>textElement</td> <td>javascript{storedVars['merchantId'].toUpperCase()}</td> </tr> </tbody> </table> </blockquote> </blockquote> </div> <div class="section" id="extending-selenium"> <h1><a name="extending-selenium">Extending Selenium</a></h1> <blockquote> <p>It can be quite simple to extend Selenium, adding your own actions, checks 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, checks and locators.</p> <p>The following examples try to give an indication of how Selenium can be extended with javascript.</p> </blockquote> <p><strong>Actions</strong></p> <blockquote> <p>All <em>doFoo</em> methods on the Selenium prototype are added as actions. For each action <em>foo</em> there is also an action <em>fooAndWait</em> registered. An action method can take up to 2 parameters, which will be passed the second and third column values in the test.</p> <p>Example: Add a "typeRepeated" action to Selenium, which types the text twice into a text box.</p> <pre class="literal-block"> 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); }; </pre> </blockquote> <p><strong>Checks</strong></p> <blockquote> <p>All <em>assertFoo</em> methods on the Selenium prototype are added as checks. For each check <em>foo</em> there is an <em>assertFoo</em> and <em>verifyFoo</em> registered. An assert method can take up to 2 parameters, which will be passed the second and third column values in the test.</p> <p>Example: Add a <em>valueRepeated</em> check, that makes sure that the element value consists of the supplied text repeated. The 2 commands that would be available in tests would be <em>assertValueRepeated</em> and <em>verifyValueRepeated</em>.</p> <pre class="literal-block"> 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 this.assertMatches(expectedValue, actualValue); }; </pre> </blockquote> <p><strong>Locator Strategies</strong></p> <blockquote> <p>All <em>locateElementByFoo</em> 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.</p> <p>Example: Add a "valuerepeated=" locator, that finds the first element a value attribute equal to the the supplied value repeated.</p> <pre class="literal-block"> // 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; }; </pre> </blockquote> <p><strong>user-extensions.js</strong></p> <blockquote> <p>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.</p> <p>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.</p> </blockquote> <hr /> <p>:</p> </div> </div> </body> </html>