gyrmination

Note: A bevy of additional information on UI-Element may be found by browsing the Selenium category of this blog.

Overview

UI-Element is an extension to Selenium IDE that aims to fill several functional gaps in both the IDE itself and integration with a driven testing environment, namely with Selenium Remote Control. If you’re not already familiar with the Selenium suite of open-source web application testing tools, please refer to the OpenQA Selenium page to learn more.

Note: This blog entry has been edited for consistency with the latest UI-Element release.

The goals of the extension are summarized as follows:

Insulate testcases from change in underlying application

With traditional Selenium IDE recorded tests, small modifications to the presentational layer of a web application can break the ability of the test to locate elements on a page. Tests should be more resilient to change, such that testcase breakage can be minimized with careful test construction, and can be fixed at a central point as opposed to in all affected testcases. This calls for some mechanism of abstracting the locator.

Provide a richer language for encoding locator logic

Ideally, the expressiveness of locator logic should mirror that of the web application logic that drives the presentational layer. This isn’t really possible with simple XPath or DOM expressions. Conditional and indexed logic should be supported in the calculation of the locator.

Increase testcase readability

XPath and DOM expressions don’t give the tester a good sense of what page elements are being interacted with. Page elements should be uniquely identified by descriptive names that don’t necessarily look like code. Any relevant information about the element previous testers have recorded should also be easily accessible and easy to understand.

Enable a smooth transition from the record-playback to the scripting paradigm

Not all users come to web testing with expert skills in scripting web tests in perl, ruby, or proprietary languages. However, as users’ understanding of scripting grows, they should be able to smoothly transition from using record-playback through the IDE to creating scripts run through the Remote Control without losing the above advantages and without duplicating effort. The testing tools should promote the development of a users’ abilities.

Diving In: A Taste of UI-Element

Here is a short test fragment created using Selenium IDE, sans UI-Element extension. Notice in particular how the locators in the second column are content dependent. In other words, the require the link text to be a certain value. If the text ever changes, or if these move to a slightly different spot in the web application (as front page articles are likely to do as new articles are posted), the test will break.

open	/
clickAndWait	//a[contains(text(),’Educate Your Stakeholders!’)]
clickAndWait	//a[contains(text(),’Shane Diffily’)]
clickAndWait	//a[contains(text(),’Content’)]

If we were to read the above test aloud in English, it might sound like: “Click link on the page that says Educate Your Stakeholders. Then click the link on the page that says Shane Diffily. Finally, click the link on the page that says Content.”

Here is the same test fragment created using Selenium IDE leveraging UI-Element. There’s some magic happening behind the scenes which you’ll see in just a moment. For now, notice what information is being conveyed by the locator. The Paamayim Nekudotayim, or double-colon, is obviously being used to delimit two pieces of data. This is the ui locator in action.

open	/
clickAndWait	ui=issuePages::article(index=2)
clickAndWait	ui=articlePages::author()
clickAndWait	ui=allPages::topics(topic=Content)

The English reading for this test may be a little less intuitive, so I’ll tell you what it is: “We should be on some issue page. Click the second article element on the page. Now we should be on an article page. Click the author element on the page. We should be on a page that contains some generic elements. Finally, click the topic element on the page for the Content topic.”

Notice how different the two English readings sound. The first reading focuses on the textual content of the page, while the second focuses on its structure. With the former, we know we’re clicking something … but we’re given no clues about the contextual significance of what we’re clicking. The latter tells us what it is, semantically, that we’re clicking.

What’s Behind the Curtain: The Map File

It would be a feat of Artificial Intelligence for the IDE to just “know what we mean” when we provide a descriptive locator. We’re not that lucky, but fortunately the map file that makes it all possible isn’t rocket science. It is a file included into the Selenium IDE as a companion extension to UI-Element that defines the names (and other attributes) of page elements, and specifies the mapping from name to location on the page. It is written in Javascript, which provides a convenient and concise way to express all the required information. Here is an example:

myMap.addPageset({
    name: 'issuePages'
    , description: 'pages including magazine issues'
    , pathRegexp: '(issues/.+)?'
});
myMap.addElement('issuePages', {
    name: 'article'
    , description: 'front or issue page link to article'
    , args: [
        {
            name: 'index'
            , description: 'the index of the article'
            , defaultValues: range(1, 5)
        }
    ]
    , getLocator: function(args) {
        return "//div[@class='item']"
            + "[" + args.index + "]/h4/a";
    }
});

If you’re not pretty familiar with Javascript or other scripting, the syntax alone will look pretty hairy to you. Don’t worry about this yet … we’ll save matching square and curly brackets, regular expressions, and comma hunting for later. Let me tell you in plain English what this definition is saying:

• I’m defining a group of pages, called a “pageset”. The name of the pageset is issuePages.
• Pages are included in the pageset depending on their URL’s. I’m doing this using the regular expression (issues/.+)? , which must match part of the URL.
• I’m defining a UI element, and I’m calling it the article element.
• Here’s a nice description for what this element means: it’s a link to an article on the front page, or on an issue page.
• You know, there might be several article elements on any given page. So I’m defining an argument which I’m calling the index of the article. I’m guessing there will typically be at most 4 such elements on a page.
• I can tell you exactly how to find the element on the page, so long all of the required information is available (in particular the index of the article being located). I do this by feeding you an XPath expression which will unequivocally specify the element.
• To explain the xpath locator: the element will be an Anchor element, which is the child of an H4 header element, which is the child of the N’th DIV element of class item. N was the value given as the index of the article element in question.

Here’s a simpler one:

myMap.addPageset({
    name: 'articlePages'
    , description: 'pages for actual articles'
    , pathRegexp: 'articles/.+'
});
myMap.addElement('articlePages', {
    name: 'author'
    , description: 'article author link'
    , locator: "//div[@id='content']/h3[@class='byline']/a";
});

In plain English:

• I’m defining a pageset called articlePages. I’m using another regular expression as the rule for pages that are included within this pageset.
• I’m defining the author UI element.
• This element is a link to the author of an article.
• There should be only one such element per page, and I know exactly how to find it with an xpath. I don’t need to define any arguments whatsoever.

Those more versed in Javascript can take advantage of the full expressive power of the language. Here we define a list of acceptable values for an argument.

var topLevelTopics = [
    'Code',
    'Content',
    'Culture',
    'Design',
    'Process',
    'User Science'
];

myMap.addPageset({
    name: 'allPages'
    , description: 'all alistapart.com pages'
    , pathRegexp: '.*'
});
myMap.addElement('allPages', {
    name: 'topics'
    , description: 'sidebar links to topic categories'
    , args: [
        {
            name: 'topic'
            , description: 'the name of the topic'
            , defaultValues: topLevelTopics
        }
    ]
    , getLocator: function(args) {
        return "//div[@id='topiclist']/ul/li" +
            "/a[text()=" + args.topic.quoteForXPath() + "]";
    }
    , testcase1: {
        args: { topic: 'foo' }
        , xhtml: '<div id="topiclist"><ul><li>'
            + '<a expected-result="1">foo</a>'
            + '</li></ul></div>'
    }
});

Again in plain English:

• I’m defining the allPages pageset for all pages, including the home page.
• I’m defining the topics element.
• This element is a link appearing on the sidebar of a page. It links to a topic category page.
• A fixed set of topics elements can appear on any page. These include Code, Content, and others. Although the list doesn’t change very often, and perhaps not at all, I’d like to be able to add and remove topics in the case that the list does change. I can do this by adding or removing from the topLevelTopics list.
• I can locate any topics element on a page using an xpath locator. To construct the xpath, I’ll have to take into consideration just what topic is being considered. Other than that, the xpath is pretty straightforward.

Jumpstart: See UI-Element In Action

Enough talk - let’s get up and running! Download Selenium IDE with the UI-Element extension. (Note that you can build a more recent version out of the Selenium IDE subversion trunk.) Currently it is based on Selenium IDE version 0.8.7 . After you’ve downloaded the XPI file, open it in Firefox to initiate the install. If you already had another version of Selenium IDE installed, it might be a good idea to uninstall that first.

You’ll have to edit your configuration before you see anything special. Start the IDE extension, and go to Options > Options. You’ll see a field called “Selenium Core extensions (user-extensions.js)”. Copy the following text into the field, and click OK:

chrome://selenium-ide/content/ui-element.js, chrome://selenium-ide/content/ui-map-sample.js

You just enabled the UI-Element extension, along with a sample map file. (Note that the order of specifying extensions matters; the map file must appear after ui-element.js.) The map file ui-map-sample.js is a reference map for the website alistapart.com, which I chose as my testbed when writing UI-Element. I’ve defined a number of page elements which you can try out to get a sense of what the extension is doing. Go ahead and browse to http://alistapart.com, then restart Selenium IDE.

Now, just start interacting with the website. Click here, click there. Observe what command locators, or “Targets”, are being created in the IDE window. You should see at least some occurrences of the ui locator.

After you’ve clicked around a bit, try running the test. The IDE should be able to trace your path through the application using any ui locators created. If you experience difficulties, try creating a new test, and making sure you give each page enough time to load before clicking on. Premature clicks can be the cause of commands not being captured correctly.

Let’s explore a couple of interesting UI-Element features. Click one of the ui locator commands in the IDE command tree. Now hover the mouse over the “Target” text field. You should see a tooltip which contains a description of the page element. If there were any arguments defined for it in the map file, they should be described too, complete with default argument values. Notice that with this knowledge, it is very easy to edit the element locator. For example, say you start with this locator:

ui=allPages::section(section=contact)

Suppose instead of clicking this element, I want to click the element for a different section. Hovering the mouse over the text field, I see that articles, topics, about, contact, and contribute are among the sections defined for this element. I need only edit the locator to update it:

ui=allPages::section(section=about)

This is one of the primary benefits of the ui locator: it is not only easy to read, it is easy to edit too. Herein lies a good argument for maintaining accurate metadata in the map file documenting the elements you’ve defined - you’ll reap the rewards when editing tests in the IDE.

Down the Rabbit Hole: The Map File

As you’ve seen, the map file is what makes the ui locator work. This section delves into the syntax of the map file in more detail. One of the great things about UI-Element, ironically, is that not every tester needs to know how to write the map file. As long as one tester has the ability (or guts) to deal with the Javascript and seed the map file, which is really a repository of knowledge, all others will benefit. With time, any tester can learn to contribute to the repository.

(I know I learn best by example. If you’d like to take a look at the map file for alistapart.com and you’ve got UI-Element installed in Firefox, simply paste the following chrome URL into the address bar of the browser:)

chrome://selenium-ide/content/ui-map-sample.js

First things first: you need a good text editor to view and edit your map file. I highly recommend jEdit. Of the editors I’ve tried, its Javascript syntax highlighting is the most complete. It will ease any struggle you have closing parentheses, curly and square brackets, and keeping track of quotes and commas:

A dissertation on the mapping file syntax once lived here, but no longer. The reason: documentation that supersedes it is now included in the UI-Element distribution, under the Help menu. Here’s a snapshot of that documentation:

ui-doc.html

A few words on XPath.

There’s an art to constructing XPaths. For any given page element, a whole slew of XPath expressions can uniquely identify it. Remember this though - you are designing your expression to withstand unrelated changes to the application, if at all possible. It is brittle to construct XPaths that start at the root of the document tree and drill down, for example /html/body/div[4]/p/a . Rely instead on the semantic relationships of your pages - ids, names, and classes are your friends. For instance:

//div[@id='easy_to_find']/a

this div element can be anywhere on the page - it doesn’t matter where - and I’ll still be able to locate the link which has a semantic relationship with it. Base your XPaths on those semantic associations which will not change, in the face of presentational associations which almost surely will.

By the way, the Selenium IDE is a great place to test your XPaths. Navigate to the desired page, type your XPath expression into the IDE as the Target, and click the Find button. If the XPath is true, the correct page element should blink with a bright border.

On occasion, you may be frustrated with syntax errors in your map file that you can’t find. If this happens, there is a simple remedy - include the map file into a simple HTML file, which you can open in Firefox. Any Javascript errors should leap out at you in the Firefox Error Console. Here’s the HTML you can use:

<html>
<head></head>
<body>
<script type="text/javascript" src="path/to/my/map.js">
</script>
</body>
</html>

Driven: Graduating the IDE

You love using the IDE to record tests, but you need the power of variables, control structures (loops, functions), database queries, and automated scheduling of regression tests. Selenium Remote Control (RC) to the rescue! Now that you’ve created testcases with the ui locator, we need to be able to drive these testcases in the language of our choice.

The examples I use here are in Perl. To set up the driven test environment, download the latest release of the RC from the openqa.org website. (You may have to update your Java version to 1.5 or greater, or install a parallel version. If you experience problems with this release, try downloading a nightly snapshot build from the OpenQA site; the files will be named something like selenium-server-x.x.x-yyyymmdd.hhmmss-x-standalone.jar.) Now we need to install the Perl driver from CPAN:

% perl -MCPAN -e shell
...
cpan> install Test::WWW::Selenium
...

Now open the test you want to drive in the IDE. Export the test into Perl: File > Export Test As > Perl - Selenium RC. The exported file will look something like:

use strict;
use warnings;
use Time::HiRes qw(sleep);
use Test::WWW::Selenium;
use Test::More "no_plan";
use Test::Exception;

my $sel = Test::WWW::Selenium->new(
    host => "localhost",
    port => 4444,
    browser => "*firefox",
    browser_url => "http://localhost:4444"
);

$sel->open_ok("/issues/237");
$sel->click_ok("ui=issuePages::article(index=2)");
$sel->wait_for_page_to_load_ok("30000");
$sel->click_ok("ui=articlePages::author()");
$sel->wait_for_page_to_load_ok("30000");
$sel->click_ok("ui=allPages::topics(topic=Content)");
$sel->wait_for_page_to_load_ok("30000");

If you’re running this particular example, you’ll have to edit the text highlighted in red to be the following:

http://alistapart.com

Save the test as ui-test.pl.

Let’s take this test on a test drive! Notice the presence of the ui locators in the code. We need to make the RC aware of both UI-Element and our map file, otherwise the locator will not be recognized and will fail to find the proper page elements. The Selenium Server component of the RC supports loading of Javascript extensions; however it currently requires all extensions to be packaged in a single file called user-extensions.js. (I’ve created a JIRA ticket for this.) We need to work around this restriction because we need to load two extensions files.

To get the first extension file, you can type the chrome URL:

chrome://selenium-ide/content/ui-element.js

into the Firefox address bar, then copy and paste the contents into a file called ui-element.js. Alternatively, you can unjar the UI-Element XPI file and drill down into the content folder to find it.

If you’ve got Unix tools at your disposal, simply concatenate the two files in this order:

% cat ui-element.js ui-map-sample.js > user-extensions.js

If not, simply concatenate the two files in a text editor, and save the resulting file as user-extensions.js. Now lets start up the Selenium Server.

% cd selenium-remote-control-0.9.0
% cd server
% java -jar selenium-server.jar -userExtensions user-extensions.js

Now run the test:

% perl ui-test.pl
ok 1 - open, /issues/237
ok 2 - click, ui=issuePages::article(index=2)
ok 3 - wait_for_page_to_load, 30000
ok 4 - click, ui=articlePages::author()
ok 5 - wait_for_page_to_load, 30000
ok 6 - click, ui=allPages::topics(topic=Content)
ok 7 - wait_for_page_to_load, 30000
1..7

A browser window should open and iterate through the test steps. The console window should indicate the success or failure of steps as they execute. Congratulations - you just ran your first Selenium driven test with UI-Element!

Conclusion

UI-Element gives the tester the option to trade off some simplicity for the sake of more power. It aims to improve the readability, maintainability, and expressiveness of testcases while still allowing the user the implement testcases, in full or in part, using Selenium IDE. It offers one valuable deliverable - the map file - which serves as living documentation for the user interface of the system under test. And it paves the road for transitioning from IDE-only testing to RC testing, with all the benefits inherent to real-world programming languages and automated regression.

Looking to the future, I hope to get feedback from the Selenium community on the usefulness of UI-Element, as well as improvement and bugfix requests. Eventually, I hope UI-Element will be good enough to merge into the Selenium project. If you have a comment, please leave a reply to this blog post, or to my UI-Element announcement post in the OpenQA forums.

This entry was posted on Saturday, May 12th, 2007 at 12:20 and is filed under Code, Selenium. You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.