bret-watircraft 0.4.0

data/lib/extensions/object.rb

@@ -0,0 +1,24 @@
+# instance_exec comes with >1.8.7 thankfully
+if VERSION <= '1.8.6'
+  class Object
+    module InstanceExecHelper; end
+    include InstanceExecHelper
+    # instance_exec method evaluates a block of code relative to the specified object, with parameters whom come from outside the object.
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        n += 1 while respond_to?(mname="__instance_exec#{n}")
+        InstanceExecHelper.module_eval{ define_method(mname, &block) }
+      ensure
+        Thread.critical = old_critical
+      end
+      begin
+        ret = send(mname, *args)
+      ensure
+        InstanceExecHelper.module_eval{ remove_method(mname) } rescue nil
+      end
+      ret
+    end
+  end
+end

data/lib/extensions/string.rb

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'activesupport'
+
+class String
+  # pluralizes a string and turns it into a symbol
+  # Example:
+  #  "apple".pluralize_to_sym    # => :apples
+  def pluralize_to_sym
+    self.pluralize.to_sym
+  end
+  # Opposite of humanize. Converts to lower case and converts spaces to underscores. 
+  # Example:
+  #   "Add Book".computerize # => "add_book"
+  def computerize
+    self.underscore.downcase.gsub ' ', '_'
+  end
+end

data/lib/extensions/watir.rb

@@ -0,0 +1,41 @@
+# TODO: support radiogroup
+# TODO: migrate this code into Watir
+# TODO: also handle FireWatir classes
+module Watir
+  class TextField # includes Hidden
+    def display_value
+      value
+    end
+  end
+  class FileField
+    def display_value
+      value
+    end
+  end
+  class CheckBox
+    # returns a boolean
+    def display_value
+      checked?
+    end
+  end
+  class SelectList
+    # Note: currently works for single-select only    
+    def display_value
+      getSelectedItems[0]
+    end
+  end
+  class Button
+    def display_value
+      value
+    end
+  end
+  class Element
+    def display_value
+      text
+    end
+  end
+
+  class B < NonControlElement
+    TAG = 'B'
+  end
+end

data/lib/taza/browser.rb

@@ -0,0 +1,45 @@
+module Taza
+  class Browser
+    
+    # Create a browser instance depending on configuration.  Configuration should be read in via Taza::Settings.config.
+    # 
+    # Example:
+    #     browser = Taza::Browser.create(Taza::Settings.config)
+    #
+    def self.create(params={})
+      self.send("create_#{params[:driver]}".to_sym,params)
+    end
+
+    private    
+
+    def self.create_watir(params)
+      require 'watir'
+      if params[:browser] == :ie
+        require 'watir/ie'
+        require 'extensions/watir'
+      end
+      Watir::Browser.default = params[:browser].to_s
+      Watir::Browser.new
+    end
+
+    def self.create_selenium(params)
+      require 'selenium'
+      Selenium::SeleniumDriver.new(params[:server_ip],params[:server_port],'*' + params[:browser].to_s,params[:timeout])
+    end
+    
+    def self.create_fake(params)
+      FakeBrowser.new
+    end
+
+  end
+
+  class FakeBrowser
+    def goto(*args)
+    end
+    def close
+    end
+    
+  end
+  
+end
+

data/lib/taza/entity.rb

@@ -0,0 +1,34 @@
+module Taza
+  class Entity
+    #Creates a entity, pass in a hash to be methodized and the fixture to look up other fixtures (not entirely happy with this abstraction)
+    def initialize(hash,fixture)
+      @hash = hash
+      @fixture = fixture
+      define_methods_for_hash_keys
+    end
+    
+    #This method converts hash keys into methods onto the entity
+    def define_methods_for_hash_keys
+      @hash.keys.each do |key|
+        create_method(key) do
+          get_value_for_entry(key)
+        end
+      end
+    end
+
+    #This method will lookup another fixture if a pluralized fixture exists otherwise return the value in the hash
+    def get_value_for_entry(key) # :nodoc:
+      if @fixture.pluralized_fixture_exists?(key)
+        @fixture.get_fixture_entity(key.pluralize_to_sym,@hash[key])
+      else
+        @hash[key]
+      end
+    end
+
+    private
+    def create_method(name, &block) # :nodoc:
+      self.class.send(:define_method, name, &block)
+    end
+
+  end
+end

data/lib/taza/fixture.rb

@@ -0,0 +1,66 @@
+module Taza
+  class Fixture # :nodoc:
+
+    def initialize # :nodoc:
+      @fixtures = {}
+    end
+
+    def load_all # :nodoc:
+      Dir.glob(fixtures_pattern) do |file|
+        entitized_fixture = {}
+        YAML.load_file(file).each do |key, value|
+          entitized_fixture[key] = value.convert_hash_keys_to_methods(self)
+        end
+        @fixtures[File.basename(file,'.yml').to_sym] = entitized_fixture
+      end
+    end
+    
+    def fixture_names # :nodoc:
+      @fixtures.keys
+    end
+    
+    def get_fixture_entity(fixture_file_key,entity_key) # :nodoc:
+      @fixtures[fixture_file_key][entity_key]
+    end
+
+    def pluralized_fixture_exists?(singularized_fixture_name) # :nodoc:
+      fixture_names.include?(singularized_fixture_name.pluralize_to_sym)
+    end
+
+    def fixtures_pattern # :nodoc:
+      File.join(base_path, 'fixtures','*.yml')
+    end
+
+    def base_path # :nodoc:
+      File.join('.','spec')
+    end
+  end
+  
+  # The module that will mixin methods based on the fixture files in your 'spec/fixtures'
+  # 
+  # Example:
+  #   describe "something" do
+  #     it "should test something" do
+  #       users(:jane_smith).first_name.should eql("jane")
+  #     end
+  #   end
+  # 
+  #  where there is a spec/fixtures/users.yml file containing a entry of:
+  # jane_smith:
+  #   first_name: jane
+  #   last_name: smith
+  module Fixtures
+    def Fixtures.included(other_module) # :nodoc:
+      fixture = Fixture.new
+      fixture.load_all
+      fixture.fixture_names.each do |fixture_name|
+        self.class_eval do
+          define_method(fixture_name) do |entity_key|
+            fixture.get_fixture_entity(fixture_name,entity_key.to_s)
+          end
+        end
+      end
+    end
+  end
+
+end

data/lib/taza/flow.rb

@@ -0,0 +1,40 @@
+module Taza
+  # Flows provide a way to write and manage common actions on a site.
+  # For instance, on an e-commerce site you may have multiple tests where a user is supposed to create a 
+  # new account and add a product to the shopping bag. In this case you could have two flows. create_an_account 
+  # and add_product_to_bag.
+  #
+  # Here's how you would get this started where your site is called Widgets of the Future:
+  #   $ ./script/generate flow create_an_account widgets_of_the_future
+  #   $ ./script/generate flow add_product_to_bag widgets_of_the_future
+  #
+  #   This will generate flows for you in lib/sites/widgets_of_the_future/flows/
+  #
+  #   From here you can create the logic needed to perform these flows without ever referencing a browser object:
+  #
+  #   module WidgetsOfTheFuture
+  #     class WidgetsOfTheFuture < Taza::Site
+  #       def create_an_account_flow(params={})
+  #         home_page.create_an_account_link.click
+  #         create_an_account_page do |cap|
+  #           cap.email.set params[:email]
+  #           cap.password.set params[:password]
+  #           cap.submit.click
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #
+  #   Then inside a spec or test you could run this flow like:
+  #
+  #   describe "Widgets of the Future" do
+  #     it "should do widgety things so that we can make more monies" do
+  #       WidgetsOfTheFuture.new do |w|
+  #         w.create_an_account_flow :email => "i.am@the.widget.store.com", :password => "secret"
+  #       end
+  #     end
+  #   end
+  class Flow
+  end
+end

data/lib/taza/page.rb

@@ -0,0 +1,259 @@
+require 'extensions/string'
+require 'watir/exceptions' # so we can trap them
+require 'watircraft/table'
+
+module Taza
+  # An abstraction of a web page, place the elements you care about accessing in here as well as specify the filters that apply when trying to access the element.
+  #
+  # Example:
+  #   require 'taza'
+  #   class HomePage < Taza::Page
+  #     element(:foo) {browser.element_by_xpath('some xpath')}
+  #     filter :title_given, :foo
+  #
+  #     def title_given
+  #       browser.title.nil?
+  #     end
+  #   end
+  #
+  # homepage.foo will return the element specified in the block if the filter returned true
+  class Page
+    attr_accessor :browser, :site
+
+    class << self
+
+      def elements # :nodoc:
+        @elements ||= {}
+      end
+
+      def filters # :nodoc:
+        @filters ||= Hash.new { [] }
+      end
+
+      def fields # :nodoc:
+        @fields ||= []
+      end
+
+      def url string=nil
+        if string.nil?
+          @url
+        else
+          @url = string
+        end
+      end
+
+      # An element on a page
+      #
+      # Watir Example:
+      #   class HomePage < Taza::Page
+      #     element(:next_button) {browser.button(:value, 'Next'}
+      #   end
+      # home_page.next_button.click
+      def element(name, &block)
+        name = name.to_s.computerize.to_sym
+        elements[name] = block
+      end
+
+      # An element on a page that has a value.
+      # Use #field for input elements and data elements.
+      #
+      #   class HomePage < Taza::Page
+      #     field(:name) {browser.text_field(:name, 'user_name')}
+      #   end
+      #
+      # home_page.name_field    # returns the text_field element
+      # home_page.name_field.exists?
+      # home_page.name = "Fred" # calls the #set method on the text_field
+      # home_page.name          # returns the current value (display_value) of the text_field
+      #
+      # The following Watir elements provide both #set and #display_value methods
+      #   text_field (both text boxes and text areas)
+      #   hidden
+      #   file_field
+      #   select_list
+      #   checkbox
+      #   (radios are the obvious item missing from this list -- we're working on it.)
+      #
+      # The following Watir elements provide #display_value methods (but not #set methods).
+      #   button
+      #   cell
+      #   hidden
+      #   all non-control elements, including divs, spans and most other elements.
+      def field(name, suffix='field', &block)
+        name = name.to_s.computerize.to_sym
+        fields << name
+        element_name = "#{name}_#{suffix}"
+        elements[element_name] = block
+        define_method(name) do
+          send(element_name).display_value
+        end
+        define_method("#{name}=") do |value|
+          send(element_name).set value
+        end
+        element_name
+      end
+  
+      # A filter for element(s) on a page
+      # Example:
+      #   class HomePage < Taza::Page
+      #     element(:foo) {browser.element_by_xpath('some xpath')}
+      #     filter :title_given, :foo
+      #     #a filter will apply to all elements if none are specified
+      #     filter :some_filter
+      #     #a filter will also apply to all elements if the symbol :all is given
+      #     filter :another_filter, :all
+      #
+      #     def some_filter
+      #       true
+      #     end
+      #
+      #     def some_filter
+      #       true
+      #     end
+      #
+      #     def title_given
+      #       browser.title.nil?
+      #     end
+      #   end
+      def filter(method_name, *elements)
+        elements = [:all] if elements.empty?
+        elements.each do |element|
+          self.filters[element] = self.filters[element] << method_name
+        end
+      end
+      
+      # Provides access to a WatirCraft::Table. 
+      #
+      # Requires that an element also be declared on the page that directly
+      # wraps the table element itself.
+      #      
+      # Example definition
+      #
+      #  class YourCartPage < ::Taza::Page
+      #    element(:items_table) {@browser.table(:index, 1)}
+      #    table(:items) do
+      #      field(:quantity) {@row.cell(:index, 1)}
+      #      field(:description) {@row.cell(:index, 2)}
+      #    end
+      #    field(:total) {@browser.cell(:id, 'totalcell')}
+      #
+      # Example usage
+      #
+      #   your_cart_page.items.row(:description => 'Pragmatic Project Automation').quantity.should == '1'
+      #
+      # Technical details: this method creates a 
+      # subclass and then allows its class methods to define fields and 
+      # elements on the table.
+      def table(name, &block)
+        # create subclass for the table
+        sub_class = Class.new(WatirCraft::Table)
+        sub_class.class_eval &block
+        # add method to the page, it returns an instance of the table subclass
+        define_method(name) do
+          sub_class.new send("#{name}_table")
+        end
+      end
+    end
+
+    def initialize
+      add_element_methods
+      @active_filters = []
+    end
+
+    def add_element_methods # :nodoc:
+      self.class.elements.each do |element_name,element_block|
+        filters = self.class.filters[element_name] + self.class.filters[:all]
+        add_element_method(:filters => filters, :element_name => element_name, :element_block => element_block)
+      end
+    end
+
+    def add_element_method(params) # :nodoc:
+      self.class.class_eval do
+        define_method(params[:element_name]) do |*args|
+          check_filters(params)
+          self.instance_exec(*args,&params[:element_block])
+        end
+      end
+    end
+
+    def check_filters(params) # :nodoc:
+      params[:filters].each do |filter_method|
+        unless @active_filters.include?(filter_method)
+          @active_filters << filter_method
+          raise FilterError, "#{filter_method} returned false for #{params[:element_name]}" unless send(filter_method)
+          @active_filters.delete(filter_method)
+        end
+      end
+    end
+    
+    # Go to this page. Url is computed based the page url and the url from the
+    # Site & Settings.
+    def goto
+      @site.goto self.class.url
+    end
+
+    # Return the full url expected for the page, taking into account the Site 
+    # and settings.
+    def full_url
+      File.join(@site.origin, self.class.url)
+    end
+    
+    # Enter values into fields on the page using a hash, using the key of
+    # each pair to name the field.
+    def populate hash
+      hash.each do |key, value|
+        send "#{key}=", value
+      end
+    end
+
+    # Verify that the fields specified by the keys in the hash correspond to the
+    # provided values.
+    def validate hash
+      hash.each do |key, value|
+        send(key).should == value
+      end
+    end
+    
+    # Return the names of the elements defined for the page.    
+    def elements
+      self.class.elements.keys.map &:to_s
+    end
+    
+    # Return the names of the fields defined for the page.
+    def fields
+      self.class.fields.map &:to_s
+    end
+    
+    # Returns a hash with the names and values of the specified fields.
+    # If no fields are specifieds, all fields on the page are used.
+    def values field_names=fields
+      result = {}
+      field_names.each { |name| result[name.to_sym] = send(name)}
+      result
+    end
+    
+    include Watir::Exception
+    def element_exist? name
+      begin
+        send(name).exist?
+      rescue UnknownFrameException, UnknownObjectException, 
+          UnknownFormException, UnknownCellException
+        false
+      end
+    end
+    alias :element_exists? :element_exist?
+  
+    def elements_exist? element_names=elements
+      result = {}
+      element_names.each do |element| 
+        result[element.to_sym] = element_exist?(element)
+      end
+      result
+    end
+    alias :elements_exists? :elements_exist?
+  
+  end
+
+  class FilterError < StandardError; end
+    
+end

data/lib/taza/settings.rb

@@ -0,0 +1,80 @@
+require 'activesupport'
+
+module Taza
+  class Settings
+    # The config settings from the site.yml and config.yml files.  
+    # ENV variables will override the settings.
+    #
+    # Example:
+    #   Taza::Settings.config('google')
+    def self.config(site_name=nil)
+      env_settings = {}
+      keys = %w(browser driver timeout server_ip server_port)
+      keys.each do |key|
+        env_settings[key.to_sym] = ENV[key.upcase] if ENV[key.upcase]
+      end
+      
+      default_settings = {:browser => :firefox, :driver => :watir}
+      
+      # Because of the way #merge works, the settings at the bottom of the list
+      # trump those at the top.
+      settings = environment_settings.merge(
+                   default_settings.merge(
+                     config_file.merge(
+                       env_settings)))
+
+      settings[:browser] = settings[:browser].to_sym
+      settings[:driver] = settings[:driver].to_sym
+      settings
+    end
+
+    # Returns a hash corresponding to the project config file.
+    def self.config_file
+      if File.exists?(config_file_path)
+        hash = YAML.load_file(config_file_path)
+      else
+        hash = {}
+      end
+      self.convert_string_keys_to_symbols hash
+    end
+
+    def self.config_file_path # :nodoc:
+      File.join(path, 'config', 'config.yml')
+    end
+    
+    # Returns a hash for the currently specified test environment
+    def self.environment_settings # :nodoc:
+      file = File.join(path, environment_file)
+      hash_of_hashes = YAML.load_file(file)
+      unless hash_of_hashes.has_key? environment
+        raise "Environment #{environment} not found in #{file}"
+      end
+      convert_string_keys_to_symbols hash_of_hashes[environment]
+    end
+    
+    @@root = nil
+
+    def self.path # :nodoc:
+      @@root || APP_ROOT
+    end
+    
+    def self.path= path
+      @@root = path
+    end
+    
+    def self.environment
+      ENV['ENVIRONMENT'] || 'test'
+    end
+    
+    def self.convert_string_keys_to_symbols hash
+      returning Hash.new do |new_hash|
+        hash.each_pair {|k, v| new_hash[k.to_sym] = v}
+      end
+    end
+    
+    private
+    def self.environment_file
+      'config/environments.yml'
+    end
+  end
+end