page-object 0.0.3 → 0.0.4

data/features/support/page.rb

@@ -11,6 +11,26 @@ class Page
   text_field(:text_field_text, :text => "")
   text_field(:text_field_value, :value => "")
 
+  text_area(:text_area_id, :id => "text_area_id")
+  text_area(:text_area_class, :class => "text_area_class")
+  text_area(:text_area_name, :name => "text_area_name")
+  text_area(:text_area_xpath, :xpath => "//textarea")
+  text_area(:text_area_css, :css => "textarea")
+  text_area(:text_area_tag_name, :tag_name => "textarea")
+  text_area(:text_area_index, :index => 0)
+  text_area(:text_area_text, :text => "")
+  text_area(:text_area_value, :value => "")
+
+  hidden_field(:hidden_field_id, :id => "hidden_field_id")
+  hidden_field(:hidden_field_class, :class => "hidden_field_class")
+  hidden_field(:hidden_field_name, :name => "hidden_field_name")
+  hidden_field(:hidden_field_xpath, :xpath => "//input[@type='hidden']")
+  hidden_field(:hidden_field_css, :css => "input[type='hidden']")
+  hidden_field(:hidden_field_tag_name, :tag_name => "input[type='hidden']")
+  hidden_field(:hidden_field_index, :index => 0)
+  hidden_field(:hidden_field_text, :text => "")
+  hidden_field(:hidden_field_value, :value => "")
+
   link(:google_search_id, :id => "link_id")
   link(:google_search_name, :name => "link_name")
   link(:google_search_class, :class => "link_class")
@@ -80,4 +100,27 @@ class Page
   image(:image_index, :index => 0)
   image(:image_xpath, :xpath => '//img')
 
+  form(:form_id, :id => 'form_id')
+  form(:form_name, :id => 'form_name')
+  form(:form_class, :class => 'form_class')
+  form(:form_index, :index => 0)
+  form(:form_xpath, :xpath => '//form')
+  
+  list_item(:li_id, :id => 'li_id')
+  list_item(:li_name, :name => 'li_name')
+  list_item(:li_class, :class => 'li_class')
+  list_item(:li_index, :index => 0)
+  list_item(:li_xpath, :xpath => '//li[1]')
+  
+  unordered_list(:ul_id, :id => 'ul_id')
+  unordered_list(:ul_name, :name => 'ul_name')
+  unordered_list(:ul_class, :class => 'ul_class')
+  unordered_list(:ul_index, :index => 0)
+  unordered_list(:ul_xpath, :xpath => '//ul')
+
+  ordered_list(:ol_id, :id => 'ol_id')
+  ordered_list(:ol_name, :name => 'ol_name')
+  ordered_list(:ol_class, :class => 'ol_class')
+  ordered_list(:ol_index, :index => 0)
+  ordered_list(:ol_xpath, :xpath => '//ol')
 end

data/features/text_area.feature

@@ -0,0 +1,32 @@
+Feature: Text Area
+
+  
+  Background:
+    Given I am on the static elements page
+  
+  Scenario: Setting and getting a value from a text area
+    When I type "abcdefghijklmnop" into the text area
+    Then the text area should contain "abcdefghijklmnop"
+
+  Scenario Outline: Locating text area on the Page
+    When I search for the text area by "<search_by>"
+    Then I should be able to type "I found it" into the area
+
+  Scenarios:
+    | search_by |
+    | id        |
+    | class     |
+    | name      |
+    | xpath     |  
+    | css       |
+    | tag_name  |
+
+  @watir_only
+  Scenario Outline: Locating text fields on Watir only
+    When I search for the text area by "<search_by>"
+    Then I should be able to type "I found it" into the area
+
+  Scenarios:
+    | search_by |
+    | index     |
+

data/features/text_field.feature

@@ -26,12 +26,11 @@ Feature: Text Fields
   @watir_only
   Scenario Outline: Locating text fields on Watir only
     When I search for the text field by "<search_by>"
+    Then I should be able to type "I found it" into the field
 
   Scenarios:
     | search_by |
     | index     |
-    | text      |
-    | value     |
 
   Scenario: Retrieve a text field
     When I retrieve a text field

data/features/unordered_list.feature

@@ -0,0 +1,39 @@
+Feature: Unordered list
+
+  Background:
+    Given I am on the static elements page
+  
+  Scenario: Getting the first element from the unordered list
+    When I get the first item from the unordered list
+    Then the list item's text should be "Item One"
+
+  Scenario Outline: Locating unordered lists on the page
+    When I search for the unordered list by "<search_by>"
+    And I get the first item from the list
+    Then the list item's text should be "Item One"
+  
+  Scenarios:
+    | search_by |
+    | id        |
+    | class     |
+    | xpath     |  
+
+  @watir_only
+  Scenario Outline: Locating unordered lists in Watir only
+    When I search for the unordered list by "<search_by>"
+    And I get the first item from the list
+    Then the list item's text should be "Item One"
+
+  Scenarios:
+    | search_by |
+    | index     |
+
+  @selenium_only
+  Scenario Outline: Locating unordered lists in Selenium only
+    When I search for the unordered list by "<search_by>"
+    And I get the first item from the list
+    Then the list item's text should be "Item One"
+
+  Scenarios:
+    | search_by |
+    | name      |

data/lib/page-object.rb

@@ -2,36 +2,81 @@
 require 'page-object/version'
 require 'page-object/accessors'
 
-# Module that when included adds core functionality to a page object.
+#
+# Module that when included adds functionality to a page object.  This module
+# will add numerous class and instance methods that you use to define and
+# interact with web pages.
+#
+# If we have a login page with a username and password textfield and a login
+# button we might define our page like the one below.  We can then interact with
+# the object using the generated methods.
+#
+# @example Login page example 
+#   class LoginPage
+#     include PageObject
+#
+#     text_field(:username, :id => 'user')
+#     text_field(:password, :id => 'pass')
+#     button(:login, :value => 'Login')
+#   end
+#
+#   ...
+#
+#   browser = Watir::Browser.new :firefox
+#   login_page = LoginPage.new(browser)
+#   login_page.username = 'cheezy'
+#   login_page.password = 'secret'
+#   login_page.login
+#
+# @see PageObject::Accessors to see what class level methods are added to this module at runtime.
+#
 module PageObject
+  # @return [Watir::Browser or Selenium::WebDriver::Driver] the platform browser passed to the constructor
+  attr_reader :browser
+  # @return [PageObject::WatirPageObject or PageObject::SeleniumPageObject] the platform page object
   attr_reader :platform
 
-  # Construct a new page object.  The browser parameter must be either a
-  # Watir::Browser or Selenium::WebDriver::Driver.
+  #
+  # Construct a new page object.
+  #
+  # @param [Watir::Browser or Selenium::WebDriver::Driver] the platform browser to use
+  #
   def initialize(browser)
+    @browser = browser
     include_platform_driver(browser)
   end
 
+  # @private
   def self.included(cls)
     cls.extend PageObject::Accessors
   end
   
+  #
   # navigate to the provided url
+  #
+  # @param [String] the full url to navigate to
+  #
   def navigate_to(url)
     platform.navigate_to(url)
   end
   
+  #
   # Returns the text of the current page
+  #
   def text
     platform.text
   end
 
+  #
   # Returns the html of the current page
+  #
   def html
     platform.html
   end
 
+  #
   # Returns the title of the current page
+  #
   def title
     platform.title
   end

data/lib/page-object/accessors.rb

@@ -1,30 +1,34 @@
 
-#
-# Contains the class level methods that are inserted into your page objects
-# when you include the PageObject module.  These methods will generate another
-# set of methods that provide access to the elements on the web pages.
-#
 module PageObject
+  #
+  # Contains the class level methods that are inserted into your page objects
+  # when you include the PageObject module.  These methods will generate another
+  # set of methods that provide access to the elements on the web pages.
+  #
+  # @see PageObject::WatirPageObject for the watir implementation of the platform delegate
+  # @see PageObject::SeleniumPageObject for the selenium implementation of the platform delegate
+  #
   module Accessors
     #
     # adds three methods to the page object - one to set text in a text field,
     # another to retrieve text from a text field and another to return the text
     # field element.
     #
-    # Example:  text_field(:first_name, {:id => "first_name"})
-    # will generate the 'first_name', 'first_name=' and 'first_name_text_field methods.
-    #
-    # @param  the name used for the generated methods
-    # @param identifier how we find a text_field.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :css => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Watir and Selenium
-    #   :tag_name => Watir and Selenium
-    #   :text => Watir only
-    #   :value => Watir only
-    #   :xpath => Watir and Selenium
+    # @example  
+    #   text_field(:first_name, :id => "first_name") 
+    #   # will generate 'first_name', 'first_name=' and 'first_name_text_field' methods
+    #
+    # @param  [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a text_field.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :css => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :tag_name => Watir and Selenium
+    #   * :text => Watir only
+    #   * :value => Watir only
+    #   * :xpath => Watir and Selenium
     #
     def text_field(name, identifier)
       define_method(name) do
@@ -37,24 +41,84 @@ module PageObject
         platform.text_field_for identifier
       end
     end
+    
+    #
+    # adds two methods to the page object - one to get the text from a hidden field
+    # and another to retrieve the hidden field element.
+    #
+    # @example
+    #   hidden_field(:user_id, :id => "user_identity")
+    #   # will generate 'user_id' and 'user_id_hidden_field' methods
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a hidden field.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :css => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :tag_name => Watir and Selenium
+    #   * :text => Watir only
+    #   * :xpath => Watir and Selenium
+    #
+    def hidden_field(name, identifier)
+      define_method(name) do
+        platform.hidden_field_value_for identifier
+      end
+      define_method("#{name}_hidden_field") do
+        platform.hidden_field_for identifier
+      end
+    end
+    
+    #
+    # adds three methods to the page object - one to set text in a text area,
+    # another to retrieve text from a text area and another to return the text
+    # area element.
+    #
+    # @example
+    #   text_area(:address, :id => "address")
+    #   # will generate 'address', 'address=' and 'address_text_area methods
+    #
+    # @param  [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a text area.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :css => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :tag_name => Watir and Selenium
+    #   * :xpath => Watir and Selenium
+    #
+    def text_area(name, identifier)
+      define_method(name) do
+        platform.text_area_value_for identifier
+      end
+      define_method("#{name}=") do |value|
+        platform.text_area_value_set(identifier, value)
+      end
+      define_method("#{name}_text_area") do
+        platform.text_area_for identifier
+      end
+    end
 
     #
     # adds three methods - one to select an item in a drop-down,
     # another to fetch the currently selected item and another
     # to retrieve the select list element.
     #
-    # Example:  select_list(:state, {:id => "state"})
-    # will generate the 'state', 'state=' and 'state_select_list' methods
+    # @example
+    #   select_list(:state, :id => "state")
+    #   # will generate 'state', 'state=' and 'state_select_list' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a select_list.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Watir and Selenium
-    #   :text => Watir only
-    #   :value => Watir only
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a select_list.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :text => Watir only
+    #   * :value => Watir only
+    #   * :xpath => Watir and Selenium
     #
     def select_list(name, identifier)
       define_method(name) do
@@ -73,21 +137,21 @@ module PageObject
     # to return a PageObject::Elements::Link object representing
     # the link.
     #
-    # Example:  link(:add_to_cart, {:text => "Add to Cart"})
-    # will generate the 'add_to_cart' and 'add_to_cart_link'
-    # method.
-    #
-    # @param the name used for the generated methods
-    # @param identifier how we find a link.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :href => Watir only
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :link => Watir and Selenium
-    #   :link_text => Watir and Selenium
-    #   :name => Watir and Selenium
-    #   :text => Watir and Selenium
-    #   :xpath => Watir and Selenium
+    # @example
+    #   link(:add_to_cart, :text => "Add to Cart")
+    #   # will generate 'add_to_cart' and 'add_to_cart_link' methods
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a link.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :href => Watir only
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :link => Watir and Selenium
+    #   * :link_text => Watir and Selenium
+    #   * :name => Watir and Selenium
+    #   * :text => Watir and Selenium
+    #   * :xpath => Watir and Selenium
     #
     def link(name, identifier)
       define_method(name) do
@@ -103,17 +167,17 @@ module PageObject
     # to return the state of a checkbox, and a final method to return
     # a PageObject::Elements::CheckBox object representing the checkbox.
     #
-    # Example: checkbox(:active, {:name => "is_active"})
-    # will generate the 'check_active', 'uncheck_active',
-    # 'active_checked?' and 'active_checkbox' methods.
+    # @example
+    #   checkbox(:active, :name => "is_active")
+    #   # will generate 'check_active', 'uncheck_active', 'active_checked?' and 'active_checkbox' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a checkbox.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Watir and Selenium
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a checkbox.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :xpath => Watir and Selenium
     #
     def checkbox(name, identifier)
       define_method("check_#{name}") do
@@ -136,17 +200,17 @@ module PageObject
     # another method to return a PageObject::Elements::RadioButton
     # object representing the radio button element
     #
-    # Example:  radio_button(:north, {:id => "north"})
-    # will generate 'select_north', 'clear_north',
-    # 'north_selected?' and 'north_radio_button' methods
+    # @example
+    #   radio_button(:north, :id => "north")
+    #   # will generate 'select_north', 'clear_north', 'north_selected?' and 'north_radio_button' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a checkbox.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Watir and Selenium
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a radio button.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :xpath => Watir and Selenium
     #
     def radio_button(name, identifier)
       define_method("select_#{name}") do
@@ -167,17 +231,18 @@ module PageObject
     # adds two methods - one to click a button and another to
     # return the button element.
     #
-    # Example: button(:purchase, :id => 'purchase')
-    # will generate a 'purchase' and 'purchase_button' methods.
+    # @example
+    #   button(:purchase, :id => 'purchase')
+    #   # will generate 'purchase' and 'purchase_button' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a checkbox.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Watir and Selenium
-    #   :text => Watir only
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a button.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :text => Watir only
+    #   * :xpath => Watir and Selenium
     #
     def button(name, identifier)
       define_method(name) do
@@ -192,16 +257,17 @@ module PageObject
     # adds two methods - one to retrieve the text from a div
     # and another to return the div element
     #
-    # Example:  div(:message, {:id => 'message'})
-    # will generate a 'message' and 'message_div' methods
+    # @example
+    #   div(:message, :id => 'message')
+    #   # will generate 'message' and 'message_div' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a div.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Selenium only
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a div.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
     #
     def div(name, identifier) 
       define_method(name) do
@@ -216,16 +282,17 @@ module PageObject
     # adds two methods - one to retrieve the text from a span
     # and another to return the span element
     #
-    # Example:  span(:alert, {:id => 'alert'})
-    # will generate a 'alert' and 'alert_div' methods
+    # @example
+    #   span(:alert, :id => 'alert')
+    #   # will generate 'alert' and 'alert_span' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a span.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Selenium only
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a span.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
     #
     def span(name, identifier)
       define_method(name) do
@@ -239,16 +306,17 @@ module PageObject
     #
     # adds a method to retrieve the table element
     #
-    # Example: table(:cart, :id => 'shopping_cart')
-    # will generate a 'cart_table' method.
+    # @example
+    #   table(:cart, :id => 'shopping_cart')
+    #   # will generate a 'cart_table' method
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a checkbox.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Selenium only
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a table.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
     #
     def table(name, identifier)
       define_method("#{name}_table") do
@@ -260,16 +328,17 @@ module PageObject
     # adds two methods  one to retrieve the text from a table cell
     # and another to return the table cell element
     #
-    # Example: cell(:total, :id => 'total_cell')
-    # will generate a 'total' and 'total_cell' methods
+    # @example
+    #   cell(:total, :id => 'total_cell')
+    #   # will generate 'total' and 'total_cell' methods
     #
-    # @param the name used for the generated methods
-    # @param identifier how we find a checkbox.  The valid values are:
-    #   :class => Watir and Selenium
-    #   :id => Watir and Selenium
-    #   :index => Watir only
-    #   :name => Selenium only
-    #   :xpath => Watir and Selenium
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a cell.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
     #
     def cell(name, identifier)
       define_method("#{name}") do
@@ -280,10 +349,112 @@ module PageObject
       end
     end
     
+    #
+    # adds a method to retrieve the image element
+    #
+    # @example
+    #   image(:logo, :id => 'logo')
+    #   # will generate a 'logo_image' method
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find an image.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Watir and Selenium
+    #   * :xpath => Watir and Selenium
+    #
     def image(name, identifier)
       define_method("#{name}_image") do
         platform.image_for identifier
       end
     end
+    
+    #
+    # adds a method to retrieve the form element
+    #
+    # @example
+    #   form(:login, :id => 'login')
+    #   # will generate a 'login_form' method
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a form.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :xpath => Watir and Selenium
+    #
+    def form(name, identifier)
+      define_method("#{name}_form") do
+        platform.form_for identifier
+      end
+    end
+    
+    #
+    # adds two methods - one to retrieve the text from a list item
+    # and another to return the list item element
+    #
+    # @example
+    #   list_item(:item_one, :id => 'one')
+    #   # will generate 'item_one' and 'item_one_list_item' methods
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find a list item.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
+    #
+    def list_item(name, identifier)
+      define_method(name) do
+        platform.list_item_text_for identifier
+      end
+      define_method("#{name}_list_item") do
+        platform.list_item_for identifier
+      end
+    end
+    
+    #
+    # adds a method to retrieve the unordered list element
+    #
+    # @example
+    #   unordered_list(:menu, :id => 'main_menu')
+    #   # will generate a 'menu_unordered_list' method
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find an unordered list.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
+    #
+    def unordered_list(name, identifier)
+      define_method("#{name}_unordered_list") do
+        platform.unordered_list_for identifier
+      end
+    end
+    
+    #
+    # adds a method to retrieve the ordered list element
+    #
+    # @example
+    #   ordered_list(:top_five, :id => 'top')
+    #   # will generate a 'top_five_ordered_list' method
+    #
+    # @param [String] the name used for the generated methods
+    # @param [Hash] identifier how we find an unordered list.  The valid keys are:
+    #   * :class => Watir and Selenium
+    #   * :id => Watir and Selenium
+    #   * :index => Watir only
+    #   * :name => Selenium only
+    #   * :xpath => Watir and Selenium
+    #
+    def ordered_list(name, identifier)
+      define_method("#{name}_ordered_list") do
+        platform.ordered_list_for identifier
+      end
+    end
   end
 end