kuh • pain´• kah

Se: Atomic Number 34

Selenium is a tool that makes your life easier if you’re a web developer by allowing you to write automated tests for your website.  Selenium basically remote controls your browser using JavaScript, allowing you to script a set of actions and verify the results.  You can use it for a myriad of tasks like testing flow and error checking.  We need it to test several forms that do intake for our customers.  Currently, we have a QA team that has to fill in each form over and over, changing the input to test validation errors and the like.  This sucks and is prone to error because, unless they’re really organized, they can miss things, not to mention that it takes a ton of mindless time (waste).  My goal is to automate the testing of these forms.

The first thing I’ve noticed is that the Selenium documentation isn’t all that great.  Ian Bicking has written some stuff, and there’s a cursory overview on their documentation pages.  Like most things Open Source, the documentation is much neglected.  Maybe it’s like most things where once you’ve figured it out and set it up, it works and you never have to really bother with it again, and therefore don’t document it.  Then the next guy coming along has to fumble through it, figures it out, and quickly forgets the pain.

Second, the tutorial basically starts with “Once you’ve got Java installed”.  Here is where I stop reading, because Java is my Kryptonite and enemy.  Basically, I don’t do Java.  Sure, the Selenium Server is written in Java, and that’s their choice and I’m happy to RUN things written in Java (I use Eclipse & Poseidon for UML and love them), but I try not to deal with it directly.  If you’re not as Java-averse as I am, check out the tutorial which shows you how to get the Selenium Server running in what amounts to console mode, and mess with it.

Third, the code has been updated and the documentation has not, so the installation instructions are wrong and can cause confusion.  I’ll go over that below.

Finally, again like most Open Source things I encounter, it is assumed you know what you’re doing and there’s not much help for the person just getting started.  More on this later.

Background

First, there are several parts to Selenium.  This post is all about getting things running quickly and showing results, therefore we’re going to take the easy route and use Selenium IDE, which is a plugin for Firefox. (If you’re developing for the web and you’re not using Firefox, staple your lip to your mousepad right now.)  There are a few other pieces to Selenium that I’m going to fuss with later, and I’m really gonna try to figure out Selenium RC, since it allows you to use Python, which I love.  Here’s an overview of the other parts of Selenium:

Selenium Core:

The core stuff that does the work

Selenium IDE:

The plugin for Firefox.  Has hugely useful “recording” mode that watches what you do, records it, and helps you learn. Saves as other formats, FTW!

Selenium RC:

RC stands for Remote Control. It runs from real code in the language of your choice, allowing you to write more complicated tests, in say, Python, rather than the IDE syntax, which is HTML tables.  Yes.  HTML tables.

Other:

There’s also some other parts like Selenium on Rails, and Selenium Grid.  I am not interested in these (yet).

So now that you see what’s available, we’re gonna play with the IDE.

The Selenium IDE

The Selenium IDE is really easy to install. You need to be using Firefox for this URL to work, as it’s a link right to an XPI file: http://release.openqa.org/selenium-ide/1.0-beta-2/selenium-ide-1.0-beta-2.xpi

It should install right into your browser and ask you to restart Firefox.  See you in a second!

A Sample Test

Now that you have the plugin installed, you should see “Selenium IDE” listed under the Tools Menu.  Yeah, go ahead and open it!  A little window will open, and it’s ready to record your actions.  Let’s do a quick test on Google.  Open a new window and go to http://google.com, then type “kapanka.com” into the search box and click the “Google Search” button.  A few commands should have been automatically entered into the Selenium IDE window.  Under the last entry, you’ll see a green line.  This is “where you are” in the recording.  Also, note that Google was entered into the Base URL box at the top.

Now we’re going to test something.  Click in the Selenium IDE window if you’re not there already.  Now click below the green line to enter a new line, then click in the “Command” field.  This is a dropdown list of the commands available and  should autocomplete if you start typing.  Type or choose: “assertTextPresent” in the Command field.  Skip the Target field, and enter “Bukkit” into the value field.  What this will do is test whether the text “Bukkit” is found anywhere on the results page.

Now it’s time to run the test.  Before we run it, there’s a hidden pane that we need to open.  If you do not see a column on the left of the Selenium IDE window with the words “TestCase” at the top, then click the thin vertical dotted line at the left.  This should open a list of available tests.  Select the “untitled” test.  Now, click the icon that has a Green Arrow on it (either one will do, one is Run All Tests, the other, Run This Test, and you only have one test right now).  If you watch carefully, you’ll see each step in the test get highlighted green as it runs.  The last step is green-er because it actually tests something.  Also, you’ll notice that it opened Google.com, typed my domain name in, hit “Google Search” and verified that “Bukkit” was found in the results.  Neat-o, huh?  If you’re having fun reading this so far, I recommend clicking the Obama Haz A Bukkit link and click on the ads there!

Next Steps

OK, so that was a pretty stupid test, but you get the idea.  You can do as much as you’d like in record mode (don’t forget to turn it off when you’re done recording!), then run the entire thing and watch it all happen real quick.  But this alone isn’t very useful.  What we want to do is save these tests so we can run a bunch of them at once.  This is where we get the concept of the Test Suite.  A Test Suite is a group of tests that can be run all at once.

Installing on the Server

Now we want to install Selenium onto your webserver so that we can record a bunch of tests with the IDE, then save them somewhere and run them all at once.  Selenium has to be installed at the same domain name as what’s called the AUT (Application Under Test).  This is because JavaScript’s security mechanism doesn’t allow it to do what’s necessary cross-domain.  This is a good thing.  You can find out more about this by poking around the Selenium site, but it suffices to say that you cannot test Domain B from Domain A.

Click for license

Therefore you’re going to need access to your web server, but if you’re developing without server access, or at least a local development environment running, you can take your mousepad-stapled lip and feed it into your office paper shredder.  You do have access to your server, right?

OK, download Selenium and unpack it on your local machine.  We’re gonna poke at it a bit before putting it onto your web server.  You can find the appropriate download on the Selenium Download Page.  Once you’ve got it downloaded and unpacked look into the resulting folder.  You’ll see the “core” folder, and the “tests” folder.  The tests folder is super-useful because it gives you a great place to look for examples.  In fact, that folder has a set of DogFood tests that test basically every function available to Selenium.  This is the first thing we’re gonna run.  Rename the folder you unpacked from “selenium-core-0.x.y” to just plain “selenium”, and upload this folder to the root of your web server.

All done?  Perfect.  Now navigate to this folder on your server: http://<your-domain-here>/selenium and you should see the Selenium default page.  Click the topmost link: Selenium TestRunner.  This takes you to the TestRunner environment that you will eventually use to run your Test Suites.  On the Test Runner page, click the “GO” button to load the default Test Suite from the Selenium “test” folder.  You should see all of the tests load into the leftmost pane.  Ready?  Click the “Run All Tests” icon (Green arrow, 3 lines) in the rightmost pane and watch it go!  While its running, you’ll see the AUT in the bottom pane.  Pretty cool, huh?

Now you should have: 74 tests run, 1 failed. 583 commands passed, o failed, 1 incomplete.

Writing your own tests

Here’s where we tie the two together.  You should create a directory on your web server called “tests”.  You can just dump all of your tests in there, or make a “stests” or “ftests” (selenium tests or functional tests) subdirectory.  This is where you’ll put your Test Suite and individual tests.

Open your website in Firefox, and also open the Selenium IDE.  First you’ll want to make a new Test Suite by using File -> New Test Suite.  Then File -> Save Test Suite As…  Save the Test Suite as MyTestSuite.html on your local machine.  Next, you’ll want to record a new test for your website.  Do some clicking, add some assertions, and when you’re all done, choose File -> Save Test Case and save it as TestMyFirstTest.html (by convention, test files start with the word Test).  Now, edit MyTestSuite.html in your favorite editor.  The format of this file is an HTML table.  You should see that the first row of the table is the Title of the Test Suite, and the second row is “Untitled”.  Replace the first column value with “TestMyFirstTest.html” and the second column with “My First Test”.  Save this file and upload both of them to your webserver in the /tests/stests directory.  Now you’re ready to run your Test Suite.

Running Your Tests

OK, back to the Selenium of your website in Firefox.  This time when you click into the Selenium TestRunner, you’ll want to type the name of your Test Suite into the box on the uppermost left field.  Type: “/tests/stests/MyTestSuite.html” and click “GO”.  You should see your “My First Test” load up in the leftmost frame.  Run the test!

Wheeee!

If everything went smoothly, your test should have run with all green.  My fingers are killing me from typing and mousing for the past hour straight.  Next post…working on getting Selenium RC to run.  I hope this helped you get started with Selenium, and sorry about the gross picture of the shredded dog tongue.  Blech!

~Spanky