gless 1.0.1

data/lib/gless/session.rb

@@ -0,0 +1,319 @@
+require 'rspec'
+
+module Gless
+
+  # Provides an abstraction layer between the individual pages of an
+  # website and the high-level application layer, so that the
+  # application layer doesn't have to know about what page it's on
+  # or similar.
+  #
+  # For details, see the README.
+  class Gless::Session
+    include RSpec::Matchers
+
+    # The page class for the page the session thinks we're currently
+    # on.
+    attr_reader :current_page
+
+    # A list of page classes of pages that it's OK for us to be on.
+    # Usually just one, but some site workflows might have more than
+    # one thing that can happen when you click a button or whatever.
+    #
+    # When you assign a value here, a fair bit of processing is
+    # done.  Most of the actual work is in check_acceptable_pages
+    #
+    # The user can give us a class, a symbol, or a list of those; no
+    # matter what, we return a list.  That list is of possible pages
+    # that, if we turn out to be on one of them, that's OK, and if
+    # not we freak out.
+    #
+    # @param [Class, Symbol, Array] newpages A page class, or a
+    #   symbol naming a page class, or an array of those, for which
+    #   pages are acceptable.
+    attr_reader :acceptable_pages
+
+    # See docs for :acceptable_pages
+    def acceptable_pages= newpage
+      log.debug "Session: changing acceptable pages list to #{newpage}"
+      @acceptable_pages = (check_acceptable_pages newpage).flatten
+      log.info "Session: acceptable pages list has been changed to: #{@acceptable_pages}"
+    end
+
+    # This exists only to be called by +inherited+ on
+    # Gless::BasePage; see documentation there.
+    def self.add_page_class( klass )
+      @@page_classes ||= []
+      @@page_classes << klass
+    end
+
+
+    # Sets up the session object.  As the core abstraction layer that
+    # sits in the middle of everything, this requires a number of
+    # arguments. :)
+    #
+    # @param [Gless::Browser] browser
+    # @param [Gless::EnvConfig] config
+    # @param [Gless::Logger] logger
+    # @param [Object] application See the README for a description
+    #   of the stuff the application object is expected to have.
+    def initialize( browser, config, logger, application )
+      @logger = logger
+
+      log.debug "Session: Initializing with #{browser.inspect}"
+
+      @browser = browser
+      @application = application
+      @pages = Hash.new
+      @timeout = 30
+      @acceptable_pages = nil
+      @config = config
+
+      @@page_classes.each do |sc|
+        @pages[sc] = sc.new( @browser, self, @application )
+      end
+
+      log.debug "Session: Final pages table: #{@pages.keys.map { |x| x.name }}"
+
+      return self
+    end
+
+    # Just passes through to the Gless::EnvConfig component's +get+
+    # method.
+    def get_config(*args)
+      @config.get(*args)
+    end
+
+    # Just a shortcut to get to the Gless::Logger object.
+    def log
+      @logger
+    end
+
+    # Anything that we don't otherwise recognize is passed on to the
+    # current underlying page object (i.e. descendant of
+    # Gless::BasePage).
+    #
+    # This gets complicated because of the state checking: we test
+    # extensively that we're on the page that we think we should be
+    # on before passing things on to the page object.
+    def method_missing(m, *args, &block)
+      # Do some logging.
+      if m.inspect =~ /(password|login)/i or args.inspect =~ /(password|login)/i
+        log.debug "Session: Doing something with passwords, redacted."
+      else
+        log.debug "Session: method_missing for #{m} with arguments #{args.inspect}"
+      end
+
+      log.debug "Session: check if we've changed pages: #{@browser.title}, #{@browser.url}, #{@previous_url}, #{@current_page}, #{@acceptable_pages}"
+
+      # Changed URL means we've changed pages.  Our current page no
+      # longer being in the acceptable pages list means we *should*
+      # have changed pages. So we check both.
+      if @browser.url == @previous_url && @acceptable_pages.member?( @current_page )
+        log.debug "Session: doesn't look like we've moved."
+      else
+        # See if we're on one of the acceptable pages; wait until we
+        # are for "timeout" seconds.
+        good_page=false
+        new_page=nil
+        @timeout.times do
+          if @acceptable_pages.nil?
+            # If we haven't gone anywhere yet, anything is good
+            good_page = true
+            new_page = @pages[@current_page]
+            break
+          end
+
+          @acceptable_pages.each do |page|
+            log.debug "Session: Checking our current url, #{@browser.url}, for a match in #{page.name}: #{@pages[page].match_url(@browser.url)}"
+            if @pages[page].match_url(@browser.url)
+              good_page    = true
+              @current_page = page
+              new_page = @pages[page]
+              log.debug "Session: we seem to be on #{page.name} at #{@browser.url}"
+              break
+            end
+          end
+
+          if good_page
+            break
+          end
+          sleep 1
+        end
+
+        good_page.should be_true, "Current URL is #{@browser.url}, which doesn't match any of the acceptable pages: #{@acceptable_pages}"
+
+        log.debug "Session: checking for arrival at #{new_page.class.name}"
+        new_page.arrived?.should be_true
+
+        url=@browser.url
+        log.debug "Session: refreshed browser URL: #{url}"
+        new_page.match_url(url).should be_true
+
+        log.info "Session: We are currently on page #{new_page.class.name}, as we should be"
+
+        @previous_url = url
+      end
+
+      cpage = @pages[@current_page]
+
+      if m.inspect =~ /(password|login)/i or args.inspect =~ /(password|login)/i
+        log.debug "Session: dispatching method #{m} with args [redacted; password maybe] to #{cpage}"
+      else
+        log.debug "Session: dispatching method #{m} with args #{args.inspect} to #{cpage}"
+      end
+      retval = cpage.send(m, *args, &block)
+      log.debug "Session: method returned #{retval}"
+
+      retval
+    end
+
+    # This function is used to go to an intitial entry point for a
+    # website.  The page in question must have had set_entry_url run
+    # in its class definition, to define how to do this.  This setup
+    # exists because explaining to the session that we really should
+    # be on that page is a bit tricky.
+    #
+    # @param [Class] pklas The class for the page object that has a
+    #   set_entry_url that we are using.
+    def enter(pklas)
+      log.info "Session: Entering the site directly using the entry point for the #{pklas.name} page class"
+      @current_page = pklas
+      @pages[pklas].enter
+      # Needs to run through our custom acceptable_pages= method
+      self.acceptable_pages = pklas
+    end
+
+    # Wait for long-term AJAX-style processing, i.e. watch the page
+    # for extended amounts of time until particular events have
+    # occured.
+    #
+    # @param [String] message The text to print to the user each
+    #   time the page is not completely loaded.
+    # @param [Hash] opts Various named options.
+    #
+    # @option opts [Integer] numtimes The number of times to test the page.
+    # @option opts [Integer] interval The number of seconds to delay
+    #   between each check.
+    # @option opts [Array] any_elements Watir page elements, if any
+    #   of them are present, the page load is considered complete.
+    # @option opts all_elements Watir page elements, if all of them
+    #   are present, the page load is considered complete.
+    #
+    # @yieldreturn [Boolean] An optional Proc/code block; if
+    #   present, it is run before each page check.  This is so
+    #   simple interactions can occur without waiting for the
+    #   timeout, and so the whole process can be short-circuited.
+    #   If the block returns true, the long_wait ends successfully.
+    #
+    # @example
+    #
+    #   @session.long_wait "Cloud Application: Still waiting for the environment to be deleted.", :any_elements => [ @session.no_environments, @session.environment_deleted ]
+    #
+    # @return [Boolean] Returns true if, on any page test, the
+    #   element conditions were met or the block returned true (at
+    #   which point it exits immediately), false otherwise.
+    def long_wait message, opts = {}
+      # Merge in the defaults
+      opts = { :numtimes => 120, :interval => 30, :any_elements => nil, :all_elements => nil }.merge(opts)
+
+      begin
+        opts[:numtimes].times do |count|
+          # Run a code block if given; might do other checks, or
+          # click things we need to finish, or whatever
+          if block_given?
+            self.log.debug "Session: long_wait: yielding to passed block."
+            blockout = yield
+            if blockout == true
+              return true
+            end
+          end
+
+          # If any of these are present, we're done.
+          if opts[:any_elements]
+            opts[:any_elements].each do |elem|
+              self.log.debug "Session: long_wait: in any_elements, looking for #{elem}"
+              if elem.present?
+                self.log.debug "Session: long_wait: completed due to the presence of #{elem}"
+                return true
+              end
+            end
+          end
+          # If all of these are present, we're done.
+          if opts[:all_elements]
+            all_elems=true
+            opts[:all_elements].each do |elem|
+              self.log.debug "Session: long_wait: in all_elements, looking for #{elem}"
+              if ! elem.present?
+                all_elems=false
+              end
+            end
+            if all_elems == true
+              self.log.debug "Session: long_wait: completed due to the presence of all off #{opts[:all_elements]}"
+              return true
+            end
+          end
+
+          # We're still here, let the user know
+          self.log.info message
+
+          if (((count + 1) % 20) == 0) && (self.get_config :global, :debug)
+            self.log.debug "Session: long_wait: We've waited a multiple of 20 times, so giving you a debugger; 'c' to continue."
+            debugger
+          end
+
+          sleep opts[:interval]
+        end
+      rescue Exception => e
+        self.log.debug "Session: long_wait: Had an exception #{e}"
+        if self.get_config :global, :debug
+          self.log.debug "Session: long_wait: Had an exception in debug mode: #{e.inspect}"
+          self.log.debug "Session: long_wait: Had an exception in debug mode: #{e.message}"
+          self.log.debug "Session: long_wait: Had an exception in debug mode: #{e.backtrace.join("\n")}"
+
+          self.log.debug "Session: long_wait: Had an exception, and you're in debug mode, so giving you a debugger."
+          debugger
+        end
+      end
+
+      return false
+    end
+
+    # Deals with popup alerts in the browser (i.e. the javascript
+    # alert() function).  Always clicks "ok" or equivalent.
+    #
+    # FIXME: Check the text of the alert to see that it's the one
+    # we want.
+    # 
+    # Note that we're using @browser because things can be a bit
+    # wonky during an alert; we don't want to run session's "are we
+    # on the right page?" tests, or even talk to the page object.
+    def handle_alert
+      @browser.alert.wait_until_present
+
+      if @browser.alert.exists?
+        @browser.alert.ok
+      end
+    end
+
+    # Does the heavy lifting, such as it is, for +acceptable_pages=+
+    #
+    # @param [Class, Symbol, Array] newpage A page class, or a
+    #   symbol naming a page class, or an array of those, for which
+    #   pages are acceptable.
+    #
+    # @return [Array<Gless::BasePage>]
+    def check_acceptable_pages newpage
+      if newpage.kind_of? Class
+        return [ newpage ]
+      elsif newpage.kind_of? Symbol
+        return [ @pages.keys.find { |x| x.name =~ /#{newpage.to_s}$/ } ]
+      elsif newpage.kind_of? Array
+        return newpage.map { |p| check_acceptable_pages p }
+      else
+        raise "You set the acceptable_pages to #{newpage.class.name}; unhandled"
+      end
+    end
+
+  end
+
+end

data/lib/gless/wrap_watir.rb

@@ -0,0 +1,164 @@
+
+module Gless
+
+  # This class, as its name sort of implies, is used to wrap Watir
+  # elements.  Every element on a Gless page (i.e. any descentant of
+  # Gless::BasePage that uses the "element" class mothed) is not
+  # actually a Watir element but rather a Gless::WrapWatir instead.
+  #
+  # Most things are passed through to the underlying Watir element,
+  # but extensive logging occurs (in fact, if you have debugging on,
+  # this is where screenshots occur), and various extremely
+  # low-level checks are done to try to work around potential
+  # Selenium problems.  For example, all text entry is checked at
+  # this level and retried until it works, since Selenium/WebDriver
+  # tends to be flaky about that (and it's even worse if the browser
+  # window gets focus during the text entry).
+  #
+  # This shouldn't ever need to be used by a user; it's done
+  # automatically by the +element+ class method.
+  class Gless::WrapWatir
+    include RSpec::Matchers
+
+    # Sets up the wrapping.
+    #
+    # @param [Gless::Browser] browser
+    # @param [Gless::Session] session
+    # @param [Symbol] orig_type The type of the element; normally
+    #   with watir you'd do something like
+    #
+    #     watir.button :value, 'Submit'
+    #
+    #   In that expression, "button" is the orig_type.
+    # @param [Hash] orig_selector_args In the example
+    #   above,
+    #
+    #     { :value => 'Submit' }
+    #
+    #   is the selector arguments.
+    # @param [Gless::BasePage, Array<Gless::BasePage>] click_destination Optional. A list of pages that are OK places to end up after we click on this element
+    def initialize(browser, session, orig_type, orig_selector_args, click_destination)
+      @browser = browser
+      @session = session
+      @orig_type = orig_type
+      @orig_selector_args = orig_selector_args
+      @elem = @browser.send(@orig_type, @orig_selector_args)
+      @num_retries = 3
+      @wait_time = 30
+      @click_destination = click_destination
+    end
+
+    # Passes everything through to the underlying Watir object, but
+    # with logging.
+    def method_missing(m, *args, &block)
+      wrapper_logging(m, args)
+      @elem.send(m, *args, &block)
+    end
+
+    # Used to log all pass through behaviours.  In debug mode,
+    # displays details about what method was passed through, and the
+    # nature of the element in question.
+    def wrapper_logging(m, args)
+      if @orig_selector_args.inspect =~ /password/i
+        @session.log.debug "WrapWatir: Doing something with passwords, redacted."
+      else
+        if @session.get_config :global, :debug
+          @session.log.add_to_replay_log( @browser, @session )
+        end
+
+        @session.log.debug "WrapWatir: Calling #{m} with arguments #{args.inspect} on a #{@elem.class.name} element identified by: #{@orig_selector_args.inspect}"
+
+        if @elem.present? && @elem.class.name == 'Watir::HTMLElement'
+          @session.log.warn "FIXME: You have been lazy and said that something is of type 'element'; its actual type is  #{@elem.to_subtype.class.name}; the element is identified by #{@orig_selector_args.inspect}"
+        end
+      end
+    end
+
+    # A wrapper around Watir's click; handles the changing of
+    # acceptable pages (i.e. click_destination processing, see
+    # {Gless::BasePage} and {Gless::Session} for more details).
+    def click
+      if @click_destination
+        @session.log.debug "WrapWatir: A #{@elem.class.name} element identified by: #{@orig_selector_args.inspect} has a special destination when clicked, #{@click_destination}"
+        @session.acceptable_pages = @click_destination
+      end
+      wrapper_logging('click', nil)
+      @session.log.debug "WrapWatir: Calling click on a #{@elem.class.name} element identified by: #{@orig_selector_args.inspect}"
+      @elem.click
+    end
+
+    # Used by +set+, see description there.
+    def set_retries!(retries)
+      @num_retries=retries
+
+      return self
+    end
+
+    # Used by +set+, see description there.
+    def set_timeout!(timeout)
+      @wait_time=timeout
+
+      return self
+    end
+
+    # A wrapper around Watir's set element that retries operations.
+    # In particular, text fields and radio elements are checked to
+    # make sure that what we intended to enter *actually* got
+    # entered.  set_retries! and set_timeout! set the number of
+    # times to try to get things working and the delay between ecah
+    # such try.
+    def set(*args)
+      wrapper_logging('set', args)
+
+      # Double-check text fields
+      if @elem.class.name == 'Watir::TextField'
+        set_text = args[0]
+        @elem.set(set_text)
+
+        @num_retries.times do |x|
+          @session.log.debug "WrapWatir: Checking that text entry worked"
+          @elem = @browser.send(@orig_type, @orig_selector_args)
+          if @elem.value == set_text
+            break
+          else
+            @session.log.debug "WrapWatir: It did not; sleeping for #{@wait_time} seconds"
+            sleep @wait_time
+            @session.log.debug "WrapWatir: Retrying."
+            wrapper_logging('set', set_text)
+            @elem.set(set_text)
+          end
+        end
+        @elem.value.should == set_text
+        @session.log.debug "WrapWatir: The text entry worked"
+
+        return self
+
+        # Double-check radio buttons
+      elsif @elem.class.name == 'Watir::Radio'
+        wrapper_logging('set', [])
+        @elem.set
+
+        @num_retries.times do |x|
+          @session.log.debug "WrapWatir: Checking that the radio selection worked"
+          @elem = @browser.send(@orig_type, @orig_selector_args)
+          if @elem.set? == true
+            break
+          else
+            @session.log.debug "WrapWatir: It did not; sleeping for #{@wait_time} seconds"
+            sleep @wait_time
+            @session.log.debug "WrapWatir: Retrying."
+            wrapper_logging('set', [])
+            @elem.set
+          end
+        end
+        @elem.set?.should be_true
+        @session.log.debug "WrapWatir: The radio set worked"
+
+        return self
+
+      else
+        @elem.set(*args)
+      end
+    end
+  end
+end

data/lib/gless.rb

@@ -0,0 +1,54 @@
+
+# The Gless module itself only defines a setup method; all the meat
+# is in the other classes, especially {Gless::Session}.  See the
+# README for a general overview; it lives at
+# https://github.com/rlpowell/gless , which is also the home of this
+# project.
+module Gless
+  # The current version number.
+  VERSION = '1.0.1'
+
+  # Sets up the config, logger and browser instances, the ordering
+  # of which is slightly tricky.
+  #
+  # @return [Gless::Logger, Gless::EnvConfig, Gless::Browser] logger, config, browser (in that order)
+  def self.setup( tag )
+    logger = Gless::Logger.new( tag )
+
+    # Create the config reading/storage object
+    config = Gless::EnvConfig.new( )
+
+    # Get the whole backtrace, please.
+    if config.get :global, :debug
+      ::Cucumber.use_full_backtrace = true
+
+      ::RSpec.configure do |config|
+        # RSpec automatically cleans stuff out of backtraces;
+        # sometimes this is annoying when trying to debug something e.g. a gem
+        config.backtrace_clean_patterns = []
+      end
+    end
+
+    # Turn on verbose (info) level logging.
+    if config.get :global, :verbose
+      logger.normal_log.level = ::Logger::INFO
+      logger.replay_log.level = ::Logger::INFO
+      logger.debug "Verbose/info level logging enabled."
+    end
+
+    # Turn on debug level logging.
+    if config.get :global, :debug
+      logger.normal_log.level = ::Logger::DEBUG
+      logger.replay_log.level = ::Logger::DEBUG
+      logger.debug "Debug level logging enabled."
+    end
+
+    # Create the browser.
+    browser = Gless::Browser.new( config, logger )
+    browser.cookies.clear
+
+    return logger, config, browser
+  end
+end
+
+Dir["#{File.dirname(__FILE__)}/gless/*.rb"].each {|r| load r }