Section 21.4. Selenium | Rapid Web Applications with TurboGears: Using Python to Create Ajax-Powered Sites

21.4. Selenium

Mechanize is great but sometimes you need to be able to see the test with your own eyes to make sure everything is correct and placed in the right place. Selenium is a great tool that helps you run tests inside the browser. You install Selenium into your web server. We recommend /static/selenium in your TurboGears project. Make sure that the following section is in your config/app.cfg. It should be included by default:

[/static] static_filter.on = True static_filter.dir = "%(top_level_dir)s/static"

Selenium works by injecting JavaScript code into your application that executes in the browser on the client side. The benefit is that Selenium's code can interact very intimately with the HTML DOM of your application. You write Selenium tests in regular HTML files that contain HTML tables with some commands in a special language called Selenese. Don't worry, you can learn it in 40 seconds. These tables are loaded and the commands are executed by Selenium's TestRunner in your browser. Here is a simple test for the bookmarker application:

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>New Test</title> </head> <body> <table cellpadding="1" cellspacing="1" border="1"> <thead> <tr><td rowspan="1" colspan="3">New Test</td></tr> </thead><tbody> <tr>      <td>open</td>      <td>../../</td>      <td></td> </tr> <tr>      <td>clickAndWait</td>      <td>link=All Bookmarks</td>      <td></td> </tr> <tr>      <td>verifyTextPresent</td>      <td>-- Main TurboGears website </td>      <td></td> </tr> </tbody></table> </body> </html>

Let's clean it up a little and concentrate on the actual content:

... <td>open</td> <td>../../</td> <td>clickAndWait</td> <td>link= All Bookmarks</td> <td>verifyTextPresent</td> <td>--Main TurboGears website </td> ...

Each row in the table contains a command with arguments. The first row opens the ../../ url, which happens to be the root of bookmarker, because the test is located in /static/selenium/SeleniumTestList.html. The second row clicks the All bookmarks link and waits for it to show up. The third row verifies that the text "-- Main TurboGears website" appears on the new page. This is a complete test that starts from the browser, moves through the network into CherryPy via the bookmarker controller code, accesses the database, and sends the information all the way back to the browser.

Selenium supports practically all browsers in common use. We tested it on modern versions of Firefox, Safari, and Opera on OSX, Firefox on Ubuntu, and even IE 6 on Windows XP. It worked perfectly on all of them.

Let's see another example. Suppose you want to add a new link. You will have to fill up a form and submit it:

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>New Test</title> </head> <body> <table cellpadding="1" cellspacing="1" border="1"> <thead> <tr><td rowspan="1" colspan="3">New Test</td></tr> </thead><tbody> <tr>        <td>open</td>        <td>../../</td>        <td></td> </tr> <tr>        <td>clickAndWait</td>        <td>link= Add New Link</td>        <td></td> </tr> <tr>        <td>type</td>        <td>bookmarkName</td>        <td>abcd</td> </tr> <tr>        <td>type</td>        <td>link</td>        <td>http://222.com</td> </tr> <tr>        <td>type</td>        <td>description</td>        <td>great site.really</td> </tr> <tr>        <td>clickAndWait</td>        <td>//input[@value=' Save Bookmark']</td>        <td></td> </tr> <tr>        <td>verifyTextPresent</td>        <td>abcd -- great site.really </td>        <td></td> </tr> </tbody></table> </body> </html>

Note that the submit button is specified using an XPath expression this time. This is important if you have elements without ID or name that you want to locate. The 'type' command, which you haven't seen before, is used for populating form fields.

Now that you have written a couple of tests, it is time to run them. The best way to run them is to write a test suite. A test suite is another simple HTML file:

<html> <head>     <title>Test Suite</title> </head> <body>     <table   cellpadding="1"            cellspacing="1"            border="1"            >         <tbody>                <tr><td><b>Test Suite</b></td></tr>                <tr><td><a href="./SeleniumTestList.html">TestList</a></td></tr>                <tr><td><a href="./SeleniumTestAddLink.html">TestAddLink</a></td></tr>         </tbody>     </table> </body> </html>

You can put your tests and TestSuite.html file anywhere in the /static directory.

Once you've put your tests in the static directory, you can browse to http://localhost:8080/static/selenium/TestRunner.html. You will see a nice web-based Selenium GUI that allows you to select a test suite file. Use a relative path from /static/selenium to locate your TestSuite.html file. The TestRunner will display your tests. You can select one of them, and you will see the commands in the middle pane. You can run a selected test or all the tests, walk through the tests, or even debug them (including breakpoints). It is really a very rich test environment considering that everything happens inside the browser. When you run your tests, the TestRunner will color successful commands in green and failed ones in red (and stop).

There is, of course, a lot more to Selenium. Once you understand the basics and how Selenium works, it is easy to expand your knowledge and explore further.

Now, we have something to confess. We didn't write these Selenium tests.

We used a wonderful Firefox extension called Selenium-IDE. This extension allows you to capture tests in a GUI fashion just by navigating through your site, clicking links, and filling out forms. You can even run your tests there. The tests that are captured are cross-platform, and you can run them on other browsers. The only limitation, and it's awfully small, is if you do any browser sniffing and generate different markup for different browsers, tests generated on one browser may break when run in a different browser.

The Selenium IDE is a great time-saver and makes the entire experience of writing web GUI tests fun, or at least tolerable.

Finally, there is another project called Selenium4Gears, which requires you to write some glue code in your application but provides automated tests based on your controller methods.