FireWatir: How to?

FireWatir is a web application testing tool written using Ruby language. It is used for testing web application functionality on Firefox browser. It is written keeping 'WATiR' in mind so that scripts written for testing the application on IE using WATiR can be used with minimal/no changes, to test the application on Firefox.

How its different from WATiR?
The main difference between WATiR and FireWatir lies in the mechanism, which drives the browser, to test a web application.
WATiR uses the COM object of IE browser exposed by windows. It interacts with the COM objects for doing any action on HTML elements, of a page, that is displayed using IE(i.e. HTML elements that are supported by WATiR). Interacting with the browser in this way restricts the usage of WATiR on Windows only.

For Firefox there is no COM object that is exposed. So, tried using XPCOM to interact with the browser. But it didn't work out as you need to compile XPCOM with Firefox browser. So it was not feasible for every user of FireWatir to first compile the source and then use the tool. So, we explored more and found an extension called JSSh. JSSh is a TCP/IP JavaScript Shell Server for Mozilla that allows other programs like Telnet to make connections to the running Mozilla process. This was what we needed to drive the Firefox browser. The ruby calls are converted to corresponding JavaScript code and send to JSSh via a socket. JSSh executes that JavaScript code on the browser and returns the result.

So, finally the test scripts when executed on IE or FireFox will be executed in same manner; the working is transparent to users. Though, FireWatir is implemented using socket for interaction with the browser, there is not much of a difference in execution speed of FireWatir as comparted to WATiR.

How to install FireWatir?
You can get the latest gem and JSSh extension for Windows from http://code.google.com/p/firwatir. FireWatir is still not tested on Mac or Linux, but it should work on any platform as we are not using any Windows specific component.

Install the JSSh extension by opening the extension file in the browser. The extension will not show up in the extension list. So to check if the extension is installed properly, restart the Firefox from command prompt with '-jssh' as command line argument. For e.g.: In windows restart it using 'c:\Program Files\Mozilla Firefox\Firefox.exe -jssh' assuming that you have installed Firefox in 'c:\Program Files\Mozilla Firefox' directory. After the browser is started telnet to port 9997. the response should be:

Welcome to the Mozilla JavaScript Shell!

JSSh command shell will open with '>' as shell prompt character. If this shows up then JSSh extension is installed properly.

Install the FireWatir gem using command 'gem install [firewatir gem name]'. This will install FireWatir 1.0 on your machine. Now go to the FireWatir installation directory in the gems. For e.g. go to 'c:\ruby\lib\ruby\gems\1.8\gems' assuming that you are on windows platform and have installed 'ruby' version 1.8 in 'c:\ruby\' directory. Check for 'firewatir-1.0-mswin32 folder (assuming you have installed gem for windows). Existence of that folder indicates correct installation. Now go to 'unittests' directory and run file 'mozilla_all_tests.rb' (make sure you have started Firefox as said above with -jssh option before running the test cases). This file will run all the unittests without any failure or errors. In case you get any errors or failures refer to section 'TroubleShooting'. In case the error is not resolved add it to the issue tracking system at 'http://code.google.com/p/firewatir.

How to use?
Go to the 'unittests' directory in the gems folder. Refer to the unittest cases on how to access the element? How to use them? What properties they expose? etc etc..

Which Firefox versions are supported?
FireWatir is tested on Firefox version 1.5, 1.5.0.7 and 2.0. It should work with all Firefox version 1.5 and above. It may or may not work with versions less that 1.5

TroubleShooting
1. Currently you need to start Firefox manually from command prompt using '-jssh' as command line argument before running any FireWatir script or unit tests.
2. Check if JSSh is installed correctly by connecting to port 9997 using Telnet (telnet localhost 9997 if you are telnet-ing from the same machine on which your Firefox instance is running, or telnet testhost 9997 where testhost is the hostname of the remote machine on which FireFox is running).
3. In case 'attach_new_browser' test fails. Make sure you run this test alone using 'ruby attach_new_browser'. Make sure that Firefox doesn't block the pop up. Also make sure that you have settings to open the link in new window instead of new tab.
4. In case you face any other problems or you have some comments/suggestions/queries mail at 'angrez@gmail.com' or at 'amit.garde@gmail.com'