iu-test-factory 0.5.4.2

data/lib/test-factory/date_factory.rb

@@ -0,0 +1,158 @@
+# Copyright 2012-2014 The rSmart Group, Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#   http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Some date and time helper functions....
+module DateFactory
+
+  MONTHS = %w{JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC}
+
+  # Takes a time object and returns a hash containing
+  # various parts of the relevant date.
+  # @param time_object [Time] the moment you want to convert
+  # @returns [Hash] a hash object containing various parts of the date/time you passed to the method
+  #
+  def date_factory(time_object)
+    {
+      sakai:          make_date(time_object),
+      sakai_rounded:  make_date(time_object).gsub!(/:\d+/, ":#{Time.at(time_object.to_i/(5*60)*(5*60)).strftime("%M")}"), # Date with time rounded to nearest 5-minute mark.
+      short_date:     time_object.strftime("%b %-d, %Y"), # => "Oct 18, 2013"
+      samigo:         time_object.strftime("%m/%d/%Y %I:%M:%S %p"), # => "10/30/2012 07:02:05 AM"
+      MON:            time_object.strftime("%^b"), # => "DEC"
+      Mon:            time_object.strftime("%b"), # => "Jan"
+      Month:          time_object.strftime("%B"), # => "February"
+      month_int:      time_object.month, # => 3
+      day_of_month:   time_object.day, # => 17 Note this is not zero-padded
+      weekday:        time_object.strftime("%A"), # => "Monday"
+      wkdy:           time_object.strftime("%a"), # => "Tue"
+      year:           time_object.year, # => 2013
+      hour:           time_object.strftime("%I").to_i, # => "07" Zero-padded, 12-hour clock
+      minute:         time_object.strftime("%M"), # => "02" Zero-padded
+      minute_rounded: (Time.at(time_object.to_i/(5*60)*(5*60))).strftime("%M"), # => "05" Zero-padded, rounded to 5-minute increments
+      meridian:       time_object.strftime("%P"), # => "pm"
+      MERIDIAN:       time_object.strftime("%p"), # => "AM"
+      date_w_slashes: time_object.strftime("%m/%d/%Y"), # => 02/08/2013
+      custom:         time_object # => Allows creation of a custom date string using the passed time value.
+    }
+  end
+
+  def an_hour_ago
+    date_factory(Time.now - 3600)
+  end
+  alias last_hour an_hour_ago
+
+  def right_now
+    date_factory(Time.now)
+  end
+
+  def in_an_hour
+    date_factory(Time.now + 3600)
+  end
+  alias next_hour in_an_hour
+
+  def last_year
+    date_factory(Time.now - (3600*24*365))
+  end
+  alias a_year_ago last_year
+
+  # Returns a randomly selected date/time from
+  # within the last year.
+  def in_the_last_year
+    date_factory(Time.random(:year_range=>1))
+  end
+
+  def last_month
+    index = MONTHS.index(current_month)
+    return MONTHS[index-1]
+  end
+
+  def hours_ago(hours)
+    date_factory(Time.now - hours*3600)
+  end
+
+  def hours_from_now(hours)
+    date_factory(Time.now + hours*3600)
+  end
+
+  # Takes an integer representing
+  # the count of minutes as the parameter, and
+  # returns the date_factory hash for the
+  # resulting Time value.
+  #
+  def minutes_ago(mins)
+    date_factory(Time.now - mins*60)
+  end
+
+  def minutes_from_now(mins)
+    date_factory(Time.now + mins*60)
+  end
+
+  # Returns the current month as an
+  # upper-case 3-letter string.
+  # example: "JUL"
+  #
+  def current_month
+    Time.now.strftime("%^b")
+  end
+
+  def next_month
+    index = MONTHS.index(current_month)
+    if index < 11
+      return MONTHS[index+1]
+    else
+      return MONTHS[0]
+    end
+  end
+
+  def in_a_year
+    date_factory(Time.now + (3600*24*365))
+  end
+  alias next_year in_a_year
+
+  def yesterday
+    date_factory(Time.now - (3600*24))
+  end
+
+  def tomorrow
+    date_factory(Time.now + (3600*24))
+  end
+
+  def in_a_week
+    date_factory(Time.now + (3600*24*7))
+  end
+  alias next_week in_a_week
+
+  def a_week_ago
+    date_factory(Time.now - (3600*24*7))
+  end
+
+  def next_monday
+    date_factory(Time.at(Time.now+(8-Time.now.wday)*24*3600))
+  end
+
+  # Formats a date string Sakai-style.
+  # Useful for verifying creation dates and such.
+  #
+  # @param time_object [Time] the moment that you want converted to the string
+  # @returns [String] a date formatted to look like this: Jun 8, 2012 12:02 pm
+  #
+  def make_date(time_object)
+    month = time_object.strftime("%b ")
+    day = time_object.strftime("%-d")
+    year = time_object.strftime(", %Y ")
+    mins = time_object.strftime(":%M %P")
+    hour = time_object.strftime("%l").to_i
+    return month + day + year + hour.to_s + mins
+  end
+
+end

data/lib/test-factory/foundry.rb

@@ -0,0 +1,76 @@
+# Copyright 2012-2014 The rSmart Group, Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#   http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This module provides methods that instantiate the page and data classes.
+module Foundry
+
+  # Using the page_url defined in the provided page_class,
+  # this method will enter that url into the browser's address bar, then run the block of
+  # code that you specify.
+  # @param page_class [Class] the name of the page class that you want to instantiate
+  # @param &block [C] this is the block of code that you want to run while on the given page
+  #
+  def visit page_class, &block
+    on page_class, true, &block
+  end
+
+  # Instantiates the supplied page class, then runs the supplied block of code. Use this
+  # method when you are already on the site page you want to interact with.
+  # @param page_class [Class] the name of the page class that you want to instantiate
+  # @param visit [TrueClass, FalseClass] Essentially you will never have to specify this explicitly
+  # @param &block [C] this is the block of code that you want to run while on the given page
+  #
+  def on page_class, visit=false, &block
+    $current_page = page_class.new @browser, visit
+    block.call $current_page if block
+    $current_page
+  end
+  alias_method :on_page, :on
+
+  # Use this for making a data object in your test steps
+  #
+  # @param data_object_class [Class] The name of the class you want to use to build a data object for testing
+  # @param opts [Hash] The list of attributes you want to give to your data object
+  #
+  def make data_object_class, opts={}
+    data_object_class.new @browser, opts
+  end
+
+  # An extension of the #make method that simplifies and improves
+  # the readability of your "create" step definitions by
+  # combining the make with the create. Of course, this
+  # requires that your data object classes properly follow the design
+  # pattern and have a #create method available.
+  #
+  def create data_object_class, opts={}
+    data_object = make data_object_class, opts
+    data_object.create
+    data_object
+  end
+
+  # A helper method that takes a block of code and waits until it resolves to true.
+  # Useful when you need to wait for something to be on a page that's a little more
+  # involved than a simple element (for those, you should use the #expected_element
+  # method found in the PageFactory class)
+  # @param timeout [Fixnum] Defaults to 30 seconds
+  # @param message [String] The text thrown if the timeout is reached
+  #
+  # @example
+  #   page.wait_until { |b| b.processing_message=="Done" }
+  #
+  def wait_until(timeout=30, message=nil, &block)
+    Object::Watir::Wait.until(timeout: timeout, message: message, &block)
+  end
+
+end

data/lib/test-factory/gem_ext.rb

@@ -0,0 +1,211 @@
+# Copyright 2012-2014 The rSmart Group, Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#   http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# We are extending Watir's element methods here with the #fit method,
+# which can be used with text fields, select lists, radio buttons,
+# and checkboxes.
+#
+# The purpose of +#fit+ is to allow the creation, in your Data Object classes,
+# of a minimal number of +#edit+ methods (ideally only one) written as
+# concisely as possible.
+#
+# Without the +#fit+ method, you would either have to write separate edit
+# methods for every possible field you want to edit, or else your
+# edit method would have to contain lots of repetitive conditional code
+# to prevent making inadvertent updates to those fields that don't need it.
+#
+# Proper use of the +#fit+ method requires following a particular coding
+# pattern, however:
+#
+# * In your Page Classes, define your text field, select list, radio button, and
+#   checkbox elements directly. Do not define +#select+, +#set+ and/or +#clear+
+#   actions there.
+# * Your data object's instance variables for radio buttons and checkboxes, when
+#   not +nil+, should have the values of +:set+ or +:clear+. If they *need* to be
+#   something else, then define a Hash transform method to easily convert the
+#   custom values back to +:set+ or +:clear+, then pass that transform to the +#fit+ method.
+# * Always remember to end your +#edit+ methods with the +#set_options()+
+#   method (a.k.a. +#update_options+), from the DataFactory module. It
+#   automatically takes care of updating your data object's instance variables
+#   with any new values.
+#
+# ==Example
+#
+# Let's take a look at how the proper use of +#fit+ in your code can significantly
+# clean things up, using a checkbox field for our example. Remember that +#fit+
+# works with radio buttons, text fields, and select lists, too.
+#
+# First, here's some code written without using +#fit+, and using
+# actions for the checkbox page objects, and a Data Object
+# instance variable, +@option+, that is either "YES" or "NO"...
+#
+#   class MyPage < BasePage
+#     # ...
+#     action(:check_checkbox) { |b| b.checkbox(id: "checkbox").set }
+#     action(:clear_checkbox) { |b| b.checkbox(id: "checkbox").clear }
+#     # ...
+#   end
+#
+#   class DataObject
+#     # ...
+#     def edit opts={}
+#       # ...
+#       if opts[:option] != @option
+#         on MyPage do |page|
+#           if opts[:option] == "NO"
+#             page.clear_checkbox
+#           else
+#             page.check_checkbox
+#           end
+#         end
+#         @option = opts[:option]
+#       end
+#       # ...
+#     end
+#     # ...
+#   end
+#
+# That's just nasty! Your Page Class has two element definitions that are nearly identical.
+# And the nested conditional in the Data Object's #edit method hurts the eyes!
+#
+# Now, let's take that same code, but this time use the +#fit+ method. We'll assume that
+# the data object's +@option+ instance variable will be +:set+, +:clear+, or +nil+, and
+# end the +#edit+ with the DataFactory's +#set_options+ helper method...
+#
+#   class MyPage < BasePage
+#     # ...
+#     element(:checkbox) { |b| b.checkbox(id: "checkbox") }
+#     # ...
+#   end
+#
+#   class DataObject
+#     # ...
+#     def edit opts={}
+#       # ...
+#       on MyPage do |page|
+#         # ...
+#         page.checkbox.fit opts[:option]
+#         # ...
+#       end
+#       # ...
+#       update_options opts
+#     end
+#     # ...
+#   end
+#
+# Much cleaner!
+#
+# The +#fit+ method is designed to allow for other values than just +:set+ or +:clear+. It will support
+# 'Yes', 'No', 'on', 'off' (and it's case insensitive), +true+, and +false+, as well. This way you don't have to worry so much
+# about making methods that transform from one type to another.
+#
+module Watir
+
+  class CheckBox
+    def fit(arg)
+      setting = TestFactory.binary_transform(arg)
+      self.send(setting) unless setting==nil
+    end
+  end
+
+  class Radio
+    def fit(arg)
+      setting = TestFactory.binary_transform(arg)
+      self.set if setting==:set
+    end
+  end
+
+  module UserEditable
+
+    # Extends Watir's methods.
+    # Use when the argument you are passing to a text field
+    # may be nil, in which case you don't
+    # want to do anything with the page element.
+    #
+    def fit(args)
+      unless args==nil
+        assert_exists
+        assert_writable
+
+        @element.clear
+        @element.send_keys(args)
+      end
+    end
+  end
+
+  class Select
+
+    # Extends Watir's methods.
+    # Use when the argument you are passing to a text field
+    # may be nil, in which case you don't
+    # want to do anything with the page element.
+    # @example
+    #   page.select_list.fit @my_selection
+    #
+    def fit(str_or_rx)
+      select_by :text, str_or_rx unless str_or_rx==nil
+    end
+
+    # Allows you to select a specific item in a
+    # select list, or, if desired, it will pick an item from
+    # the list at random.
+    #
+    # If you pass this method the string '::random::' then
+    # it will select an item at random from the select
+    # list and, assuming what you passed it was a class instance
+    # variable, it will be updated to contain the
+    # selected value (hence the ! in the method name).
+    # Note that this method will be slow with large selection lists.
+    #
+    # @example
+    #   @my_selection='::random::'
+    #   page.select_list.pick! @my_selection
+    #   puts @my_selection # => <Value of randomly selected item from list>
+    #
+    def pick!(item)
+      if item=='::random::'
+        item.replace(select_at_random)
+      else
+        fit item
+      end
+    end
+
+    # Same as #pick!, except it does not change the
+    # value of 'item'
+    #
+    def pick(item)
+      if item=='::random::'
+        select_at_random
+      else
+        fit item
+      end
+    end
+
+    private
+
+    def select_at_random
+      ar = options.map(&:text)
+      # Must break out of this method if the select list has nothing to select...
+      return '::random::' if ar.size==1 && (ar[0]=~/^select(.?)$/i || ar[0]=='')
+      sel = ar.sample
+      while sel=~/^select(.?)$/i || sel==''
+        sel = ar.sample
+      end
+      select sel
+      sel
+    end
+
+  end
+
+end

data/lib/test-factory/page_factory.rb

@@ -0,0 +1,219 @@
+# Copyright 2012-2014 The rSmart Group, Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#   http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The PageFactory class provides a set of methods that allow the rapid creation of page element definitions--known
+# colloquially as "page objects". These elements are defined using Watir syntax. Please see www.watir.com if you are
+# not familiar with Watir.
+#
+class PageFactory
+
+  # As the PageFactory will be the superclass for all your page classes, having this initialize
+  # method here means it's only written once.
+  #
+  def initialize browser, visit = false
+    @browser = browser
+    goto if visit
+    expected_element if respond_to? :expected_element
+    has_expected_title? if respond_to? :has_expected_title?
+  end
+
+  # Catches any "missing" methods and passes them to the browser object--which means
+  # that Watir will take care of parsing them, so the assumption is that the method being
+  # passed is a valid method for the browser object.
+  #
+  def method_missing sym, *args, &block
+    @browser.send sym, *args, &block
+  end
+
+  class << self
+
+    # Define this in a page class and when you use the "visit" method to instantiate the class
+    # it will enter the URL in the browser's address bar.
+    #
+    def page_url url
+      define_method 'goto' do
+        @browser.goto url
+      end
+    end
+
+    # Define this in a page class and when that class is instantiated it will wait until that
+    # element appears on the page before continuing with the script.
+    # @param element_name [Symbol] The method name of the element that must be present on the page
+    #
+    def expected_element element_name, timeout=30
+      define_method 'expected_element' do
+        self.send(element_name).wait_until_present timeout: timeout
+      end
+    end
+
+    # Define this in a page class and when the class is instantiated it will verify that
+    # the browser's title matches the expected title. If there isn't a match, it raises an
+    # error and halts the script.
+    # @param expected_title [String] The exact text that is expected to appear in the Browser title when the page loads
+    #
+    def expected_title expected_title
+      define_method 'has_expected_title?' do
+        has_expected_title = expected_title.kind_of?(Regexp) ? expected_title =~ @browser.title : expected_title == @browser.title
+        raise "Expected title '#{expected_title}' instead of '#{@browser.title}'" unless has_expected_title
+      end
+    end
+
+    # The basic building block for defining and interacting with
+    # elements on a web page. # Use in conjunction with
+    # Watir to define all elements on a given page that are important to validate.
+    #
+    # Methods that take one or more parameters can be built with this as well.
+    #
+    # @example
+    #   element(:title) { |b| b.text_field(:id=>"title-id") }
+    #   value(:page_header) { |b| b.h3(:class=>"page_header").text }
+    #   action(:continue) { |b| b.frm.button(:value=>"Continue").click } => Creates a #continue method that clicks the Continue button
+    #   p_element(:select_style) { |stylename, b| b.div(:text=>/#{Regexp.escape(stylename)}/).link(:text=>"Select").click } => #select_style(stylename)
+    #
+    def element name, &block
+      raise "#{name} is being defined twice in #{self}!" if self.instance_methods.include?(name.to_sym)
+      define_method name.to_s do |*thing|
+        Proc.new(&block).call *thing, self
+      end
+    end
+    alias_method :action, :element
+    alias_method :value, :element
+    alias_method :p_element, :element
+    alias_method :p_action, :element
+    alias_method :p_value, :element
+
+    # Use this for links that are safe to define by their text string.
+    # This method will return two methods for interacting with the link:
+    # one that refers to the link itself, and one that clicks on it.
+    # Since it's assumed that the most common thing done with a link is to click it,
+    # the method for clicking it will be named according to the text of the link,
+    # and the method for the link itself will have "_link" appended to it. Any special
+    # characters are stripped from the string. Capital letters are made lower case.
+    # And spaces and dashes are converted to underscores.
+    #
+    # @example
+    #   link("Click Me For Fun!") => Creates the methods #click_me_for_fun and #click_me_for_fun_link
+    #
+    # The last parameter in the method is optional. Use it when
+    # you need the method name to be different from the text of
+    # the link--for example if the link text is something unhelpful,
+    # like "here", or else the link text gets updated (e.g., what was
+    # "Log In" is now "Sign In", instead) and you don't
+    # want to have to go through all your data objects and step
+    # definitions to update them to the new method name.
+    #
+    # @example
+    #   link("Click Me For Fun!", :click_me) => Creates the methods #click_me and #click_me_link
+    #
+    def link link_text, *alias_name
+      elementize(:link, link_text, *alias_name)
+    end
+
+    # Use this for buttons that are safe to define by their value attribute.
+    # This method will return two methods for interacting with the button:
+    # one that refers to the button itself, and one that clicks on it.
+    # Since it's assumed that the most common thing done with a button is to click it,
+    # the method for clicking it will be named according to the value of the button,
+    # and the method for the button itself will have "_button" appended to it. Any special
+    # characters are stripped from the string. Capital letters are made lower case.
+    # And spaces and dashes are converted to underscores.
+    # @param button_text [String] The contents of the button's value tag in the HTML
+    #
+    # @example
+    #   button("Click Me For Fun!") => Creates the methods #click_me_for_fun and #click_me_for_fun_button
+    #
+    # The last parameter in the method is optional. Use it when
+    # you need the method name to be different from the text of
+    # the button--for example if the button text is unhelpful, like "Go", or else
+    # it changes (e.g., from "Update" to "Edit") and you don't
+    # want to have to go through all your data objects and step
+    # definitions to update them to the new method name.
+    #
+    # @example
+    #   link("Click Me For Fun!", :click_me) => Creates the methods #click_me and #click_me_link
+    #
+    def button button_text, *alias_name
+      elementize(:button, button_text, *alias_name)
+    end
+
+    # TestFactory doesn't allow defining a method in a child class
+    # with the same name as one already defined in a parent class.
+    # The thinking here is: "Out of sight, out of mind." Meaning:
+    # you or a team mate might not know or have forgotten that a given
+    # element is already defined in a parent class, and so define it
+    # again. TestFactory's restriction is there to help prevent this.
+    #
+    # However, in some cases you may have a child page class with a
+    # special circumstance, where the parent class's version of the
+    # method really doesn't apply, and you want to use the same method
+    # name in this child class because, really, no other method name
+    # would fit quite as well.
+    #
+    # The #undefine method is for those rare cases. Note: If you start
+    # using this method a lot then you should consider that a sign
+    # that perhaps you're putting too many method definitions into
+    # parent page classes.
+    #
+    # @example
+    #   undefine :status, :doc_id => Undefines the specified methods in the current class
+    #
+    def undefine *methods
+      methods.each{ |m| undef_method m }
+    end
+
+    def inherited klass
+      klass.instance_eval {
+
+        # Creates a method, #wait_for_ajax, usable in your Page Classes, that executes
+        # the 'jQuery.active' Javascript snippet each second until timeout.
+        #
+        # If timeout is exceeded, raises Watir::Wait::TimeoutError exception. The returned error
+        # message is customizable.
+        #
+        define_method 'wait_for_ajax' do |timeout=10, message|
+          timeout.times do
+            sleep 0.3
+            return true if @browser.execute_script('return jQuery.active').to_i == 0
+            sleep 0.7
+          end
+          raise Watir::Wait::TimeoutError, "Ajax calls continued beyond #{timeout} seconds. #{message}"
+        end
+
+      }
+    end
+
+    private
+    # A helper method that converts the passed string into snake case. See the StringFactory
+    # module for more info.
+    #
+    def damballa text
+      StringFactory.damballa(text)
+    end
+
+    def elementize type, text, *alias_name
+      hash={:link=>:text, :button=>:value}
+      if alias_name.empty?
+        el_name=damballa("#{text}_#{type}")
+        act_name=damballa(text)
+      else
+        el_name="#{alias_name[0]}_#{type}".to_sym
+        act_name=alias_name[0]
+      end
+      element(el_name) { |b| b.send(type, hash[type]=>text) }
+      action(act_name) { |b| b.send(type, hash[type]=>text).click }
+    end
+
+  end
+
+end # PageFactory