<?xml version="1.0" encoding="UTF-8"?>
<!--
/*
* Modified by TIBCO Software Inc., © 2007
* TIBCO General Interface Test Automation Kit (GITAK) 0.8
*/
-->
<!DOCTYPE xslt [
<!--Used to control code intenting -->
<!ENTITY nbsp " ">
]>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:strip-space elements="*"/><xsl:output method="html"/>
<!-- TOP LEVEL -->
<xsl:template match="/">
<xsl:call-template name="header" />
<xsl:apply-templates select="//top" />
<h2>Selenium Actions</h2>
<dl>
<xsl:apply-templates select="//function[not(return) and not(starts-with(@name, 'assert'))]" mode="action"/>
</dl>
<h2>Selenium Accessors</h2>
<dl>
<xsl:apply-templates select="//function[starts-with(@name, 'assert')]" mode="action"/>
<xsl:apply-templates select="//function[return]" mode="accessor"/>
</dl>
<xsl:call-template name="footer" />
</xsl:template>
<xsl:template name="header">
<h1>Selenium Reference</h1>
<h2>Concepts</h2>
<p>A <strong>command</strong> is what tells Selenium what to do. Selenium commands come in three 'flavors': <strong>Actions</strong>, <strong>Accessors</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>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.</p>
<p><strong>Accessors</strong> examine the state of the application and store the results in variables, e.g. "storeTitle". They are also used to automatically generate Assertions.</p>
<p><strong>Assertions</strong> 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".</p>
<p>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.</p>
<p>"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 <strong>setTimeout</strong> action below).
</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>
</xsl:template>
<xsl:template name="footer">
<h2><a name="parameter-construction-and-variables">Parameter construction and Variables</a></h2>
<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><a name="storedVars"></a><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 class="section" id="extending-selenium">
<h2><a name="extending-selenium">Extending Selenium</a></h2>
<blockquote>
<p>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.</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>Accessors/Assertions</strong></p>
<blockquote>
<p>All <em>getFoo</em> and <em>isFoo</em> methods on the Selenium prototype are added as accessors (storeFoo). For each accessor there
is an <em>assertFoo</em>, <em>verifyFoo</em> and <em>waitForFoo</em> 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.</p>
<p>Example: Add a <em>valueRepeated</em> 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
<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
Assert.matches(expectedValue, actualValue);
};
</pre>
</blockquote>
<p><strong>Automatic availability of storeFoo, assertFoo, assertNotFoo, waitForFoo and waitForNotFoo for every getFoo</strong></p>
<blockquote>
<p>All <em>getFoo</em> and <em>isFoo</em> methods on the Selenium prototype automatically result in the availability
of storeFoo, assertFoo, assertNotFoo, verifyFoo, verifyNotFoo, waitForFoo, and waitForNotFoo commands.</p>
<p>Example, if you add a getTextLength() method, the following commands will automatically be available:
storeTextLength, assertTextLength, assertNotTextLength, verifyTextLength, verifyNotTextLength, waitForTextLength, and waitForNotTextLength commands.</p>
<pre class="literal-block">
Selenium.prototype.getTextLength = function(locator, text) {
return this.getText(locator).length;
};
</pre>
<p>Also note that the <em>assertValueRepeated</em> method described above could have been implemented using
isValueRepeated, with the added benefit of also automatically getting assertNotValueRepeated, storeValueRepeated,
waitForValueRepeated and waitForNotValueRepeated.</p>
</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>
</div>
</xsl:template>
<!-- Ignore the top comment in iedoc.xml; just process all of its children -->
<xsl:template match="top">
<xsl:apply-templates />
</xsl:template>
<!-- Print out store* and all of its related assertions -->
<xsl:template match="function" mode="accessor">
<dt><strong>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">store</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-accessor"/>
variableName
)
</strong></dt>
<dd>
<xsl:apply-templates select="comment" />
<p>Arguments:</p>
<ul>
<xsl:apply-templates select="param" mode="comment" />
<li>variableName -
the name of a <a href="#storedVars">variable</a> in which the result is to be stored.
</li>
</ul>
<p>Related Assertions, automatically generated:</p>
<ul>
<li>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">assert</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-assertion"/>
<xsl:if test="./return/@type != 'boolean'">
<a href="#patterns">pattern</a>
</xsl:if>
)
</li>
<li>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">assertNot</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-assertion"/>
<xsl:if test="./return/@type != 'boolean'">
<a href="#patterns">pattern</a>
</xsl:if>
)
</li>
<li>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">verify</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-assertion"/>
<xsl:if test="./return/@type != 'boolean'">
<a href="#patterns">pattern</a>
</xsl:if>
)
</li>
<li>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">verifyNot</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-assertion"/>
<xsl:if test="./return/@type != 'boolean'">
<a href="#patterns">pattern</a>
</xsl:if>
)
</li>
<li>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">waitFor</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-assertion"/>
<xsl:if test="./return/@type != 'boolean'">
<a href="#patterns">pattern</a>
</xsl:if>
)
</li>
<li>
<xsl:call-template name="accessor-rename">
<xsl:with-param name="accessor"><xsl:value-of select="@name" /></xsl:with-param>
<xsl:with-param name="prefix">waitForNot</xsl:with-param>
</xsl:call-template>
(
<xsl:apply-templates select="param" mode="declaration-assertion"/>
<xsl:if test="./return/@type != 'boolean'">
<a href="#patterns">pattern</a>
</xsl:if>
)
</li>
</ul>
</dd>
<br/>
</xsl:template>
<xsl:template match="function" mode="action">
<dt><strong>
<xsl:value-of select="@name" />
(
<xsl:apply-templates select="param" mode="declaration-action"/>
)
</strong></dt>
<dd>
<xsl:apply-templates select="comment" />
<xsl:if test="count(./param) > 0">
<p>Arguments:</p>
<ul>
<xsl:apply-templates select="param" mode="comment" />
</ul>
</xsl:if>
</dd>
<br/>
</xsl:template>
<!-- In action mode, don't print out a comma after the last argument -->
<xsl:template match="param" mode="declaration-action">
<xsl:value-of select="@name" />
<xsl:if test="position() != last()">
<xsl:text>,</xsl:text>
</xsl:if>
</xsl:template>
<!-- In accessor mode, always print out a comma, because we'll always append a final argument variableName -->
<xsl:template match="param" mode="declaration-accessor">
<xsl:value-of select="@name" />,
</xsl:template>
<!-- In assertion mode, append a final pattern argument, unless the assertion is boolean, in which case no final argument -->
<xsl:template match="param" mode="declaration-assertion">
<xsl:value-of select="@name" />
<xsl:if test="position() != last() or ../return/@type != 'boolean'">
<xsl:text>, </xsl:text>
</xsl:if>
</xsl:template>
<xsl:template match="param" mode="comment">
<li>
<xsl:value-of select="@name" />
<xsl:text> - </xsl:text>
<xsl:apply-templates/>
</li>
</xsl:template>
<!-- When we encounter anything else, just copy it right on over! -->
<xsl:template match="node()|@*" >
<xsl:copy>
<xsl:apply-templates select="node()|@*" />
</xsl:copy>
</xsl:template>
<!-- Take an accessor named getFoo or isFoo and replace it with a new prefix, e.g. storeFoo -->
<xsl:template name="accessor-rename">
<xsl:param name="accessor"/>
<xsl:param name="prefix"/>
<xsl:variable name="spaced"> <xsl:value-of select="$accessor" /></xsl:variable>
<xsl:choose>
<!-- If the accessor ends with "Present" and the prefix ends with "Not", then a simple replacement
would get something ungrammatical, like assertNotTextPresent. Instead, negate the prefix (assertNot becomes assert)
and negate the accessor (TextPresent becomes TextNotPresent), so the command generated is
assertTextNotPresent, which is much prettier -->
<xsl:when test="contains(concat($prefix,' '),'Not ') and contains(concat($accessor,' '),'Present ')">
<!-- negate the prefix -->
<xsl:variable name="negatedPrefix">
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"><xsl:value-of select='$prefix' /> </xsl:with-param>
<xsl:with-param name="search-string">Not </xsl:with-param>
<xsl:with-param name="replace-string"></xsl:with-param>
</xsl:call-template>
</xsl:variable>
<!-- negate the accessor -->
<xsl:variable name="negatedAccessor">
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"><xsl:value-of select='$accessor' /> </xsl:with-param>
<xsl:with-param name="search-string">Present </xsl:with-param>
<xsl:with-param name="replace-string">NotPresent</xsl:with-param>
</xsl:call-template>
</xsl:variable>
<!-- replace "get" with the negated prefix -->
<xsl:variable name="getReplaced">
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"> <xsl:value-of select='$negatedAccessor' /></xsl:with-param>
<xsl:with-param name="search-string"> get</xsl:with-param>
<xsl:with-param name="replace-string"><xsl:value-of select='$negatedPrefix' /></xsl:with-param>
</xsl:call-template>
</xsl:variable>
<!-- replace "is" with the negated prefix -->
<xsl:variable name="isReplaced">
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"><xsl:value-of select='$getReplaced' /></xsl:with-param>
<xsl:with-param name="search-string"> is</xsl:with-param>
<xsl:with-param name="replace-string"><xsl:value-of select='$negatedPrefix' /></xsl:with-param>
</xsl:call-template>
</xsl:variable>
<!-- and print out the output -->
<xsl:value-of select="$isReplaced"/>
</xsl:when>
<xsl:otherwise>
<!-- replace "get" with the prefix -->
<xsl:variable name="getReplaced">
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"> <xsl:value-of select='$accessor' /></xsl:with-param>
<xsl:with-param name="search-string"> get</xsl:with-param>
<xsl:with-param name="replace-string"><xsl:value-of select='$prefix' /></xsl:with-param>
</xsl:call-template>
</xsl:variable>
<!-- replace "is" with the prefix -->
<xsl:variable name="isReplaced">
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"><xsl:value-of select='$getReplaced' /></xsl:with-param>
<xsl:with-param name="search-string"> is</xsl:with-param>
<xsl:with-param name="replace-string"><xsl:value-of select='$prefix' /></xsl:with-param>
</xsl:call-template>
</xsl:variable>
<!-- and print out the output -->
<xsl:value-of select="$isReplaced"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template name="search-and-replace">
<xsl:param name="input"/>
<xsl:param name="search-string"/>
<xsl:param name="replace-string"/>
<xsl:choose>
<!-- See if the input contains the search string -->
<xsl:when test="$search-string and
contains($input,$search-string)">
<!-- If so, then concatenate the substring before the search
string to the replacement string and to the result of
recursively applying this template to the remaining substring.
-->
<xsl:value-of
select="substring-before($input,$search-string)"/>
<xsl:value-of select="$replace-string"/>
<xsl:call-template name="search-and-replace">
<xsl:with-param name="input"
select="substring-after($input,$search-string)"/>
<xsl:with-param name="search-string"
select="$search-string"/>
<xsl:with-param name="replace-string"
select="$replace-string"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<!-- There are no more occurrences of the search string so
just return the current input string -->
<xsl:value-of select="$input"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet> 
RSS Feed