Drinking the Watir

I've been using Watir recently to help automate integration tests for some of our client projects. Moving from a Windows XP to a Windows Vista environment proved more troublesome than I had realised it would be, however I now have my test environment all working and last Friday night realised some value from the automated tests as they (very) quickly ran through a complicated series of steps to prove an important piece of client functionality after a server upgrade, thus allowing me to get home earlier than expected.

For the benefit of my fellow Elcomites I'm going to document the steps required to setup Watir on a brand new Vista machine.

Pre-Requisites

Firstly, as I pointed out previously, you can't have Office Groove 2007 installed. Also, you need to be able to run as Administrator on your local machine.

Install Ruby

You will want Ruby 1.8.5, and fortunately there is a one-click installer for Windows, which you just need to download and run. By default this installs under C:\Ruby\ and includes RubyGems (which makes installing other Ruby stuff dead easy).

Having done this, let's test whether we have a fully working Ruby installation by running irb (the interactive ruby shell). Open a command window and type the following:

C:\Users\angus>irb

In Vista this prompts you with the message "An unidentified program wants to access your computer", identifying the program as ruby.exe with the option to Cancel or Allow. Obviously we want to Allow this (note: you won't get this message if your UAC settings are different to mine). It will then open a new command window with the following text shown:

irb(main):001:0>

Just getting this far tells us that Ruby is installed. Close both the command windows you have open.

Install Watir

Installing Watir is as simple as starting another command window and then typing in the following command:

C:\Users\angus>gem install watir

We then want to do the same for the windows-pr library that provides access to various Win32 APIs and is needed in Vista to run Watir.

C:\Users\angus>gem install windows-pr

We can then open irb again and see if we can test Watir from the command-line!

irb(main):001:0> require 'watir'
=> true

This tells Ruby that we are using the Watir namespace (like Imports in VB.NET or using in C#.NET)

irb(main):002:0> include Watir
=> Object

This actually mixes in the Watir library with our code (essentially making it available to us).

irb(main):003:0> ie = Watir::IE.new
=> #<Watir::IE:0x4a50e70 @url_list=["about:blank"], @ole_object=nil, @rexmlDomobject=nil, @logger=#<Watir::DefaultLogger:0x4a50d94, @progname=nil, @logdev=#<Logger::LogDevice:0x4a50d30, @mutex=#<Logger::LogDevice::LogDeviceMutex:0x4a50d08, @mon_entering_queue=[], @mon_count=0, @mon_owner=nil, @mon_waiting_queue=[]>, @dev=#<IO:0x32d7320>, @shift_size=nil, @shift_age=nil, @filename=nil>, @formatter=nil, @default_formatter=#<Logger::Formatter:0x4a50d58 @datetime_format="%d-%b-%Y %H:%M:%S">, @level=2>, @activeObjectHighLightColor="yellow", @down_load_time=0.413, @speed=:slow, @typingspeed=0.08, @page_container=#<Watir::IE:0x4a50e70 ...>, @ie=#<WIN32OLE:0x4a50e0c>, @error_checkers=[], @defaultSleepTime=0.1>

Whoa! Did you see that Internet Explorer window open up? This is the litmus test for Watir, this line opens a new IE window and assigns a reference to it to the ie variable.

irb(main):004:0> ie.goto('http://ww.google.com.au')
=> 2.206

We can now start playing with the open window, firstly by browsing to the Google (Australia) website ...

irb(main):005:0> ie.text_field(:name, 'q').set('Elcom Technology')
=> true

... entering a search term ...

irb(main):006:0> ie.button(:name, 'btnG').click
=> 1.045

... and then actioning the search. There is a lot more that Watir allows you to do, but this is a good start!

Install Aptana Studio

Editing Ruby scripts in Notepad is a chore, and whilst Visual Studio will eventually support Ruby the current Sapphire in Steel IDE doesn't excite me (the free version is still just an alpha release). Enter Aptana Studio, which has absorbed the old RadRails IDE project and which has a stable, and free, Community edition. Amongst other features this gives us Ruby colour coding and an integrated test runner - great for Watir!

Aptana Studio is built atop the open-source Eclipse IDE for Java. This means that other Eclipse plugins are also available. It also means your machine will end up running Sun's Java. It comes with a Windows installer to make things easy and is a free download.

Once you have run the installer you will want to edit the properties of the studio exe so that it runs as administrator.

You can now run Aptana Studio and choose to install the Ruby on Rails plugin from the start page:

Create your first test script ... here is that sample we ran before, but this time the way you might typically create a test file:

##########################################################

# Integration Test Sample

##########################################################

# This demonstrates the skeleton of an integration test.

##########################################################

 

require 'rubygems'

require 'test/unit'

require 'watir'

require 'watir/testcase'

 

class IntegrationTest < Watir::TestCase

    # Runs before each test case, e.g. used to specify login details.

  def setup

    super

  end

 

  # Runs after each test case, e.g. could be used for logging, etc

  def teardown

    super

  end 

 

  # always the first test as it sets up the browser object

  def test_first

    # Create a new browser instance (running this opens IE)

    @@ie = Watir::IE.new

    @@ie.speed = :fast # comment this line if you want to more easily see what is happening

    @@ie.maximize

  end

 

  # reproduce our irb test

  def test_google_elcom

    @@ie.goto('http://www.google.com.au')

    @@ie.text_field(:name, 'q').set('Elcom Technology')

    @@ie.button(:name, 'btnG').click

  end

 

  # always the last test, closes the browser object 

  def test_end

    @@ie.close

  end

end

 

By right-clicking in that file and choosing Run As > Test::Unit Test (see below) you can run the tests within the Aptana test runner.

That gives you a nice test result tree that shows exactly where things fall over (when they do).

You are done! Now I am pretty sure that people are going to find problems I haven't documented. If you do, then please feel free to add a comment with your difficulty and I'll update this main post with the solution.