Building a Selenium Test Suite

In this section, we will describe the mechanics of deploying Selenium tests, and give an overview of how to build Selenium tests with the Selenium IDE and the XPath Checker extensions to Firefox. We also describe some of the most frequently used Selenium commands. At the end we discuss how to test JavaScript and Ajax sites with Selenium.

Deploying and running tests

Selenium is, at heart, a set of JavaScript code that interprets tests written in straight HTML. To install Selenium, all you need to do is unpack the Selenium Core zip archive and move the selenium/ subdirectory into a location that your web server or web application will serve as static pages. You can get the latest version of Selenium Core at (http://www.openqa.org/selenium-core/) (at the time of this writing, the latest version of Selenium Core is 0.8.2).

The next thing you need to do is write a page for each test suite. Each test suite contains multiple Selenium test pages; to write the test suite, just write an HTML table with a single column, and with each row containing the name of a test page enclosed in an <a href=...> tag. To get started, just grab the source code for the first test suite above, at (http://webtesting.idyll.org/selenium/suite.html).

The suite source is pretty simple:

<table cellpadding="1" cellspacing="1"border="1">
  <tbody>
    <tr><td><b>ExampleServer Test Suite</b></td></tr>
    <tr><td><a href="ExampleServerTests.html">ExampleServerTests</a></td></tr>
  </tbody>
</table>

It’s a table that contains a column full of tests; any link in this column is considered a test page. Each test page consists of a Selenium Core “program,” which is just an HTML table with the first column containing each Selenium command in the program. Arguments to the commands are provided in additional columns, so the command:

command | argument 1 [ | optional argument 2 ]

would be written in HTML like this:

<tr>
 <td>
     command
 </td>
 <td>
     argument 1
 </td>
 <td>
     argument 2
 </td>
</tr>

For an actual Selenium program, you can look at the source HTML for the example server tests at (http://webtesting.idyll.org/selenium/ExampleServerTests.html).

This URL contains the example code you ran above. For example, the first two commands are open | /login and clickAndWait | create, which go to the URL /login and click on the create button. The HTML source for these two commands is:

<tr>
     <td>open</td>
     <td>/login</td>
     <td></td>
</tr>
<tr>
     <td>clickAndWait</td>
     <td>create</td>
     <td></td>
</tr>

So, the test suite consists of links to individual test pages, and each test page contains a program written in HTML, but what actually runs the test suite? The answer is the Selenium Test Runner, a static HTML and JavaScript page that’s in charge of loading the test suite and executing the tests; to load a particular test suite, you pass it into the Test Runner page as part of the URL, selenium/core/TestRunner.html?test=

<path to
        test suite HTML page>

The path to the test suite HTML page can be either absolute or relative; if it’s relative, it will be interpreted as a path relative to the TestRunner.html. In the case of the example server, the absolute path to the test suite is /selenium/suite.html and the relative path from TestRunner.html is ../suite.html, so the full URL for the tests is: (http://webtesting.idyll.org/selenium/core/TestRunner.html?test=../suite.html).

Recording tests with the Selenium IDE

Writing GUI tests for web apps is no fun, no matter what your testing tool is. You need to navigate through pages, fill and submit forms, and verify that certain elements are present on the pages. Doing all this manually can quickly become tedious.

If you’re writing Selenium tests, these activities are made tolerable due to the Selenium IDE. The Selenium IDE is a Firefox extension that you launch via the Tools menu. It records web browsing actions such as opening a URL, clicking on a link, entering text in a field form, selecting a drop-down menu item, submitting a form, etc. This makes building a basic test suite a simple matter of starting up the Selenium IDE and running through the actions you want to test.

For example, to build the example test suite demonstrated above, do the following:

And there you are—a full test of creating an account and logging in! The Selenium IDE window will have the complete test program recorded, and you can either run it (by pushing the green “Play” button) or you can save it (by going to the File menu and saying “Save test”). This will save an HTML test program that can be directly linked to from a test suite.

A guide to Selenium commands

Below we discuss a few of the most commonly used Selenium commands. The full list is available on the (http://www.openqa.org/selenium-core/testrunner.html).

Opening web pages by URL

Web pages can be opened by their URL via the open command:

open | url

Clicking on links

This is one of the trickiest aspects of writing tests in Selenium. In general, HTML elements on the web pages you’re trying to test can be referred to in Selenium commands via “element locators”, which can be one of the following:

• identifiers: the id or name attribute of the element

• DOM traversal syntax: document.forms['myForm'].myDropdown

• XPath syntax: //img[@alt='The image alt text']

Life is easy when HTML elements such as links have id attributes such as id="the_link_id". In this case, the command you need to use for clicking on the link is simply:

click | the_link_id

Life is also pretty easy when links have text that is on the same line with the starting a tag and the closing /a tag. In this case, you can use the following XPath syntax:

click | //a[text() = "the link text"]

A recently introduced Selenium command for accessing links by their text is the link: command:

click | link:the link text

Note that you need to follow link by a colon, then immediately by the text of the link with no quotes.

In other cases, especially when the link text is on a line by itself or spans multiple lines, the text method will not work and you will need to identify the link by some other attributes.

Clicking on submit buttons

The command you need to use for clicking on form submit buttons is click. The target of the command is the element locator for the button. This can be either the button’s name attribute or its value attribute.

click | form.button.Register

Here is an example of clicking a submit button by its value, using an XPath expression:

click | //input[@value='Log in']

Clicking on checkboxes

The click command is also used for clicking on checkboxes. You need to indicate the name of the checkbox field as the target of the command. The click command, when applied to a checkbox, toggles the value of that box.

Note that the click command can also be used for clicking on radio buttons.

Entering text in input fields

If you need to fill in input fields in forms, use the type command, which takes two arguments: the name of the input field (you’ll need to figure what that name is by inspecting the HTML source) and the value you need to type in that field.

Selecting values in drop-down lists

This is accomplished via the select command, which also takes two arguments: the name of the drop-down list field and the value you need to select in that list.

Verifying the state of the application

So far we have shown how Selenium can drive an embedded browser via “Selenese” commands. This is only one aspect of testing a web application, since it indirectly verifies that the HTML elements it expects to click or open are indeed present. For direct verifications, Selenium provides a variety of “verify” commands that check the values of the different elements under test. Perhaps the simplest check is verifyTextPresent, which makes sure that a given snippet of text is present in a web page.

Values for elements of a form (input fields, drop-down lists, checkboxes) can be verified via the verifyValue command:

verifyValue | wysiwyg_editor | Epoz
verifyValue | checkbox | off

(For a checkbox such as “listed,” the value that we compare with is either off or on.)

To verify that a web page contains a specific URL, use either verifyAbsoluteLocation (which checks that the URL of the page equals the given string) or verifyLocation (which checks that the URL of the page ends with the given string).

There are many other types of check commands available on the (http://www.openqa.org/selenium-core/testrunner.html).

Using variables

One very convenient feature of Selenium is the ability to use variables directly in the test tables. In the official documentation, the only way to deal with variables is via separate HTML pages where these variables are set. In the TestNewUser table, I’m using the setVariable command to set three variables: base_url, join_url, and logout_url. The syntax for setting a variable is:

setVariable | <variable name> | <variable value>

If the value is a string, it needs to be enclosed in quotes.

The syntax for getting the value of a variable is ${var_name}.

An important use of a variable, especially when testing web sites that provide log in functionality, is to set a random user ID that will be used in the test. For example,

setVariable | random_user | 'user' + (new Date()).getTime()'

In this case the value for the random_user variable is obtained by concatenating a string (‘user’) with the value returned by a JavaScript function (the getTime() method for a Date

new eb20junior(196636, “small”,0,”"); object). So, you can just use JavaScript code in your variable assignments.

Locating page elements with XPath Checker

Several of the commands in Selenium can take XPath locators as arguments; for example, in click | //a[text() = "the link text"] the argument is an XPath locator specifying the link to click on. Locating specific bits of text on the page manually can be quite annoying. The (http://slesinsky.org/brian/code/xpath_checker.html) is a sanity-saving Firefox extension to help with this chore. After installing it, you can highlight any text on a web page and get an XPath expression that uniquely identifies this text. To do this, right-click on the page and choose “View XPath.” A Firefox window will pop up with an entry field containing an XPath expression, as identified by the tool, and with the text matching that expression. This window allows you to interactively change the XPath expression and see the text that it matches, which is great for learning XPath. (There’s also a good (http://www.zvon.org/xxl/XPathTutorial/General/examples.html) available for people unfamiliar with XPath.)

You can also try out (https://addons.mozilla.org/firefox/1192/),(https://addons.mozilla.org/firefox/addon/1843) another Firefox extension that some people prefer to the XPath Checker extension.

Note that XPath expressions don’t work that well in Internet Explorer. If browser compatibility is high on your list, then you will need to identify HTML elements via their DOM locations. For that, you can use the DOM Locator extension which ships with Firefox, or you can also try to build an equivalent DOM expression based on the XPath expression generated by the XPath Checker.

Selenium and JavaScript

Selenium deals with client-side JavaScript very well: it simply handles it, with no special requirements.

To see how it actually works, go to the front page of the example server. Here we have two common examples of client-side JavaScript: first, an alert box, triggered by clicking on the “JavaScript alert box” link; and second, form entry assertions checked using the onChange element of input boxes. Try clicking the alert link as well as entering some numbers above 200 into the form boxes to see how they work.

The Selenium tests for these features are located in suite2.html; you can run them by going to this page, (http://webtesting.idyll.org/selenium/core/TestRunner.html?test=../suite2.html) in the example server. Try running them all. (They should all work!)

The only thing new about these tests is that they make use of two new Selenium commands, assertAlert and assertValue. These commands test for the contents of the alert box and the form value, respectively. In particular, there is nothing special that needs to be done to test the onChange based JavaScript—simply enter the values, and see what becomes of them.

So, that’s it for testing client-side JavaScript! As we mentioned above, Selenium is particularly nice because you can run your tests in any browser—and thereby test your web site, including your JavaScript code, in any browser you have available.

Asynchronous HTTP requests and Ajax

It is also possible to test web sites that use asynchronous HTTP requests with Selenium. Asynchronous HTTP requests are a common component of Ajax functionality, and they enable a very interactive web experience; because of this, Ajax has become very popular.

The problem with Ajax testing is that the HTML page under test is modified asynchronously, so a plain Selenium assert or verify command might very well fail because the element being tested has not yet been created by the Ajax call. A quick and dirty solution is to put a pause command before the assert. This is error-prone, since the pause might be not sufficient for a slow server, while being unnecessarily slow on a faster one.

A better solution is to use Dan Fabulich’s (http://wiki.openqa.org/display/SEL/waitForCondition) extension, which allows you to wait until a specified JavaScript expression evaluates “True.” Selenium will not advance until the condition becomes true, and the test will fail if the condition is not met within a specified timeout.

Here is an example of a Selenium test table row that uses waitForCondition:

waitForCondition | var value = selenium.getText("//textarea[@name='comment']"); \
value == "" | 10000

This command waits for 10 seconds (the second argument to waitForCondition) until the JavaScript command passed in as the first argument succeeds. Here, the command we passed in checks for the presence of an (empty) textarea named comment, which is added to the page dynamically through an Ajax call.

Note that to locate the element, we used the special variable selenium, which makes the Selenium API directly available to JavaScript. All of the methods available in the file selenium-api.js (which comes with Selenium Core) are available via this variable. In this case, we used getText, which takes a locator as its argument and returns the contents of the located element.

Extensions like waitForCondition allow you to add new commands to Selenium Core, and there are a number of (http://wiki.openqa.org/pages/viewpage.action?pageId=282) available on the Selenium web site. Installing extensions is very easy, just add them to the core/scripts/user-extensions.js file, which is automatically loaded by Selenium.