My environment for Selenium 2.0 (WebDriver)

One thing I believe to be very important for any sort of software development (and test automation with Selenium is software development) is having a good environment. So here is how I set up my environment to start with Selenium 2.0 and Java.

What you need:

1. Java (go to  http://www.oracle.com/technetwork/java/index.html)
1. I typically go with Java SE 1.6.0. If you don't need the latest, go with something more mature.
2. Download the full SDK and docs.
3. Install them in C:\jdk1.6.0_30 (assuming you downloaded build 30)
4. I like to put it in the root of the C drive with no spaces in case other things don't like spaces.
5. Unpack the docs into the same directory so they are easy to find. 
2. Eclipse (go to  http://www.eclipse.org/downloads/)
1. I typically go with Eclipse IDE for Java Developers because it has everything for Selenium and it is small.
3. SVN (go to  http://subversion.apache.org/)
1. You need some sort of source control.
2. I usually go with Git but more people are still using Subversion.
3. There are more tutorials on SVN and better support.
4. Selenium (go to  http://code.google.com/p/selenium/downloads/list)
1. You'll need to download:
1. selenium-java-2.19.0.zip (or whatever the latest version is)
2. selenium-server-standalone-2.19.0.jar (or whatever the latest version is)
2. Unpack the zip file to some location
1. I'll typically unzip them into the workspace for the project
2. I'll also put the jar file in the same location
3. This way I can add the jar files to subversion
5. Eclipse support for SVN (go to  http://subclipse.tigris.org/ )
1. Normally I would suggest using Marketplace from the Help menu but not for the latest SVN client.
2. I like subclipse for an SVN client.
3. Once on the subclipse site go to download and install.
4. Copy the link for Eclipse Update Site URL for 1.8.x
5. Go to Eclipse Help->Install New Software...
6. Click Add...
1. Name: subclipse 1.8.x
2. Location: the update site URL you copied above.
7. Select all
8. Unselect Mylyn 3.x if you don't want it.
9. Follow the install wizard
6. Adding the JDK to Eclipse
1. Go to Window->Preferences in Eclipse
2. Expand Java
3. Select Installed JREs
4. Click Add...
5. Select Standard VM
6. Set JRE home to C:\jdk1.6.0_30\jre
7. Set JRE name to JDK 1.6.0
8. Everything else can be left as default.
7. Creating a project
1. Select File->New->Java Project
1. Project name: something relating to the application you are testing
2. I usually go with the defaults.
3. Maybe change the JRE.
4. Click Next >
5. On the Libraries tab
6. Add JARs... (add External JARs... if you didn't put them in the project workspace)
7. Go to the location you unzip the Selenium files.
8. Select the selenium-java-2.19.0.jar and selenium-java-2.19.0-src.jar files and add them.
9. Add JARs... (add External JARs... if you didn't put them in the project workspace)
10. Go to the location you unzip the Selenium files.
11. Go to the libs folder and add all the jar files in there.
12. Add JARs... (add External JARs... if you didn't put them in the project workspace)
13. Go to the location you downloaded the selenium-server-standalone-2.19.0.jar file
14. Add this file to the libraries.
2. Finish the rest of the project creation using defaults.
3. You can now start adding JUnit Test Cases to the project
1. I select JUnit 4
2. I select a package which follows Java conventions
3. For example, com.mycompany.selenium.application where application is the application we are testing.
4. Add a setUp() and tearDown()
5. Finish
4. Have a look at  http://seleniumhq.org/docs/03_webdriver.html for what to put in the setUp(), tearDown() and test cases.

The most important thing about using Selenium with Java is that you really need to know Java, Source Control (Subversion), an IDE (Eclipse) and a test framework (JUnit) before you even start using Selenium. So search the web for basic Java tutorials, play with Eclipse, check out http://www.junit.org/ and search for tutorials on JUnit 4 then look at the docs on Selenium HQ.

If you need help with Selenium and WebDriver, post a message to http://groups.google.com/group/webdriver. I usually respond to people there on a regular basis.

Using source control within Eclipse

In my last blog entry I talked about setting up a Subversion (SVN) repository, getting the subclipse plugin for Eclipse and adding a project to source control.

So why do we need source control? There are many reasons to use source control. Here are some of them:

1. It creates a backup of your work
2. It allows you to undo changes you made to the project
3. It lets you work as a team with others on the same project
4. You can create branches of the project for different reasons

The first point is pretty obvious. If something happened to your working copy of the project you still have a backup of the project in source control. If the repository is on a remote machine it is even better. If the repository is on the same machine but a different hard drive, that is a little better. Obviously not a huge advantage of having the repository on the same hard drive as the working copy.

The ability to undo changes is huge. Let's say you have a project using Selenium and it looks fantastic. You have 80% of the application automated. Then you add one more feature. You run the automation and there are failures all over. You check one of them and find there is nothing wrong with the application under test. It was a change you made to the automation. You have been working on the new automation for 3 hours.

Let's say you didn't have source control. You realize you probably should have tested some of the changes rather than working solid for 3 hours. It is too late to fix that now. You try to remember what you changed in the last few hours. Was it something you changed at the beginning? Was it something you just changed? You have no idea. You step through the automation and try to figure out what is wrong. It has been a long day and you are tired. You try changing a few things, you believe, back to the way they were. After another hour of changing things and just making it worse you decide to go to sleep and look at it tomorrow.

The next day you have a look at the code and immediately realize you messed up one of the locators. You thought the automation was failing at step 37 but there was actually a failure in the setup. You fix the locator and check the setup. It is working fine now. What about the hour of changes you made yesterday? After around 3 hours of work you think you got it back to were it was yesterday.

One minor mistake, 1 hour franticly trying to fix it, 3 hours undoing the frantic work you did yesterday. Total time wasted 4 hours. Maybe things aren't this bad in a situation you might encounter but I can guarantee you will waste an hour or more with situations like this.

Now let's look at the same situation with source control. You realize you should have tested your automation a few times in the last few hours. No problem. You have a few options at this point. You can compare your working copy with the last thing you checked in. In Eclipse,

1. Right click on the project
2. Go down to Compare With and select Latest from Repository

It will give you a window with a tree view in the top. The tree will contain a list of all the files which have changed. If you select one of the files, by double clicking it, it will open a compare view. On the left will be your working copy with the changes and on the right will be the last thing you checked into the repository. Using this tool you can review all your changes and see if one of them caused the failure. Hopefully you spot the change in the setup. Worst case, set a breakpoint at all the places you made a change, run the automation in debug mode and confirm everything is good at each change. You should definitely see that the setup is broken.

Typically, you don't want to check in broken code but if you are on a private branch (more about this later) or working alone it is okay. You could check in the code, compare the last checked in with the previous version. You'll see the same comparison tree but this time you can undo all the changes and bring them back one at a time. The whole procedure would be:

1. Check in broken code
2. Check out the previous, working version
3. Compare this with the checked in, broken version
4. Re-introduce one change at a time
5. Run the automation and confirm the change didn't break anything
6. Keep repeating steps 4 and 5 until you find the change that break the automation

The third advantage of source control is working as a team. If the repository is in a location two or more people can access it, each person can check out a working copy and make changes. This is one of the biggest advantages of source control. Without source control, if two people wanted to make a change on one file they'd have to one at a time. Imagine we have version 1 of a file. I get a working copy, you get a working copy. I make a change to line 17. You make a change to line 43. Without source control, I save the file back to the shared folder. You save the file back to the shared folder. My change to line 17 is lost. Not good.

With source control, it is smart enough to merge my changes and your changes. If for some reason it could not figure out how to merge the changes, the last person to attempt checking in would be told there was a conflict. To fix a conflict in SVN, you update your working copy to the latest from the repository. It will keep your change and grab a copy of the conflicting change. You then compare the changes, fix them by hand and check the file back in. At this point there should be no conflict.

The last advantage I mentioned was creating branches. A branch is a way of creating copies of the entire project. An example of a branch would be version v1.0 and trunk. When I start my project, everything is put in trunk (some source control software calls this head or main). At first things aren't very stable. I would never give a copy of trunk to a customer. At some point I get trunk stable and running well. If I add a new feature, trunk will become unstable again. What I can do is make a branch. Now the repository has trunk and v1.0. Any changes I make on v1.0 will not affect trunk and vice versa. Now I can add the new feature to trunk and destabilize it. At the same time, I can do safe, simple bug fixes on v1.0. I then ship the build from v1.0 to the customer (automation for v1.0 is also updated to match the product I shipped to the customer and nothing more). 

A few months later the customer calls up and says he found a bug. Development has made a LOT of changes to trunk by now. Test automation has been updated to match the changes in trunk. If you tried to run the test automation on v1.0 it would fail to run properly. We don't want to give a copy of trunk to the customer. Partly because it is not stable but also because it has new features the customer hasn't paid for.

So a developer will check out a copy of v1.0, fix the bug and build it as version v1.0.1. While the developer is working on the bug fix, the test automator will check out a copy of the automation from branch v1.0, update the automation to catch the bug, test it to make sure it does find the bug in v1.0 of the product. The tester will now run their automation against version v1.0.1 and confirm the fix. At this point the source control administrator will tag the code (development and automation) for v1.0.1.

Hold on, we missed something. The bug still exists in trunk. Whenever you work on a branch, you have to be sure to merge bug fixes from the branch down into trunk. The change to test automation has to be merged down into trunk as well. Sometimes it is a simple procedure but in some cases, the code in trunk has changed so much they (a) the bug no longer exists or (b) the fix is totally different. In case (b) the developer will have to devise a new fix and the test automator needs to change the test to find the bug in trunk.

There are just some of the things to know about using source control. I'll just leave you with a few recommendations:

1. Test your code often. Don't wait 3 hours.
2. Only check in code that works.
3. After you test code and confirm it works, check it in.
4. Put good comments so you know what you checked in and why.

Good luck and happy coding.

Setting up source control at home

If you are learning how to do development (or test automation) you need source control. I first spoke about this in So you want to create automated tests. Automated testing is software development and part of good software development is source control.

There are a number of open source projects you can use. Originally I would have been suggesting Concurrent Versions System (CVS). When you install something like Eclipse you will see it has the CVS plugin already installed. CVS is well over 20 years old and quite stable. However, Subversion (SVN) is another choice and one I'm going to talk about today.

SVN has been around for over 10 years. As of 3 days ago Subversion become Apache Subversion. The old official site was here. Now the official site is here. If you go to the old site you will find it directs you to the new site.

First thing we need to do is go to the new official site and download a copy of the binaries. SVN is supported on a wide variety of platforms including Linux, Mac OS X and Windows. You will need to download a server/client package. The SVN server will be installed on the machine hosting your files and the SVN client will be installed on the machine you want to do your development on (probably the same computer but you could work with a friend and have them host the server or put the server on a school computer).

Once you have downloaded and installed SVN you should be able to go to a command prompt and enter:

svn help

On a Mac OS X computer, go to Spotlight (upper right corner) and enter Terminal then select Terminal the application to get a command prompt. On a Windows computer, go to the Start->Run menu and enter cmd to get a command prompt.

Now on to creating your SVN repository. But first, a little bit about source control or Software Configuration Management (SCM). Files will exist in at least two locations. There is a repository and there is a working copy. The idea is that you create the files and copy the files to the repository (check in). You can then delete the files you created (working copy) because you have them backed up in the repository. You can make multiple copies of the files (check out) or you and a friend can each have your own copy of the files. First thing we need is a place to store the files or the repository.

We have to make a few decisions before we set up the repository. At some point you will probably have multiple projects. Do you want one repository for each project? Or do you want all the projects in one repository?

At first it will not matter but as you start using advance features it might. For example, at companies they might have a policy that no code change can be checked in to SVN unless you add a comment with the defect tracking system number. Thus to add a new feature to the project a developer must create an entry in the defect tracking system, create the feature and refer to the defect tracking number when they check in the work. SVN has triggers which allow us to remind the developer to do this. How they work is, when a developer tries to check in the code, SVN will scan the comments for a defect tracking number. If there is no number it will reject the check in and ask the developer to include the number in the comments. Do you want this for all the projects you set up? Or only some? If you have one repository, rules like this apply to all projects. If you have multiple repositories then each can have its own set of rules.

For now, lets assume you are just working on one project but leave room for more projects in the same repository. If you change your mind, you can create another repository later.

Select a computer to host the repository (localhost probably) and a location on the file system (on Mac OS X, Linux, UNIX you can use maybe /var/svn/repos; on Windows you can use C:\var\svn\repos). I'll refer to this location at the SVN repository root.

When selecting a computer to host the files on you have to consider things like who will be accessing it and how. If you were setting up a repository for a company and had to deal with firewalls, proxies, user security, etc. it would be an entire chapter in a book. However, this is just a personal repository for you to start learning at home.

Now that we know where the files are going to live we need to decide if we want to store the files in the file system or a Berkeley database. Using a Berkeley DB is more reliable for day to day operations but more work to setup and administer. There have been some bugs relating to using the file system but for our purposes I think it will be fine. Additionally, using the file system is the default since SVN 1.2. So the file system it is.

So, assuming the repository is going into /svn/repositories, lets create a repository for Selenium testing and we'll call it the SELTEST project. From the command prompt:

svnadmin create /var/svn/repos/SELTEST

And that is it. If you look in the directory /var/svn/repos/SELTEST you should find something like:

-rw-r--r--   1 darrell  darrell  229 20 Feb 10:06 README.txt
drwxr-xr-x   5 darrell  darrell  170 20 Feb 10:06 conf
drwxr-xr-x   2 darrell  darrell   68 20 Feb 10:06 dav
drwxr-sr-x  10 darrell  darrell  340 20 Feb 10:06 db
-r--r--r--   1 darrell  darrell    2 20 Feb 10:06 format
drwxr-xr-x  11 darrell  darrell  374 20 Feb 10:06 hooks
drwxr-xr-x   4 darrell  darrell  136 20 Feb 10:06 locks

but you want to access these files using the svn command. On UNIX/Linux/Mac OS X you can use the file system directory permissions to control access. Create groups and use the chmod, chgrp commands.

At this point you are ready to start using SVN. If at a later date you decide you want things setup differently, no problem. There are instructions on migrating, updating, backing up, renaming, etc. your SVN repositories. For now, let's start checking in some code.

Let's assume we are using Eclipse and want to access our SVN repository. Eclipse comes with a plugin for CVS but you'll have to add one for SVN. I recommend using subclipse. There are other SVN client plugins for Eclipse but I have been extremely happy with subclipse. Assuming you already have Eclipse installed and running:

• Go to the subclipse web site
• Go to the download and install section
• Find the update link for your version of Eclipse
• Copy the link and go to Eclipse
• Select the Install Software... menu option (usually in the Help menu)
• When this dialog open you can add the subclipse link
• There should be 3 parts to subclipse
• Select all of them and click Next
• Follow the wizard and accept the license agreement
• You may get a warning about unsigned content
• I accept the installation anyway
• Once it is done you'll have to restart Eclipse
• Now you can switch to the SVN perspective
• Go to the Window menu and open a perspective
• You'll have to select Other... and find the SVN Repository Exploring perspective
• In this perspective there will be a SVN Repositories tab (upper left corner)
• Right click in there and select New->Repository Location...

Now assuming the files are on the local file system, the SVN URL will start with file: but if you are accessing the files from a remote computer you'll need to use ssh. We assume that ssh is set up on the remote computer and you have a login. For a remote computer you want svn+ssh: protocol.

Let's assume the files are located cs.toronto.edu, the repository root is at /u/dgrainge/svn/repos/SELTEST and I can log in with dgrainge. The URL is going to be:

svn+ssh://cs.toronto.edu/u/dgrainge/svn/repos/SELTEST

When I enter this into Eclipse it will ask me for my username and password. These are the username and password I use when I ssh to cs.toronto.edu.

If I am going to be hosting the repository locally in /var/svn/repos/SELTEST then I would use:

file:///var/svn/repos/SELTEST

Because it is local there is no need for a username or password.

Once the repository has been added to Eclipse I can switch back to the Java perspective. Assuming I already have a Java project I want to add to SVN:

• Right click on the Project Name in Package Explorer
• Go down to Team and select Share Project
• Select SVN for the type of repository to use then click Next
• Select the existing repository we just created and click Next
• Click Next to accept the default URL
• Click Finish to start copying the project to the repository
• It will ask you for an 'author' name
• This just identified that you want to check the project into SVN
• Now we have to pick which files to commit (copy)

We do not want to add things like .project, .classpath or .setting. In the Synchronize view:

• Right click on .project and select Add to svn:ignore
• Right click on .classpath and select Add to svn:ignore
• Right click on the root of the project and select Commit
• A list of files to copy to SVN will be listed
• If any of the files are generated (.class files) you don't want to add them
• Any log files or output from running the project should not be added
• Uncheck everything you don't want to add to the repository
• Put the comment in "Initial check in"
• Click OK

If you check in too much you can always remove it later. If you fail to check something in then delete the local copy, it is gone forever.

Next blog entry will be about using the repository and all the benefits it gives you.