You might see a warning similar to this one when you use the new page-object release. I am planning on removing something that current exists in the gem. This post will explain what and why.

What?

When the page-object gem was young there was a significant amount of functionality that existed in the native drivers (watir-webdriver and selenium-webdriver) that was not exposed via the page-object gem. At that time I decided to override method_missing in the Element class to directly delegate all unknown calls to the underlying native element. This was a work around to make it easier for the users to use these capabilities while I was busy adding all necessary functionality into the page-object gem.

I will be removing this capability in about two months. At that time you will get an error when you call a method on an Element that doesn’t exist. The warning message should provide guidance to you on what you will need to change over the next two months.

Why?

Some of you may wonder why I am removing this feature. While it seemed like a good idea at the time I added this capability, it has been the source of most of the support I have provided for users. Many have found it confusing having both page-object and Watir calls mixed together and many errors resulted. At this point, over three fourths of the problems I help people with are directly related to these calls being used together. In almost every case the solution is to only use the page-object elements and methods.

What should I do?

You should run your scripts and note where these warnings occur. When you see them you should adjust your code to use the page-object methods and objects. If you do find that there is some feature you need that is currently not supported by page-object please go to the issues page and open an issue. I will respond to it as soon as possible.

This post is an actual section from chapter 5 of my book. It introduces the concept of Default Data and also shows how to use this new feature.

High level tests

Many of the Scenarios we have written so far suffer from a problem. They are too verbose. What I mean by this is they specify every single keystroke even when it is not important for the actual test. Let’s take a look at the original Scenario where we adopted a puppy.

  Scenario: Adopting one puppy
    When I click the View Details button for “Brook”
    And I click the Adopt Me button
    And I click the Complete the Adoption button
    And I enter “Cheezy” in the name field
    And I enter “123 Main Street” in the address field
    And I enter “cheezy@example.com” in the email field
    And I select “Credit card” from the pay with dropdown
    And I click the Place Order button
    Then I should see “Thank you for adopting a puppy!”

What specifically are we verifying? The only thing we are verifying is that the “Thank you” message is displayed. Does it really matter what name I enter in the name field? What about the puppy I select for adoption?

The truth is that none of the data I enter or select on the screens has any impact on the outcome for this particular Scenario. That is also the case with most Scenarios. Although we often have to enter a lot of information in order to complete a Scenario the majority of the information is not directly relevant for the thing we are testing.

A major part of writing good Scenarios is ensuring they are written well and easy to understand. Imagine if we have to traverse through multiple pages to get to the page we plan to tests and each page requires us to enter a lot of data. If we specify all of the typing and clicks in our Scenario there would be a lot of details. It would be very easy to see how one could loose the simple items we wish to specify in all of those details.

Below is the same Scenario as above except all of the unnecessary details are hidden:

  Scenario: Thank you message should be displayed
    When I complete the adoption of a puppy
    Then I should see “Thank you for adopting a puppy!”

This Scenario is much easier to understand and we can clearly see what is being specified. We still need to perform all of the activities necessary to adopt a puppy even though we did not specify them in the Scenario. The next few sections will provide some techniques you can use to enable you to specify your Scenarios at a right level of granularity and still have all of the detailed steps take place.

Inline Tables

In chapter four we saw how we can build up a table of Examples to provide the data for a Scenario Outline. It is also possible to have a table of data that is a part of an individual step. Let’s see how would could place an order using a table of data. We’ll make a modified version of the Scenario from the last section.

  Scenario: Adopting a puppy using a table
    When I click the View Details button for “Brook”
    And I click the Adopt Me button
    And I click the Complete the Adoption button
    And I complete the adoption with:
    | name   | address         | email              | pay_type |
    | Cheezy | 123 Main Street | cheezy@example.com | Check    |
    Then I should see “Thank you for adopting a puppy!”

In this case we’ve collapsed five steps into one. Go ahead and write this Scenario and generate the one new step definition. In this case we will be passing all of our test data to the page in one step. When you generate you step definition you will notice that a table variable is passed into your step. For our purposes we can just call a hashes method on table which will return an Array of Hashes. Each entry in the Array represents one row of data with the key being the table header and the value being the data in the table. Since we only have one row of data we will just call the first method on this Array to get the single Hash containing our data.

We have two options for the implementation. The first option is to use the methods generated by PageObject like this:

When /^I complete the adoption with:$/ do |table|
  data = table.hashes.first
  on_page(CheckoutPage) do |page|
    page.name = data['name']
    page.address = data['address']
    page.email = data['email']
    page.pay_type = data['pay_type']
    page.place_order
  end
end

Although this step definition works fine most of the code seems to be a little out of place in the step definition. The knowledge of how to take a group of data, complete the form, and submit it would seem to be better place in the page object itself. Let’s take a look how that might work.

Here is a new method on CheckoutPage:

  def complete_order(data)
    self.name = data['name']
    self.address = data['address']
    self.email = data['email']
    self.pay_type = data['pay_type']
    place_order
  end

The first thing you might notice is that we are using the keyword self in our new method. The reason for this is that equals methods (one that end with an equal sign) are required to have a receiver so they are not mistaken for local variable assignment. self represents the current object and therefore when we call self.name = we are really saying call the name= method on this same object.

With this method on our page object our step definition can be simplified to this:

When /^I complete the adoption with:$/ do |table|
  on_page(CheckoutPage).complete_order(table.hashes.first)
end

DO NOT OVERUSE TABLES
Tables are nice and do help us consolidate multiple steps into one but they also make things a little harder to read. Use you best judgement on when you believe it adds to the overall Scenario and make sure you do not overuse them to the point where it takes away from what we are trying to say.

Default Data

It is fairly common for your Scenarios to require a lot of data in order to complete a successful run. In the last section we discussed how to use tables to create higher level tests. In that Scenario it really didn’t matter if we used the name “Cheezy” or “Mickey Mouse”; the outcome would be the same. In fact, none of the data we provide made any difference on the outcome. As long as we select a puppy and complete the checkout form we see the thank you message.

We should ask ourselves why do we need to provide all of this data if it is not important to what we are testing. Does providing this data really add clarity or is it distracting? Does specifying every click necessary to traverse through the system add to our understanding? Does it make the specification more complete?

If we were able to rephrase the Scenario from the last section to state the exact essence of what we were trying to specify it would be this:

  Scenario: Thank you message should be displayed
    When I complete the adoption of a puppy
    Then I should see “Thank you for adopting a puppy!”

This is much cleaner and easier to understand. It specifies the exact thing we are trying to describe – a thank you message should be displayed when the adoption is completed.

In order to implement the Scenario above we still need to provide the information necessary to fill in and submit the pages of our application. But where will it come from? This is where Default Data comes in.

Default Data is a widely used pattern in the testing community. The pattern is implemented by providing a set of data that can be used to generically traverse through the application but at the same time allowing you to override any data specific to your context. For example, take the last Scenario. In that Scenario we should just be able to use the Default Data to complete all of the pages and the validate the message. If required us to use a “Credit card” then we should be able to specify it override the default value and use “Credit card”. Let’s see how we could implement this in our CheckoutPage.

class CheckoutPage
  include PageObject

  DEFAULT_DATA = {
    ‘name’ => ‘cheezy’,
    ‘address’ => ‘123 Main Street’,
    ‘email’ => ‘cheezy@example.com’,
    ‘pay_type’ => ‘Purchase order’
  }

  text_field(:name, :id => “order_name”)
  text_field(:address, :id => “order_address”)
  text_field(:email, :id => “order_email”)
  select_list(:pay_type, :id => “order_pay_type”)
  button(:place_order, :value => “Place Order”)

  def complete_order(data = {})
    data = DEFAULT_DATA.merge(data)
    self.name = data['name']
    self.address = data['address']
    self.email = data['email']
    self.pay_type = data['pay_type']
    place_order
  end
end

There are several new things here to discuss. The first is the Hash near the top of the class. It simply provides the default data that will be used by the page. The way this happens is that the first line of the complete_order method merges the data passed to the method with the default data of the page. The merge simply tries to match up a key and if a match is found it will update the corresponding value.

The other new thing here is the modified parameter passed to our complete_order method – data = {}. This is Rubies way of specifying a default parameter to a method. If we provide a parameter when we call this method then it is passed on through. If we call the method without passing a parameter the default will be used which is an empty Hash is this case. The effect of using the empty Hash is to just use all of the default data.

If you are using PageObject 0.5.3 or higher there is an even simpler way to populate your page with a Hash of data. A new method has been added named populate_page_with which takes a Hash. It will match up the keys from the Hash with the names you provided for the elements when you declared them on the page. All values must be Strings except for Checkboxes and Radio Buttons must be true or false. Let’s look at our complete_order method if we use this instead.

When /^I complete the adoption using a Credit card$/ do
  on_page(CheckoutPage).complete_order(‘pay_type' => 'Credit card')
end

When /^I complete the adoption$/ do
  on_page(CheckoutPage).complete_order
end

I think we have achieved the goal of default data. We can now individually set the values on the page using the methods generated by page-object. We can use the default data by calling the complete_order method passing no parameters. We can use partial or no default data by passing in a Hash that contains the data we wish to use.

The only additional page we have in our system where we have to provide data is the HomePage. Providing default data for this page is as simple as providing a default parameter for the adopt method.

def adopt(name = ‘Brook’)
  index = puppy_index_for(name)
  button_element(:value => 'View Details', :index => index).click
end

With this in place we can now get back and add the Scenario we introduced at the beginning of this section and add the missing step definition.

When /^I complete the adoption of a puppy$/ do
  on_page(HomePage).adopt
  on_page(DetailsPage).adopt_me
  on_page(ShoppingCartPage).complete_adoption
  on_page(CheckoutPage).complete_order
end

In this post I’ll write a simple scenario that demos the async handling capabilities in the page-object gem. I’ll also briefly introduce you to a new gem that I use to generate my new projects. I’ll do all of this by writing a scenario that uses one of the examples google has provided to demo the GWT libraries. For those of you who have taken one of my classes you will already be familiar with this example but perhaps there are still a few things here for you to learn. Let’s get started writing the code!

Creating the project

The first thing I need to do is create my project structure. Let me see. I think I’ll use the page-object gem with Selenium. Let’s use the tesetgen gem to get started. If you don’t have this gem installed already you can just execute gem install testgen. Here’s the command I used to generate my project:

testgen project ajax_example --pageobject-driver=selenium

This creates my entire project structure. Let’s quickly verify that everything is OKay. The first thing we need to do is make sure we have all of the gems installed. testgen created a Gemfile file for us so all we need to do is change to the newly created ajax_example directory and execute bundle install.

Now that we’re sure we have all of the gems installed it’s time to run cucumber. testgen created a Rakefile for us to make that easy. Just type the rake command in the ajax_example directory. You should see the following:

Using the default profile...
0 scenarios
0 steps
0m0.000s

We’re now ready to write a scenario.

Writing the scenario

We’ll be using the DynaTable example from the GWT site. Here is the page. On this page select a day checkbox and then the classes offered on that day are displayed in the row with the professors name. Let’s try to write a scenario.

I start by creating a file in the features directory. Here’s the content:

Feature: Displaying class schedules

I need to be able to display the class schedule for professors.  When I
select a day the page should display all of the class taught by professors
on that day as well as the time for the classes.

  Scenario: Displaying classes offered by professors
    Given I am on the google dynamic table page
    When I view the schedule for "Monday"
    Then I should see that "Inman Mendez" offers a class at "Mon 9:45-10:35"
    When I view the schedule for "Tuesday"
    Then I should see that "Inman Mendez" offers a class at "Tues 2:15-3:05"
    And I should see that "Teddy Gibbs" offers a class at "Tues 10:00-10:50"

Notice that I didn’t say anything about clicking buttons or checkboxes. Also notice that I in no way stated how the class or instructor’s name are found or represented on the page. Why do you think I did this? I’ll have a lot more to say about this in future posts.

My next step is to create the step definitions. To do this I will again execute the ‘rake’ command. Cucumber is nice enough to generate the pending step definitions.

Given /^I am on the google dynamic table page$/ do
  pending # express the regexp above with the code you wish you had
end

When /^I view the schedule for "([^\"]*)"$/ do |arg1|
  pending # express the regexp above with the code you wish you had
end

Then /^I should see that "([^\"]*)" offers a class at "([^\"]*)"$/ do |arg1, arg2|
  pending # express the regexp above with the code you wish you had
end

I know I’m going to create a page object but first of all I want to think about what that object will look like. I think I’ll write the code I wish I had in a couple of the step definitions. Here’s what I came up with:

When /^I view the schedule for "([^\"]*)"$/ do |day|
  page.select_schedule_for day
end

Then /^I should see that "([^\"]*)" offers a class at "([^\"]*)"$/ do |name, expected|
  page.schedule_for(name).include? expected
end

Yeah. I think that's how I want to interact with the page object. These step definitions are not complete. I have just written enough to understand what I need to include in the page object I am about to write. Now, let's write it.

Creating the Page Object

In order to implement the functionality I currently need in my page object I will need to provide access to the day checkboxes, the none button (in order to clear all of the checkboxes), and the table that contains the schedules. I'll also need to provide the url for the page. I create a new file in the pages directory named dynamic_table_page.rb. Here's the first version of this class:

class DynamicTablePage
  include PageObject

  page_url "http://gwt.google.com/samples/DynaTable/DynaTable.html"
  table(:dyna_table, :class => 'table')
  checkbox(:sunday, :id => 'gwt-uid-1')
  checkbox(:monday, :id => 'gwt-uid-2')
  checkbox(:tuesday, :id => 'gwt-uid-3')
  checkbox(:wednesday, :id => 'gwt-uid-4')
  checkbox(:thursday, :id => 'gwt-uid-5')
  checkbox(:friday, :id => 'gwt-uid-6')
  checkbox(:saturday, :id => 'gwt-uid-7')
  button(:none, :value => 'None')

end

The next thing I need to do is write the two methods I determined I needed earlier. Here they are:

def select_schedule_for(day)
  none
  self.send "check_#{day.downcase}"
end

def schedule_for(name)
  the_row = dyna_table_element.find { |row| row[0].text == name}
  the_row[2].text
end

I think there are a few things here that need explaining. Let's take it one method at a time.

Sending messages

In the first method we are pressing the none button which clears all of the checkboxes. Next we check the appropriate checkbox. The page-object gem generates four methods when you define a checkbox. Let's look at the four methods generated for the :monday checkbox declaration above.

def check_monday
  # check the monday checkbox
end

def uncheck_monday
  # uncheck the monday checkbox
end

def monday_checked?
  # return whether the monday checkbox is checked
end

def monday_element
  # return the monday checkbox element
end

Understanding the generated methods it makes it clear that what we want to call is the check_? method. When you call a method in Ruby it actually sends a message to the object on which the call is to be made. In fact, Ruby provides a send method that performs the actual call. In other words:

page.check_monday

# is the same as

page.send "check_monday"

This is what allows us to call the appropriate checkbox method based on the name passed into the method. Notice that we force the day name to lowercase so "Monday" as an argument yields check_monday.

def select_schedule_for(day)
  none
  self.send "check_#{day.downcase}"
end

Allow me to Enumerate

Ruby has a module mixin named Enumerable. The numerous methods provided by this module add the ability to traverse, search, and sort items in a collection. In the page-object gem the Table, TableRow, OrderedList, and UnorderedList elements all include Enumerable. This provides the ability to perform activities on their children. For example, you can loop through all of the TableRow elements by using the methods on Table and then you can loop through the TableCell elements by calling the methods on TableRow.

We use one of the methods from Enumerable to help us find the correct row in the table. The find method calls a block one time for each item in the list. The method will return the first item in which the block returns true. We can look for the name of the professor by looking at the first column of the table.

def schedule_for(name)
  the_row = dyna_table_element.find { |row| row[0].text == name}
  the_row[2].text
end

The final thing we need to do is return the text from the third row column which contains the courses offered.

Getting rid of the magic

The final change I wish to make to the page object is to eliminate the magic numbers. Magic numbers are numbers that appear in code that have a significance but their meaning is not obvious. For example, we are using 0 and 2 in the schedule_for method. If I come back to this code several months after writing it I am sure I will not remember exactly what those numbers mean. To resolve this I will add constants that provide some meaning. After making that change you can see the entire class.

class DynamicTablePage
  include PageObject

  NAME_COLUMN = 0
  SCHEDULE_COLUMN = 2

  page_url "http://gwt.google.com/samples/DynaTable/DynaTable.html"
  table(:dyna_table, :class => 'table')
  checkbox(:sunday, :id => 'gwt-uid-1')
  checkbox(:monday, :id => 'gwt-uid-2')
  checkbox(:tuesday, :id => 'gwt-uid-3')
  checkbox(:wednesday, :id => 'gwt-uid-4')
  checkbox(:thursday, :id => 'gwt-uid-5')
  checkbox(:friday, :id => 'gwt-uid-6')
  checkbox(:saturday, :id => 'gwt-uid-7')
  button(:none, :value => 'None')

  def select_schedule_for(day)
    none
    self.send "check_#{day.downcase}"
  end

  def schedule_for(name)
    the_row = dyna_table_element.find { |row| row[NAME_COLUMN].text == name}
    the_row[SCHEDULE_COLUMN].text
  end
end

Finishing the Step Definitions

I can now finish the step definitions. I'll be using the PageObject::PageFactory to create my objects. Let's look at the steps and then we can discuss the details.

*)"$/ do |day|
  on_page(DynamicTablePage).select_schedule_for day
end

Then /^I should see that "([^\"]*)" offers a class at "([^\"]*)"$/ do |name, expected|
  on_page(DynamicTablePage) do |page|
    page.wait_until(2) do
      page.schedule_for(name).include? expected
    end
  end
end

The third step beginning on line nine is where the ajax heavy lifting occurs. I am using the wait_until method available on PageObject. There are numerous methods to handle ajax calls baked into the gem. This particular method will wait until the block returns true. By default it will wait for 30 seconds but I thought that was too long so I am passing in 2 to set the wait time to 2 seconds. If the expected text for the schedule does not show up within 2 seconds an error will be thrown and the step will fail.

Wrapping up

Please take the time to look at the other methods that page-object provides that make testing ajax sites simple. As always, please let me know what you think of this post.

The truth is that I don’t run them. Instead I have a server process run the features for me. I am a strong advocate of having the continuous integration server run the acceptance tests continuously. This post will explain how I do it and hopefully provide you the information you need to do it as well.

Let’s be clear

Before I go into the details let me be clear. I am not proposing that this is the only way you and your team should run your features. I am a proponent of developers running the feature they are working on all of the time (perhaps continuously) and I think testers should run them on their computer very frequently as well. This post is about how I like to run the entire suite of features to form a regression. I’ll start by introducing how I control the running of the features and setup my projects. Next I’ll discuss how this works with Jenkins.

cucumber.yml

First of all I have a cucumber.yml file at the root of my project structure. I use this file to define a set of profiles (a grouping of command-line arguments) that I can easily use when I want to run my features. Cucumber already has a default profile that will be used unless you override it. Here is what that might look like:

default:  --no-source --format pretty --tags ~@not_ready

Everything after the default: label in the entry will be passed to cucumber as arguments when it runs.

You can use profiles to define separate definitions of how you want to run your features. For example, if you have some very slow tests you might want to separate them out into their own run. You would start by placing a @slow tag on those features or scenarios and then create a few profiles like this:

default:  --no-source --format pretty --tags ~@not_ready
slow:  --no-source --format pretty --tags @slow --tags ~@not_ready
fast:  --no-source --format pretty --tags @~slow, ~@not_ready

To use the profiles you simply pass the profile name on the command line. If you wish to run the fast tests you would run:

cucumber -p fast

Rakefile

Rake is a tool that has the ability to execute tasks. Many tools, including cucumber, are distributed with pre-built rake tasks that can be used to control their execution. Jenkins has a plugin that can execute Rakefiles. We use this combination to control the running of our features in Jenkins. We will discuss how to setup Jenkins in the next section. Here we’ll discuss how to write a simple Rakefile. Let’s start by looking at a simple example.

require ‘cucumber’
require ‘cucumber/rake/task’

Cucumber::Rake::Task.new(:features) do |t|
  t.profile = ‘ci’
end

task :default => :features

This rake script creates a new task named features and has it call the ci profile. Next it makes the features task the default task. You can execute rake in the project directory and it will run the features task (the default) using the ci profile created in a cucumber.yml file. We use the Rakefile to specify which profile to run and we use the cucumber.yml file to detail out the profiles.

A more sophisticated Rakefile might create a namespace to contain several tasks.

require ‘cucumber’
require ‘cucumber/rake/task’

namespace :features do
  Cucumber::Rake::Task.new(:fast) do |t|
    t.profile = ‘fast’
  end

  Cucumber::Rake::Task.new(:slow) do |t|
    t.profile = ‘slow’
  end

  task :ci => [:fast, :slow]
end

task :default => :fast

This Rakefile creates a namespace named features, which contains three tasks (fast, slow, and ci). The ci task runs the fast task followed by the slow task. To execute the slow tests you would execute

rake features:slow.

If you want to see what tasks are available from the rake tool you can execute the rake –T command.

Jenkins

The Jenkins configuration couldn’t be simpler. The first thing you need to do is install the Jenkins Rake plugin. Once this is installed you should go to the Configure System page. You will see a new section appear on this page.

It is likely that Jenkins discovered your ruby installation already but if it didn’t, just enter the path to the location where ruby is installed.

Next you need to create the project to run your cukes. Complete the form as you usually would. In the Build section select the Add build step button and then select Invoke Rake. This will open this dialog.

In this section you simply need to type the task you wish to run.

Guidelines I use to run my cukes

How often should you run your features? In my opinion, you should try to run them as close to all of the time as possible. Each time they run they should execute against the latest version of the application.

If it takes 2 hours 30 minutes to run the tests I would schedule them to run every 3 hours. If you have some slow tests you might want to schedule them to run 4 times a day and have the fast test run every hour.

The goal here is to get fast feedback.

One thing I have found difficult to work with is pages that have frames and iframes. It gets worse when the elements you are trying to work with are nested within multiple frames/iframes. To address this complexity I decided to add simple frames handling to page-object.

The page-object gem provides a way to declare elements are within frames or iframes. In fact, these frames can be nested infinitely. Let’s look at a simple case.

class RegistrationPage
  include PageObject

  in_frame(:id => 'left-frame') do |frame|
    text_field(:address, :id => 'address_id', :frame => frame)
  end
end

In this example we are declaring that the textfield exists within a frame identified by the id ‘left-frame’. Note that I am passing the frame argument for the block as the last parameter to text_field. In the remainder of my class I can just refer to the element by its’ name – in this case ‘address’.

Frames can be identified by :name, :id, or :index and frames and iframes are handled identically.

Let’s take a look at how we would handle a situation where the frames (or iframes) are nested within other frames. We’ll modify the example above.

class RegistrationPage
  include PageObject

  in_frame(:id => 'left-frame') do |frame|
    in_frame({:id => 'left-top-frame'}, frame) do |frame|
      text_field(:address, :id => 'address_id', :frame => frame)
    end
  end
end

There are a couple of interesting things here. First of all we just nested our previous call to in_frame in another call to the same method. Also note that we had to pass the frame block parameter from the first call to the second call to in_frame. This method is how page-object keeps track of the frame nesting and allows you to nest calls to in_frame as many times as necessary.

That’s all there is to it. Enjoy.

This post will walk you through some of the core features of the gem. Most of the materials in this post are also on the project wiki. Please refer to the wiki for updated documentation.

Get me started right now!

For the impatient among you we will get directly to showing you how to use it.

Create your page

The first thing you must do is create your page objects. These are simple ruby classes that include the PageObject Module.

class RegistrationPage
  include PageObject
end

By including the PageObject Module you have added a lot of capabilities to your page. Let’s take a look at how we might use some of that right now.

Describe your page

After you create your page object class you need to describe the web page this class represents. The RegistrationPage example might look like this:

class RegistrationPage
  include PageObject

  text_field(:name, :id => 'name')
  text_field(:email, :id => 'email')
  button(:register, :value => 'Register')
end

By calling these methods, the PageObject Module will add several additional methods for you. To learn about what methods are available and what methods they generate please see this page.

Use your page

Now that we have a basic page object defined it is time to put it to use. You can use either watir-webdriver or selenium-webdriver as the driver gem. Just pass them into the constructor.

browser = Watir::Browser.new :firefox
registration_page = RegistrationPage.new(browser)

or

browser = Selenium::WebDriver.for :firefox
registration_page = RegistrationPage.new(browser)

Once created, you can interact with the page using the generated methods.

registration_page.name = 'Test User'
registration_page.email = 'test@example.com'
registration_page.register

That’s all there is to getting started with the gem. The good news is that there is a lot of additional functionality that was not covered in this brief introduction. Continue reading to learn more.

Page-Object Features

Here are a few of the features you will find in this gem:

A simple DSL for defining and interacting with the content of your page

The PageObject Module adds several methods to your page object. The methods that are added follow a similar pattern. Let’s take a look at a few of the methods and their generated output.

The call to text_field like this one

text_field(:first_name, :id => 'first')

will produce the following three methods

first_name               # return the value in the text field
first_name=              # set the value in the text field
first_name_element       # return the text field element

There is one special purpose generator method that does not follow this pattern. When you call the page_url method

page_url 'http://google.com'

it will produce a method named goto. To see all of the methods available and what methods the generated read the documentation for the Accessors module here.

Support for both watir-webdriver and selenium-webdriver

The page-object gem can use either watir-webdriver or selenium-webdriver as the underlying gem to drive the browser. The way you choose which driver to use is by passing it into the constructor of your PageObject

browser = Watir::Browser.new :firefox
registration_page = RegistrationPage.new(browser)

or

browser = Selenium::WebDriver.for :firefox
registration_page = RegistrationPage.new(browser)

In order to make this work seamlessly, the page-object gem had to add capabilities found in one driver and not in the other. Let’s look at one example.

Locating elements

There were differences in the way Watir and Selenium allowed you to locate elements on a page. We had to add functionality to page-object to eliminate those differences. Here are a few notable ones:

• Watir allows you to provide multiple locators when identifying an element on a page. Selenium only allows you to provide one locator. With page-object you can now use multiple parameters when using Selenium.
• Watir provides the ability to use :index when locating an element. Selenium did not have this capability. With page-object you can now use :index when using Selenium.
• In Selenium you could not find a link by :href while this ability existed in Watir. With page-object on Selenium you can now use :href when identifying a link.
• Watir supports finding a hidden field by :text. This ability does not exist in Selenium. With page-object you can find a hidden field by :text when using Selenium.
• What did not support finding div, span, table, table data, ordered lists, unordered lists, and list items by :name. Selenium had this ability. With page-object you can now find these elements using :name.

Creating and using page objects

Alister Scott blogged about an idea for creating a factory to create instances of page objects. In the past I have blogged about page objects returning page objects. After a lot of contemplation, I am completely in the Alister camp. page-object now supports this approach as well.

PageFactory

A module named PageFactory provides this ability. This module has two methods.

def visit_page(page_class, &block)
def on_page(page_class, visit=false, &block)

Let’s take a look at how you would use these methods in your cucumber scripts.

Given /^I am on the registration page$/ do
  visit_page RegistrationPage
end

This call will cause the browser to open the page specified by the call to page_url in the class.

class RegistrationPage
  include PageObject

  page_url "http://mysite.com/registration"
  ...
end

If you wish to perform some activity on that page when you navigate to it you can pass a block to the method.

When /^I register on the registration page$/ do
  visit_page RegistrationPage do |page|
    page.register_user
  end
end

If you are already on a page and wish to interact with it you can use the on_page method.

Then /^I should be able to cancel my order$/ do
  on_page CheckoutPage do |page|
    page.cancel_order
  end
end

Handling Ajax calls

The secret to working with Ajax is having the ability to wait until different page events occur. The page-object gem supports waiting at two different levels – the page level and the element level. Let’s look at both.

Page level waiting

On the PageObject module (and therefore on your page objects) there is a method that assist with waiting.

def wait_until(timeout=30, message=nil, &block)

This method will wait until the passed in block returns true. If the block does not return true within the specified timeout seconds then an error is thrown with a default message or the provided message. Let’s take a look at how we might use this.

@page.wait_until do
  @page.text.include? "Success"
end

In this example we are using the default timeout and message. This code will wait until the page includes the text “Success”. Let’s look at another example.

@page.wait_until(5, "Call not returned within 5 seconds") do
  @page.text.include? "Value returned from Ajax call"
end

In this example we are setting the timeout to 5 seconds and providing a custom message.

Element level waiting

On the Element class we have several methods to assist with waiting.

def when_present(timeout=5)
def when_visible(timeout=5)
def when_not_visible(timeout=5)
def wait_until(timeout=5, message=nil, &block)

The usage of the first three methods are fairly self explanatory. They will simply wait until the element is present, visible, or not visible and then continue. If the wait exceeds the timeout value then an error occurs. Let’s look at a simple example.

@page.continue_element.when_visible do
  @page.continue
end

As of release 0.3.2 you can combine these into a single call like this:

@page.continue_element.when_visible.continue

In this code we are waiting until a link defined by a call to link(:continue, :id => 'cont') is visible and then we are clicking it.

There are times when you want to wait for something other than the element being present or visible. The last wait call wait_until handles this well. It will wait until the block returns true.

Handling JavaScript popups

Handling JavaScript popups in Watir and Selenium has always been a hassle. The approach the page-object gem takes is to intercept the call to the popup and cause it to not happen. At the same time, the gem provides the information to the user that they would wish to receive if they had access to the popup. Let’s look at a few examples.

Alerts

The PageObject module has a method named alert. Her’s how you can use it.

message = @page.alert do
  @page.button_that_cases_the_alert
end
message.should == "My Alert!"

This call demonstrates that we are passing a block to the alert method. That block is the code that causes the alert to occur. The alert will not popup but the message that was included in the popup is returned by the block.

Confirms

PageObject also has a confirm method that handles confirm popups. It works the same way as the alert method except it requires a boolean parameter which is the value returned to the browser when the confirm popup is called. Here’s an example.

message = @page.confirm(true) do
  @page.button_causing_the_confirm
end

Prompts

Finally, PageObject has a prompt method that follows the same pattern. There are two differences. The first is that it accepts a parameter that is the value returned from the prompt. The second is that it returns a Hash with two keys – :message contains the message from the confirm popup and :default_value contains the default value if one was provided.

confirm_result = @page.prompt("Cheese") do
  @page.what_do_you_like_button
end
confirm_result[:message].should == "What do you like?"

Additional documentation

You can read the RDoc documentation here.

The ChangeLog with the gem’s history can be found here.

Requesting features and reporting issues

The project has an Issues tracker where you can request new functionality and report defects.

A transform is a filter that can be applied to step definition arguments to refactor out common code. The simplest example is one in which you want to convert all number arguments to numbers instead of strings. Actually this can be used for far more advanced transformations than just numeric transformations. Let’s look at a few examples and rewrite some step definitions from previous postings at the same time.

Looking back

In a previous article we wrote cukes to verify the contents of a shopping cart. We had Scenarios that had steps like this:

And I should see "Pragmatic Project Automation" in the description for line "1"
And I should see "29.95" in the each for line "1"
And I should see "29.95" in the total for line "1"

and the corresponding step definitions:

Then /^I should see "([^\"]*)" in the description for line "([^\"]*)"$/ do |desc, line|
  @shopping_cart.description_for_line(line.to_i).should == desc
end

Then /^I should see "([^\"]*)" in the each for line "([^\"]*)"$/ do |each, line|
  @shopping_cart.each_for_line(line.to_i).should == "$#{each}"
end

Then /^I should see "([^\"]*)" in the total for line "([^\"]*)"$/ do |total, line|
  @shopping_cart.total_for_line(line.to_i).should == "$#{total}"
end

The first thing I would like to point out is that I am calling to_i on each line value passed into the step. The second thing to notice is that I am transforming each book price to a dollar amount like "$#{total}". These are both candidates for using Transforms.

Two transforms to go

Let’s start by eliminating the need to convert the string line number to a number. The common pattern here is that we are stating line "1" in each step. Let’s create a Transform for this.

Transform /^line (\d+)$/ do |line_string|
  line_string.to_i
end

This transformation works by looking through the Scenarios and finding portions of steps that match "line N" where N is a number. When it finds a match it calls our Transform and places the number string value into the line_string parameter. The code in the step simply calls to_i on the string to convert it to a number. Notice that we did not include the double quotes in the pattern to match. With this simple Transformation we can eliminate all of the duplicate to_i calls in our steps. We can also eliminate the need for the double quotes around the number.

Then /^I should see "([^\"]*)" in the description for (line \d+)$/ do |desc, line|
  @shopping_cart.description_for_line(line).should == desc
end

Notice how our pattern in the step definition is (line \d+). We are creating the pattern that will match our Transform. We also need to modify the Scenario to remove the double quotes.

And I should see "Pragmatic Project Automation" in the description for line 1

Very good!

Now let’s move on to the dollar transformation. We need to create a transformation for any number of digits, a period, and exactly two digits. Here is what that looks like.

Transform /^(\d+\.\d{2})$/ do |dollar_amount|
  "$#{dollar_amount}"
end

And with this transformation we can now remove all of the string formatting in our step definitions.

Then /^I should see "([^\"]*)" in the each for line "([^\"]*)"$/ do |each, line|
  @shopping_cart.each_for_line(line.to_i).should == each
end

Then /^I should see "([^\"]*)" in the total for line "([^\"]*)"$/ do |total, line|
  @shopping_cart.total_for_line(line.to_i).should == total
end

That’s all there is to it. By creating these simple transformations I was able to eliminate duplication I had in several step definitions.

If you’re interested in what’s coming up, I plan to release another chapter next week that parses and creates XML in our tests. After that I will release a new version of these chapters using a new example application. After that…

Outline

I’ve had several people ask me for a full outline for my book. Here are the chapter titles and brief description. This is all subject to change of course.

1. Introducing Acceptance Testing: 
This chapter will begin with a discussion on what is wrong with the way we typically test software today. It will point out the waste/rework caused by testing software after development and duplication caused by writing detailed test plans. It will then turn the focus on acceptance test driven development and demonstrate the efficiencies gained by adopting this practice. It will conclude with a description of how acceptance test driven development effects the entire process of delivering high quality software.

2. Installing the software: 
This chapter takes the reader through the process of installing Ruby, cucumber and a few additional gems, and an evaluation copy of RubyMine. Through the book I demonstrate how to do the activities through both the command-line and RubyMine.

3. Getting our feet wet with Watir: 
Watir is the foundation of my web testing strategy. In this chapter I introduce the reader to some basic Ruby concepts as well as taking them through the process of writing a few simple scripts using Watir. Along the way we also introduce a few design concepts to help us keep our code clean and maintainable. This is one of the two sample chapters I am including in this proposal

4. Getting started with Cucumber
: We finally introduce the reader to cucumber. We also introduce more Ruby concepts including classes. After writing a few basic scenarios and scenario outlines we turn our focus to writing more robust scenarios with page objects and default data. We conclude the chapter by discussing what level of granularity to use when writing scenarios.

5. Using a database in our tests: 
Frequently we need to stage or read data for out tests. In this chapter we introduce ActiveRecord as well as a few additional gems (factory_girl and pickle) to make this task easier. We do this by writing a couple of Scenarios against the database for our example web application and then enhance it by adding additional gems and techniques. We also demonstrate how our default data pattern from the previous chapter is applicable to this testing area.

6. Testing XML: 
Producing or validating XML is a common task for testers. This chapter introduces a couple of gems to help with this task. We end the chapter by creating scenarios that can create an XML contact list and then other scenarios that can verify the content of that list.

7. At your service: 
Service oriented architectures are still very popular. In this chapter we write a feature that specifies a web service that stock quotes. The scenarios will test both a restful and soap version of this service.

8. Ready for Web 2.0
: Testing applications that have a lot of javascript and ajax calls introduces a new set of challenges. We tackle these challenges head on by writing scenarios against an ajax version of our example web application. We finish the chapter by writing an extension to the Watir gem that allows us to test drag-and-drop.

9. Going Mobile: 
Most people still manually test their mobile applications. In this chapter we introduce iCuke to test an iPhone application. We also demonstrate how the page object and default data patterns apply to this type of testing.

10. Hanging out with the natives: 
Sometimes our tests need to make calls into libraries written in compiled languages. This chapter will begin writing scenarios to test the functionality of a library written in C. We will then proceed by using the gem ffi to create a wrapper around the library to enable us to make direct calls. Next we will write a higher level domain specific language to make our calls simpler. We will finish by using the DSL in our step definitions to complete the tests.

11. I’ve lost my head: 
In this chapter we will write the Scenarios for an application that reads data from a set of tables, performs some data transformation, and then writes the data into another set of tables. A secondary focus will be on how do you test an application when you can’t see it run. We will also build upon some of the design patterns we introduced in previous chapters.

12. Mocking processes: 
What do you do when the software you are testing needs to talk to hardware? What do you do when you application talks to a web service that doesn’t exist yet? This chapter focuses on creating surrogates for volatile or missing components in order to facilitate testing now.

Appendix A: Watir Quick Reference

Appendix B: RSpec Matcher Quick Reference

I initially decided I would write a blog series. When I outlined it I quickly determined it would take nearly thirty entries to share all I wanted to share. That was when I came up with the crazy idea of writing a book. I had no idea what I was getting myself into. For the past several months I have spent a fair amount of my free time (do I really have free time?) working on this book. With this post I am releasing the first two chapters of that book.

The book is primarily written for testers with little or no scripting experience. In the book I am introducing the reader to Acceptance Testing, Ruby, Cucumber, and good design principles. Perhaps that is too much to ask for one book but I’ll let you be the judge.

The two chapters below will need a fair amount of rework. You see, I made a mistake. When I got started with this endeavor the words started flowing rapidly. I really needed a simple application I could use to write my tests against. An application quickly came to mind and I downloaded it and started to use it in my writings. A few months and several chapters later I decided to check to make sure I really had the “rights” to use this example. I didn’t.

I am in the process of completing a new example application and once it is finished I will be changing these chapters (and others) to use it.

What’s covered?

The book talks about techniques and patterns that can be used to tests many different types of applications. There are a few chapters on testing web applications but there are also chapters on testing mobile applications, native win32 applications, web services, as well as headless applications. We also have chapters that cover reading and writing XML and using databases in your tests.

When will the book be released?

I have most of the book written although I will have to rewrite a few chapters once I finish the new example application. The main item that remains is finding a publisher (if you’re out there please give me a call!). Overall I hope the book will be out by the summer.

Show me the book please!

I am including chapters three and four. I welcome all feedback!

Last Thursday I attended the Cleveland Ruby Brigade meeting. It was nice to see a some old friends. I mentioned a few times that I had just started working with a team that was using C++. Each time the reaction was negative. People said things like “I’m sorry for you”. Actually, there is nothing to be sorry about. C++ is a strong language that has continued to evolve over the years and will have a place in software development for the foreseeable future.

The negative reaction to C++ encouraged me to create this screencast (my first ever). I had some time Monday morning before work so I turned on the recorder. I am using Google Test to drive the design. I hope you enjoy.