Parameter construction and Variables

Parameter construction and Variables

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.

Stored Variables

The commands store, storeValue and storeText can be used to store a variable value for later access. Internally, these variables are stored in a map called "storedVars", with values keyed by the variable name. These commands are documented in the command reference.

Variable substitution

Variable substitution provides a simple way to include a previously stored variable in a command parameter. This is a simple mechanism, by which the variable to substitute is indicated by ${variableName}. Multiple variables can be substituted, and intermixed with static text.

Example:

store	Mr	title
storeValue	nameField	surname
store	${title} ${surname}	fullname
type	textElement	Full name is: ${fullname}

Javascript evaluation

Javascript evaluation provides the full power of javascript in constructing a command parameter. To use this mechanism, the entire parameter value must be prefixed by 'javascript{' with a trailing '}'. The text inside the braces is evaluated as a javascript expression, and can access previously stored variables using the storedVars map detailed above. Note that variable substitution cannot be combined with javascript evaluation.

Example:

store	javascript{'merchant' + (new Date()).getTime()}	merchantId
type	textElement	javascript{storedVars['merchantId'].toUpperCase()}

Whitespace Rules

HTML automatically normalizes whitespace within elements, ignoring leading/trailing spaces and converting extra spaces, tabs and newlines into a single space. When Selenium reads text out of the page, it attempts to duplicate this behavior, so you can ignore all the tabs and newlines in your HTML and do assertions based on how the text looks in the browser when rendered. We do this by replacing all non-visible whitespace (including the non-breaking space "&nbsp;") with a single space. All visible newlines (<br>, <p>, and <pre>formatted newlines) should be preserved.

We use the same normalization logic on the text of HTML Selenese test case tables. This has a number of advantages. First, you don't need to look at the HTML source of the page to figure out what your assertions should be; "&nbsp;" symbols are invisible to the end user, and so you shouldn't have to worry about them when writing Selenese tests. (You don't need to put "&nbsp;" markers in your test case to assertText on a field that contains "&nbsp;".) You may also put extra newlines and spaces in your Selenese <td> tags; since we use the same normalization logic on the test case as we do on the text, we can ensure that assertions and the extracted text will match exactly.

This creates a bit of a problem on those rare occasions when you really want/need to insert extra whitespace in your test case. For example, you may need to type text in a field like this: "foo   ". But if you simply write <td>foo   </td> in your Selenese test case, we'll replace your extra spaces with just one space.

This problem has a simple workaround. We've defined a variable in Selenese, ${space}, whose value is a single space. You can use ${space} to insert a space that won't be automatically trimmed, like this: <td>foo${space}${space}${space}</td>. We've also included a variable ${nbsp}, that you can use to insert a non-breaking space.

Note that XPaths do not normalize whitespace the way we do. If you need to write an XPath like //div[text()="hello world"] but the HTML of the link is really "hello&nbsp;world", you'll need to insert a real "&nbsp;" into your Selenese test case to get it to match, like this: //div[text()="hello${nbsp}world"].

Extending Selenium

It can be quite simple to extend Selenium, adding your own actions, assertions and locator-strategies. This is done with javascript by adding methods to the Selenium object prototype, and the PageBot object prototype. On startup, Selenium will automatically look through methods on these prototypes, using name patterns to recognise which ones are actions, assertions and locators.

The following examples try to give an indication of how Selenium can be extended with javascript.

Actions

All doFoo methods on the Selenium prototype are added as actions. For each action foo there is also an action fooAndWait registered. An action method can take up to 2 parameters, which will be passed the second and third column values in the test.

Example: Add a "typeRepeated" action to Selenium, which types the text twice into a text box.

        Selenium.prototype.doTypeRepeated = function(locator, text) {
            // All locator-strategies are automatically handled by "findElement"
            var element = this.page().findElement(locator);
        
            // Create the text to type
            var valueToType = text + text;
        
            // Replace the element text with the new text
            this.page().replaceText(element, valueToType);
        };
        

Accessors/Assertions

All getFoo and isFoo methods on the Selenium prototype are added as accessors (storeFoo). For each accessor there is an assertFoo, verifyFoo and waitForFoo registered. An assert method can take up to 2 parameters, which will be passed the second and third column values in the test. You can also define your own assertions literally as simple "assert" methods, which will also auto-generate "verify" and "waitFor" commands.

Example: Add a valueRepeated assertion, that makes sure that the element value consists of the supplied text repeated. The 2 commands that would be available in tests would be assertValueRepeated andverifyValueRepeated.

        Selenium.prototype.assertValueRepeated = function(locator, text) {
            // All locator-strategies are automatically handled by "findElement"
            var element = this.page().findElement(locator);
        
            // Create the text to verify
            var expectedValue = text + text;
        
            // Get the actual element value
            var actualValue = element.value;
        
            // Make sure the actual value matches the expected
            Assert.matches(expectedValue, actualValue);
        };
        

Automatic availability of storeFoo, assertFoo, assertNotFoo, waitForFoo and waitForNotFoo for every getFoo

All getFoo and isFoo methods on the Selenium prototype automatically result in the availability of storeFoo, assertFoo, assertNotFoo, verifyFoo, verifyNotFoo, waitForFoo, and waitForNotFoo commands.

Example, if you add a getTextLength() method, the following commands will automatically be available: storeTextLength, assertTextLength, assertNotTextLength, verifyTextLength, verifyNotTextLength, waitForTextLength, and waitForNotTextLength commands.

        Selenium.prototype.getTextLength = function(locator, text) {
            return this.getText(locator).length;
        };
        

Also note that the assertValueRepeated method described above could have been implemented using isValueRepeated, with the added benefit of also automatically getting assertNotValueRepeated, storeValueRepeated, waitForValueRepeated and waitForNotValueRepeated.

Locator Strategies

All locateElementByFoo methods on the PageBot prototype are added as locator-strategies. A locator strategy takes 2 parameters, the first being the locator string (minus the prefix), and the second being the document in which to search.

Example: Add a "valuerepeated=" locator, that finds the first element a value attribute equal to the the supplied value repeated.

        // The "inDocument" is a the document you are searching.
        PageBot.prototype.locateElementByValueRepeated = function(text, inDocument) {
            // Create the text to search for
            var expectedValue = text + text;
        
            // Loop through all elements, looking for ones that have 
            // a value === our expected value
            var allElements = inDocument.getElementsByTagName("*");
            for (var i = 0; i < allElements.length; i++) {
                var testElement = allElements[i];
                if (testElement.value && testElement.value === expectedValue) {
                    return testElement;
                }
            }
            return null;
        };
        

user-extensions.js

By default, Selenium looks for a file called "user-extensions.js", and loads the javascript code found in that file. This file provides a convenient location for adding features to Selenium, without needing to modify the core Selenium sources.

In the standard distibution, this file does not exist. Users can create this file and place their extension code in this common location, removing the need to modify the Selenium sources, and hopefully assisting with the upgrade process.