Selenium Reference

A command is what tells Selenium what to do. Selenium commands come in three 'flavors': Actions, Accessors and Assertions. Each command call is one line in the test table of the form:

Actions 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.

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.

Accessors examine the state of the application and store the results in variables, e.g. "storeTitle". They are also used to automatically generate Assertions.

Assertions 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".

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.

"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 setTimeout action below).

Element Locators 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.

Patterns 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.

Element Locators

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

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

Element Filters

String-match Patterns

Selenium Actions

Selenium Accessors

Parameter construction and Variables

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 and verifyValueRepeated.
	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.

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

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