How to start writing web test scripts with Ruby and Watir

This blog entry is about how to start writing web test scripts with Ruby and Watir.  Watir is basically a library that lets you interface Ruby to Microsoft Internet Explorer (IE).  I originally presented this as a lightning talk at the Austin Alt.Net conference and one of my colleagues, Jason Darling http://blogs.dovetailsoftware.com/blogs/jason_darling/default.aspx, suggested that I blog it.  I am assuming you know something about Ruby and Watir or you would not be reading this.  If you don’t, I have included some links at the bottom of the post to get you started.  This is going to be rather lengthy so please bear with me.

We will start with a fairly simple user story in the paragraph below.

A user can add an item to the shopping cart.  The user can then proceed to checkout, add shipping information, billing information, and complete the transaction with a valid credit card.  When the transaction is complete, the user will be presented with the item(s) ordered, the total price of the order, the shipping information entered, and the billing information entered.

I tell the people I train to just write out the test steps like they would normally do.  For example, they may do something like this:

    Add an item to the shopping cart

Now comes the first rule:

1. All the words have to be lower case.

 Our first line becomes:

     add an item to the shopping cart

That brings us to rule number two:

2.  Put underlines between words instead of spaces.

  Our first line becomes:

     add_an_item_to_the_shopping_cart

I also like to name the method in the form of “verb” “object”, add_item, verify_information, etc.  We will now use these rules on the rest of the test steps:

The user can then proceed to checkout — so we add:
   “click_go_to_checkout_button”

add shipping information, —
  “enter_shipping_information”

billing information, —
  “enter_billing_information”

complete the transaction with a valid credit card —
  “enter_valid_credit_card_information”
  “click_checkout_button”

the user will be presented with the item(s) ordered —
  “verify_item_ordered”

the total price of the order —
  “verify_total_amount”

shipping information entered —
  “verify_shipping_information”

billing information entered —
  “verify_billing_information”

Putting it all together,our test scenario looks like what follows.  I made some assumptions based on my hypothetical model – like buttons that had to be clicked.
     add_an_item_to_the_shopping_cart
     click_go_to_checkout_button
     enter_shipping_information
     enter_billing_information
     enter_valid_credit_card_information
     click_checkout_button
     verify_item_ordered
     verify_total_amount
     verify_shipping_information
     verify_billing_information
OK, that’s it.  That’s the test scenario.  Anyone who is familiar with what the company does, should be able to read this and have a basic understanding of what is going on.  This scenario should be saved in a file with a .rb extension, which we will come back to later.  Give the file a descriptive name like book_purchase_with_credit_card.rb At this point we have outlined “what” needs to happen and now we need to define the “how”.

I recommend doing the following in a separate file.  Open the new file to do the following steps.  We will turn each of the “whats” into “hows” by turning each of the “whats” into a method.  A method implements the things that need to happen for that step.  We define the method by adding a “def” in front of the line and ending it with an “end” statement so it looks like:

     def add_an_item_to_the_shopping_cart

     end

Let’s say we want to order the book “Everyday Scripting with Ruby” by Brian Marick, which by the way is an excellent book for beginners.  In our application you select the book by selecting the title from a dropdown list.  To do that you need to do the following:

     ie.select_list(:id, “selectbook”).select’Everyday Scripting with Ruby’

“Wooowwwhhh,” you say, “How did you know that?”  “I’m glad you asked.”  There is a lot to get through in this single statement.  First, remember I said that Watir works with IE.  That is why the first thing is “ie”.  It does not have to be that way but trust me it is less confusing for now.  The “select_list” is the way in Watir you specify that you want to access a dropdown select list.  Yes, but there are several select_lists on the screen, how do you specify which one you want to access?  The “(:id, “selectbook”)” is the way you identify the select_list on the page that you want to act on.  To finish this off, “.select” is a method on select_list that allows you pick which item in the list you want to select.  ‘Everyday Scripting with Ruby’ is the exact text of the item in the list that you want to select.

Watir referrs to text boxes where you type in text, like where you would enter your name, as a “text_field,” a check box as a “check_box,” a radio button as a “radio,” a regular button as a “button,” a drop-down select list as a “select_list,” etc.  You are going to have to look through the Watir documentation for the Watir “names” for different controls.  A confusing thing about some of these is that they are often just referred to as “input” in the html.  The easiest thing to do is use your eyes to figure out which “input” they are.

The next part is a little harder.  It is how to uniquely identify the control on the page.  Watir supports a number of different ways to identify the controls and again I refer you to the Watir documentation.  You can use “id”, “name”, “class”, “url”, and a number of others depending on the type of the control and what is actually defined for the control.  For example, a text_field that is used to input a name may have an “id” of “name,” text_field(:id, “name”).   Sometimes you have several choices as to what to use.  If a control has a unique “id”, then I suggest using that.  To find out what is defined for a particular control, it is best to use something like the Microsoft IE Developer Toolbar. 

At the time of writing, you can get it at:

http://www.microsoft.com/downloads/details.aspx?familyid=e59c3964-672d-4511-bb3e-2d5e1db91038&displaylang=en

The IE toolbar will allow you to see controls and what attributes they have.  If you are lucky, you will have  unique ids for each of the controls you have to deal with.  If you don’t, ask your developers to add them for the ones you need.  If that does not work, there are different ways to identify them but that is a separate blog or look in more detail at the Watir documentation.

Back to the task at hand.  Our first method looks like this:

     def add_an_item_to_the_shopping_cart
       ie.select_list(:id, “selectbook”).select’Everyday Scripting with Ruby’
     end

That should be all we need for this method.

Let’s do the next method, click_go_to_checkout_button.

     def click_go_to_checkout_button
       ie.button(:id, “goto_checkout_button”).click
     end

The “ie.button(:id, “goto_checkout_button”)” identifies the button on the page and the “.click” is the method to click a button.

The next method is – enter_shipping_information.  I am going to use simplified information for shipping; a single name field, a single address field, a city field, a state field, and a zip code field.

     def enter_shipping_information
       ie.text_field(:id, “shipping_name).set’Joe Tester’
       ie.text_field(:id, “shipping_address”).set’123 Address’
       ie.text_field(:id, “shipping_city”).set’Austin”
       ie.text_field(:id, “shipping_state”).set’TX’
       ie.text_field(:id, “shipping_zipcode”).set’12345′
     end

That is all we would really need, except that I like to add a few more things to blanket information like this.  First, I like to make sure there was nothing left over in the fields from a previous run.  To do that, I do and assert ” (two single quotes) on each of the fields.  The assert expects to have “true” returned.  If is does not, it throws an exception.  So, asserting that the value in a field is  ”  means that if the field is empty, the result is “true” and the assertion passes.  If the field is not empty, then the expression evaluates to “false” and an exception is thrown.  After I have set the values, I like to make sure they contain the value I set.  To do that I do an assert of ‘<value that I set>’.  The method becomes:

     def enter_shipping_information
       assert(ie.text_field(:id, “shipping_name).value == ”)
       assert(ie.text_field(:id, “shipping_address”).value == ”)
       assert(ie.text_field(:id, “shipping_city”).value == ”)
       assert(ie.text_field(:id, “shipping_state”).value == ”)
       assert(ie.text_field(:id, “shipping_zipcode”.value == ”)
       ie.text_field(:id, “shipping_name).set’Joe Tester’
       ie.text_field(:id, “shipping_address”).set’123 Address’
       ie.text_field(:id, “shipping_city”).set’Austin”
       ie.text_field(:id, “shipping_state”).set’TX’
       ie.text_field(:id, “shipping_zipcode”).set’12345′
       assert(ie.text_field(:id, “shipping_name).value == ‘Joe Tester’)
       assert(ie.text_field(:id, “shipping_address”).value == ‘123 Address’)
       assert(ie.text_field(:id, “shipping_city”).value == ‘Austin’)
       assert(ie.text_field(:id, “shipping_state”).value == ‘TX’)
       assert(ie.text_field(:id, “shipping_zipcode”).value == ‘12345’)
     end

The billing method is similar:

     def enter_billing_information
       assert(ie.text_field(:id, “billing_name).value == ”)
       assert(ie.text_field(:id, “billing_address”).value == ”)
       assert(ie.text_field(:id, “billing_city”).value == ”)
       assert(ie.text_field(:id, “billing_state”).value == ”)
       assert(ie.text_field(:id, “billing_zipcode”.value == ”)
       ie.text_field(:id, “billing_name).set’Joe Tester’
       ie.text_field(:id, “billing_address”).set’123 Address’
       ie.text_field(:id, “billing_city”).set’Austin”
       ie.text_field(:id, “billing_state”).set’TX’
       ie.text_field(:id, “billing_zipcode”).set’12345′
       assert(ie.text_field(:id, “billing_name).value == ‘Joe Tester’)
       assert(ie.text_field(:id, “billing_address”).value == ‘123 Address’)
       assert(ie.text_field(:id, “billing_city”).value == ‘Austin’)
       assert(ie.text_field(:id, “billing_state”).value == ‘TX’)
       assert(ie.text_field(:id, “billing_zipcode”).value == ‘12345’)
     end

To pay the bill, we have to enter a valid (test) credit card.

     def enter_valid_credit_card_information
       ie.select_list(:id, “select_credit_card_type”).select’MC’
       assert(ie.text_field(:id, “credit_card_number).value == ”)
       ie.text_field(:id, “credit_card_number).set ‘1234567890123456’
       assert(ie.text_field(:id, “credit_card_number).value == ‘1234567890123456’)
       ie.select_list(:id, “credit_card_expiration_month”).select’August’
       ie.select_list(:id, “credit_card_expiration_year”).select’2008′
     end

Complete the checkout:

     def click_checkout_button
       ie.button(:id, “checkout_button”).click
     end

There is often a summary of the order at then end.  It contains what was ordered, total cost, shipping information, and billing information.  I normally look at each of these separately.  I have made some assumptions of additional total fields on the page.

     def verify_item_ordered
       assert(ie.text_field(:id, “item_ordered”).value == ‘Everyday Scripting with Ruby’
     end

     def verify_total_amount
       item_amount = ie.text_field(:id, “item_amount).text
       shipping_amount = ie.text_field(:id, “shipping_amount”).text
       total_amount = ie.text_field(:id, “total_amount).text
       assert(add_it_up(item_amount, shipping_amount, total_amount))
     end

I need to explain about the method “add_it_up(item_amount, shipping_amount, total_amount).  I am assuming that it is a method defined someplace else that takes the text amounts, converts them into numbers, adds them together, and returns “true” if item_amount and shipping_amount add up to total_amount.  It is not hard to do but I am not including it for simplicity.  I included the reference because I did not want to give you the false impression that you could simply add text numbers together.

     def verify_shipping_information
       assert(ie.text_field(:id, “review_shipping_name).value == ‘Joe Tester’)
       assert(ie.text_field(:id, “review_shipping_address”).value == ‘123 Address’)
       assert(ie.text_field(:id, “review_shipping_city”).value == ‘Austin’)
       assert(ie.text_field(:id, “review_shipping_state”).value == ‘TX’)
       assert(ie.text_field(:id, “review_shipping_zipcode”).value == ‘12345’)
     end

     def verify_billing_information
       assert(ie.text_field(:id, “review_billing_name).value == ‘Joe Tester’)
       assert(ie.text_field(:id, “review_billing_address”).value == ‘123 Address’)
       assert(ie.text_field(:id, “review_billing_city”).value == ‘Austin’)
       assert(ie.text_field(:id, “review_billing_state”).value == ‘TX’)
       assert(ie.text_field(:id, “review_billing_zipcode”).value == ‘12345’)
     end

Save the file with all these method definitions in a file called something like book_purchase_with_credit_card_defs.rb in the same directory as the book_purchase_with_credit_card.rb.  I like to use a name that is descriptive about the particular application I am testing.

We have basically all the pieces we need to run the tests.  Now we have to assemble them into a test that runs.  We have to add some things to the test file, book_purchase_with_credit_card.rb, to define the test case and make it work.  The finished file would look something like this:

dir = File.dirname(__FILE__)

require “#{dir}\/book_purchase_with_credit_card_defs”

require ‘watir’
require ‘watir/testcase’

$ie = Watir::IE.new_process
$ie.set_fast_speed

class TC_BookCheckoutWithCreditCard < Watir::TestCase

  include BookPurchaseWithCreditCard

  def test_01_book_purchase_with_credit_card
    $ie.goto”http://www.mywebsite.com”
    add_an_item_to_the_shopping_cart
    click_go_to_checkout_button
    enter_shipping_information
    enter_billing_information
    enter_valid_credit_card_information
    click_checkout_button
    verify_item_ordered
    verify_total_amount
    verify_shipping_information
    verify_billing_information
  end
end

That should do it for the test case file.  I will offer some simple explanations for the things I added to this file, but you will have to read some Ruby reference material to better understand it.

dir = File.dirname(__FILE__) – Assigns the directory path of the current file to the variable “dir”

require “#{dir}\/book_purchase_with_credit_card_defs” – will read in the contents of the file (book_purchase_with_credit_card_defs) from the current directory.  (Remember, I said to save it to the same directory)

require ‘watir’ – causes all the Watir definitions to be read in

require ‘watir/testcase’ – causes all the Watir test definitions to be read in

$ie = Watir::IE.new_process – says to create a new IE object and assign it to the global variable $ie.  I know that a lot of programmers argue against using global variables, but this is one case where I think it is justified.

$ie.set_fast_speed  – this causes the script to execute quickly.  You may want to comment this out if you are having problems so you can see what is happening

class TC_BookCheckoutWithCreditCard < Watir::TestCase  – defines a new test class which inherits from the Watir TestCase class.  The test class name is made up of words that are run together with their first letter capitalized.

include BookPurchaseWithCreditCard  – This keeps you from having to explicitly reference the module with methods in your defs file.  This is a simpler way to do things for now.  You can research the topic for further information.

def test_01_book_purchase_with_credit_card – This line actually defines a method that is your test case.  It should start with “test_” to allow several test runner programs to find it.  I also number them in the order I want them to run (test_01_).  Some test runner programs run the tests in alphabetical order so this is the simplest way to ensure that your tests are run in the order that you want.

$ie.goto”http://www.mywebsite.com” – I added this to show how you can go to the web site you want to test.

The only thing else new is the two “end” statements.  The first one is for the test_01_book_purchase_with_credit_carddefinition and the second is for the test case class definition, class TC_BookCheckoutWithCreditCard < Watir::TestCase.

That finishes the test case file.  There are a few things we have to do to finish up the “defs” file.  The final “defs” file should look like this:
require ‘watir’
require ‘watir/testcase’

module BookPurchaseWithCreditCard

  include Test::Unit::Assertions

     def add_an_item_to_the_shopping_cart
       $ie.select_list(:id, “selectbook”).select’Everyday Scriptiong in Ruby’
     end

     def click_go_to_checkout_button
       $ie.button(:id, “goto_checkout_button”).click
     end

     def enter_shipping_information
       assert($ie.text_field(:id, “shipping_name).value == ”)
       assert($ie.text_field(:id, “shipping_address”).value == ”)
       assert($ie.text_field(:id, “shipping_city”).value == ”)
       assert($ie.text_field(:id, “shipping_state”).value == ”)
       assert($ie.text_field(:id, “shipping_zipcode”.value == ”)
       $ie.text_field(:id, “shipping_name).set’Joe Tester’
       $ie.text_field(:id, “shipping_address”).set’123 Address’
       $ie.text_field(:id, “shipping_city”).set’Austin”
       $ie.text_field(:id, “shipping_state”).set’TX’
       $ie.text_field(:id, “shipping_zipcode”).set’12345′
       assert($ie.text_field(:id, “shipping_name).value == ‘Joe Tester’)
       assert($ie.text_field(:id, “shipping_address”).value == ‘123 Address’)
       assert($ie.text_field(:id, “shipping_city”).value == ‘Austin’)
       assert($ie.text_field(:id, “shipping_state”).value == ‘TX’)
       assert($ie.text_field(:id, “shipping_zipcode”).value == ‘12345’)
     end

     def enter_billing_information
       assert($ie.text_field(:id, “billing_name).value == ”)
       assert($ie.text_field(:id, “billing_address”).value == ”)
       assert($ie.text_field(:id, “billing_city”).value == ”)
       assert($ie.text_field(:id, “billing_state”).value == ”)
       assert($ie.text_field(:id, “billing_zipcode”.value == ”)
       $ie.text_field(:id, “billing_name).set’Joe Tester’
       $ie.text_field(:id, “billing_address”).set’123 Address’
       $ie.text_field(:id, “billing_city”).set’Austin”
       $ie.text_field(:id, “billing_state”).set’TX’
       $ie.text_field(:id, “billing_zipcode”).set’12345′
       assert($ie.text_field(:id, “billing_name).value == ‘Joe Tester’)
       assert($ie.text_field(:id, “billing_address”).value == ‘123 Address’)
       assert($ie.text_field(:id, “billing_city”).value == ‘Austin’)
       assert($ie.text_field(:id, “billing_state”).value == ‘TX’)
       assert($ie.text_field(:id, “billing_zipcode”).value == ‘12345’)
     end

     def enter_valid_credit_card_information
       $ie.select_list(:id, “select_credit_card_type”).select’MC’
       assert($ie.text_field(:id, “credit_card_number).value == ”)
       $ie.text_field(:id, “credit_card_number).set’1234567890123456′
       assert($ie.text_field(:id, “credit_card_number).value == ‘1234567890123456’)
       $ie.select_list(:id, “credit_card_expiration_month”).select’August’
       $ie.select_list(:id, “credit_card_expiration_year”).select’2008′
     end

     def click_checkout_button
       $ie.button(:id, “checkout_button”).click
     end

     def verify_item_ordered
       assert($ie.text_field(:id, “item_ordered”).value == ‘Everyday Scripting with Ruby’
     end

     def verify_total_amount
       item_amount = $ie.text_field(:id, “item_amount).text
       shipping_amount = $ie.text_field(:id, “shipping_amount”).text
       total_amount = $ie.text_field(:id, “total_amount).text
       assert(add_it_up(item_amount, shipping_amount, total_amount))
     end

     def verify_shipping_information
       assert($ie.text_field(:id, “review_shipping_name).value == ‘Joe Tester’)
       assert($ie.text_field(:id, “review_shipping_address”).value == ‘123 Address’)
       assert($ie.text_field(:id, “review_shipping_city”).value == ‘Austin’)
       assert($ie.text_field(:id, “review_shipping_state”).value == ‘TX’)
       assert($ie.text_field(:id, “review_shipping_zipcode”).value == ‘12345’)
     end

     def verify_billing_information
       assert($ie.text_field(:id, “review_billing_name).value == ‘Joe Tester’)
       assert($ie.text_field(:id, “review_billing_address”).value == ‘123 Address’)
       assert($ie.text_field(:id, “review_billing_city”).value == ‘Austin’)
       assert($ie.text_field(:id, “review_billing_state”).value == ‘TX’)
       assert($ie.text_field(:id, “review_billing_zipcode”).value == ‘12345’)
     end
  end

We are almost done.  Let me give some simple explanations about the additional lines in this file.
require ‘watir’
require ‘watir/testcase’

I have included these again to avoid any possible problems.  You may want to experiment and see which ones you really need in each of the files.

module BookPurchaseWithCreditCard – Defines the module that contains the method definitions you are using.  Note the ”  include BookPurchaseWithCreditCard” line in your test file has to match this module name.

include Test::Unit::Assertions – Allows you to use the “assert” statements in this file.

Note that I have changed all the “ie” (which is a local variable) to “$ie” (which is a global variable).

The last thing is the “end” statement which is the “end” for the module definition.

That is it.  This will not actually run since it is not designed for a specific web site.  If you implemented the “add_it_up” method, you could put it into this “defs” file too.  There is some useful refactoring you can do on this once you get things working.  Get it working first and then refactor.  Some simple things you can do would be to change the following methods from:

     def click_go_to_checkout_button
       $ie.button(:id, “goto_checkout_button”).click
     end

and

     def click_checkout_button
       $ie.button(:id, “checkout_button”).click
     end

to

     def go_to_checkout_button
       $ie.button(:id, “goto_checkout_button”)
     end

and

     def checkout_button
       $ie.button(:id, “checkout_button”)
     end

and then change your test from

    click_go_to_checkout_button
and
    click_checkout_button

to

    go_to_checkout_button.click
and
    checkout_button.click

This puts the “.click” in your test case which is not a big deal, but it allows you to use other button methods on the buttons from your test case.

A more useful thing may be to refactor the “enter_valid_credit_card_information” method to generalize it for other credit cards.  That way you could use it and pass in all the credit card information.  So, you might change it from:
     def enter_valid_credit_card_information
       $ie.select_list(:id, “select_credit_card_type”).select’MC’
       assert($ie.text_field(:id, “credit_card_number).value == ”)
       $ie.text_field(:id, “credit_card_number).set’1234567890123456′
       assert($ie.text_field(:id, “credit_card_number).value == ‘1234567890123456’)
       $ie.select_list(:id, “credit_card_expiration_month”).select’August’
       $ie.select_list(:id, “credit_card_expiration_year”).select’2008′
     end

to something like this:
     def enter_credit_card(type, number, expire_month, expire_year)
       $ie.select_list(:id, “select_credit_card_type”).select”#{type}”
       assert($ie.text_field(:id, “credit_card_number).value == ”)
       $ie.text_field(:id, “credit_card_number).set”#{number}”
       assert($ie.text_field(:id, “credit_card_number).value == “#{number}”)
       $ie.select_list(:id, “credit_card_expiration_month”).select”#{expire_month}”
       $ie.select_list(:id, “credit_card_expiration_year”).select”#{expire_year}”
     end

and then change your test case to:

     enter_credit_card(“MC”, “1234567890123456”, “August”, “2008”)

The variables in enter_credit_card are local variables; type, number, expire_month, expire_year.  They are originally defined in the method definition statement:

enter_credit_card(type, number, expire_month, expire_year)

When you want to use the string value of the variable, the construct “#{type}” says to substitute the string value stored in the variable “type”.

That should get you started.  There are several things I said to do to keep it simple.  If you want to know the detail, you should read Watir or Ruby reference material.  I will end with a list of most common beginner problems:

1.  Capitalizing Watir in the require statement:  require ‘watir’  NOT  require ‘Watir’.
2.  Not putting an “end” for the class statement in the test case file.
3.  Leaving out the “class” statement in the test case file.
4.  Not specifying that your test class inherits from Watir::TestCase.
5.  Not starting the test case definition with def “test_”
6.  If you are using a “defs” file like I showed  you, not including the exact name of the “defs” module in the test case file (within the class definition).
7.  In a “defs” file, forgetting to put in the “module” statement.
8.  In a “defs” file, not putting an “end” statement for the “module” statement.
9.  In a “defs” file, not putting in an “include Test::Unit::Assertions” statement if you are using “assert” statements in the file.

10. Capitalizing of test names instead of keeping them lower case, “test_01_test_to_see_if this_works”.

Links for Ruby – rubyforge the main Ruby site:
http://rubyforge.org/

The easiest Ruby to install on Windows – One Click Ruby: http://rubyforge.org/projects/rubyinstaller/

Watir has two places of interest.  One is on rubyforge: http://rubyforge.org/projects/wtr/

The other is on the openqa.org site: http://openqa.org/

Tags: Ruby, software testing, Watir