gless 1.0.1

data/examples/test_github/lib/test_github.rb

@@ -0,0 +1,68 @@
+require 'uri'
+require 'gless'
+
+module TestGithub
+
+  class TestGithub::Application
+    include RSpec::Matchers
+
+    attr_accessor :browser
+    attr_accessor :session
+    attr_accessor :site
+    attr_accessor :base_url
+
+    def initialize( browser, config, logger )
+      @logger = logger
+      
+      @logger.debug "TestGithub Application: initializing with browser #{browser.inspect}"
+
+      @browser = browser
+      @config = config
+
+      @base_url = @config.get :global, :site, :url
+      @base_url.should be_true
+
+      # Create the session
+      @session = Gless::Session.new( @browser, @config, @logger, self )
+
+      @session.should be_true
+
+      @logger.info "TestGithub Application: going to github"
+      @session.enter TestGithub::LoginPage
+    end
+
+    def goto_repository_from_anywhere name, repo_pattern
+      @logger.info "TestGithub Application: going to repository #{name}"
+
+      @session.search.click
+
+      @session.search_for name
+
+      repodata = @session.find_repository repo_pattern
+      repodata.should be_true, "TestGithub Application: couldn't find repository #{name}"
+
+      @logger.info "TestGithub Application: found repository #{repodata[:name]}, which was at number #{repodata[:index] + 1} on the page, now opening it."
+
+      @session.goto_repository repo_pattern
+    end
+
+    def poke_headers
+      @logger.info "TestGithub Application: trying out all the header buttons."
+
+      @logger.info "TestGithub Application: clicking explore."
+      @session.explore.click
+
+      @logger.info "TestGithub Application: clicking search."
+      @session.search.click
+
+      @logger.info "TestGithub Application: clicking features."
+      @session.features.click
+
+      @logger.info "TestGithub Application: clicking blog."
+      @session.blog.click
+
+      @logger.info "TestGithub Application: clicking home."
+      @session.home.click
+    end
+  end
+end

data/gless.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "gless"
+
+Gem::Specification.new do |s|
+  s.name        = "gless"
+  s.version     = Gless::VERSION
+  s.authors     = ["Robin Lee Powell"]
+  s.email       = ["rlpowell@digitalkingdom.org"]
+  s.homepage    = "http://github.com/rlpowell/gless"
+  s.summary     = %q{A wrapper for Watir-WebDriver based on modelling web page and web site structure.}
+  s.description = %q{This gem attempts to provide a more robust model for web application testing, on top of Watir-WebDriver which already has significant improvements over just Selenium or WebDriver, based on describing pages and then interacting with the descriptions.}
+
+  s.add_dependency 'rspec'
+  s.add_dependency 'watir-webdriver'
+  s.add_dependency 'selenium-webdriver'
+  s.add_development_dependency 'debugger'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'yard-tomdoc'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/gless/base_page.rb

@@ -0,0 +1,339 @@
+require 'rspec'
+
+module Gless
+  #
+  # This class is intended to be the base class for all page classes
+  # used by the session object to represent individual pages on a
+  # website.  In fact, if you *don't* subclass all your page classes
+  # from this one, something is likely to break.
+  #
+  # = Class Level Methods
+  #
+  # This class defines a bunch of class-level behaviour, so that we can
+  # have things like
+  #
+  #   element :email_field,       :text_field,    :id => 'email'
+  #
+  # in the class definition itself.
+  #
+  # However, this is too early to do much of the initialization,
+  # which leads to some complexity in the real init method to
+  # basically make up for deferred computation.
+  #
+  # = Calling Back To The Session
+  #
+  # The session object needs to know all of the page object classes.
+  # This is accomplished by having an +inherited+ method on this
+  # (the +BasePage+) class that calls +add_page_class+ on the Session
+  # class; this only stores the subclass, it does no further
+  # processing, since complicated processing at class creation time
+  # tends to hit snags.  When a session object is actually
+  # instantiated, the list of page classes is walked, and a page
+  # class instance is created for each for future use.
+  #
+  class Gless::BasePage
+    include RSpec::Matchers
+
+    #******************************
+    # Class Level
+    #******************************
+
+    class << self
+      # @return [String] A URL that can be used to come to this page
+      #   directly, if that can be known at compile time; has no
+      #   sensible default
+      attr_accessor :entry_url
+
+      # @return [Array<String>, Array<Regexp>] A list of strings or
+      #   patterns to add to the Session dispatch list
+      attr_writer :url_patterns
+
+      # @return [Array] Just sets up a default (to wit, []) for url_patterns
+      def url_patterns
+        @url_patterns ||= []
+      end
+
+      # Calls back to Gless::Session.  See overview documentation
+      # fro +Gless::BasePage+
+      def inherited(klass)
+        Gless::Session.add_page_class klass
+      end
+
+      # @return [Array<String>] An list of elements (actually just
+      #   their method names) that should *always* exist if this
+      #   page is loaded; used to wait for the page to load and
+      #   validate correctness.  The page is not considered fully
+      #   loaded until all of these elements are found.
+      attr_writer :validator_elements
+
+      # @return [Array] Just sets up a default (to wit, []) for
+      #   validator_elements
+      def validator_elements
+        @validator_elements ||= []
+      end
+
+      # Specifies the title that this page is expected to have.
+      #
+      # @param [String,Regexp] expected_title
+      def expected_title expected_title
+        define_method 'has_expected_title?' do
+          @session.log.debug "In GenericBasePage, for #{self.class.name}, has_expected_title?: current is #{@browser.title}, expected is #{expected_title}"
+          expected_title.kind_of?(Regexp) ? @browser.title.should =~ expected_title :  @browser.title.should == expected_title
+        end
+      end
+
+      # Specifies an element that might appear on the page.
+      # The goal is to be easy for users of this library to use, so
+      # there's some real complexity here so that the end user can
+      # just do stuff like:
+      #
+      #   element :deleted_application    , :div     , :text => /Your application. \S+ has been deleted./
+      # 
+      # and it comes out feeling very natural.
+      #
+      # A longer example:
+      #
+      #   element :new_application_button , :element , :id => 'new_application'  , :validator => true , :click_destination => :ApplicationNewPage
+      #
+      # That's about as complicated as it gets.
+      #
+      # The first two arguments (name and type) are required.  The
+      # rest is a hash.  +:validator_elements+ and +:click_destination+
+      # (see below) have special meaning.
+      #
+      # Anything else is taken to be a Watir selector.  If no
+      # selector is forthcoming, the name is taken to be the element
+      # id.
+      #
+      # @param [Symbol] basename The name used in the Gless user's code
+      #   to refer to this element.  This page object ends up with a
+      #   method of this name.
+      #
+      # @param [Symbol] type The Watir element type; used to
+      #   dynamically pick which Watir element class to use for this
+      #   element.
+      #
+      # @param [Hash] opts Further options for the element.
+      #
+      # @option opts [Boolean] :validator (false) Whether or not the element should
+      #   be used to routinely validate the page's correctness
+      #   (i.e., if the element is central to the page and always
+      #   reliably is present).  The page isn't considered loaded
+      #   until all validator elements are present.  Defaults to
+      #   false.
+      #
+      # @option opts [Symbol] :click_destination (nil) A symbol giving the last
+      #   bit of the class name of the page that clicking on this
+      #   element leads to, if any.
+      # 
+      # @option opts [Object] ANY All other opts keys are used as
+      #   Watir selectors to find the element on the page.
+      def element basename, type, opts = {}
+        # No class-compile-time logging; it's way too much work, as this runs at *rake* time
+        # $master_logger.debug "In GenericBasePage for #{self.name}: element: initial opts: #{opts}"
+
+        # Promote various other things into selectors; do this before
+        # we add in the default below
+        non_selector_opts = [ :validator, :click_destination ]
+        if ! opts[:selector]
+          opts.keys.each do |key|
+            if ! non_selector_opts.member?(key)
+              opts[:selector] = { key => opts[key] }
+              opts.delete(key)
+            end
+          end
+        end
+
+        opts = { :selector => { :id => basename.to_s }, :validator => false, :click_destination => nil }.merge(opts)
+
+        # No class-compile-time logging; it's way too much work, as this runs at *rake* time
+        # $master_logger.debug "In GenericBasePage for #{self.name}: element: final opts: #{opts}"
+
+        selector = opts[:selector]
+        click_destination = opts[:click_destination]
+        validator = opts[:validator]
+
+        methname = basename.to_s.tr('-', '_')
+
+        if validator
+          # No class-compile-time logging; it's way too much work, as this runs at *rake* time
+          # $master_logger.debug "In GenericBasePage, for #{self.name}, element: #{basename} is a validator"
+          validator_elements << methname
+        end
+
+        if click_destination
+          # No class-compile-time logging; it's way too much work, as this runs at *rake* time
+          # $master_logger.debug "In GenericBasePage, for #{self.name}, element: #{basename} has a special destination when clicked, #{click_destination}"
+        end
+
+        define_method methname do
+          Gless::WrapWatir.new(@browser, @session, type, selector, click_destination)
+        end
+      end
+
+      # @return [Rexexp,String] Used to give the URL string or pattern that matches this page; example:
+      #
+      #   url %r{^:base_url/accounts/[0-9]+/apps$}
+      #
+      # +:base_url+ is replaced with the output of
+      # +@application.base_url+
+      def url( url )
+        if url.is_a?(String)
+          url_patterns << Regexp.new(Regexp.escape(url))
+        elsif url.is_a?(Regexp)
+          url_patterns << url
+        else
+          puts "INVALID URL class "+url.class.name+" for #{url.inspect}"
+        end
+      end
+
+      # Set this page's entry url.
+      #
+      # @param [String] url
+      def set_entry_url( url )
+        @entry_url = url
+      end
+
+    end # class-level definitions
+
+    #******************************
+    # Instance Level
+    #******************************
+
+
+    # @return [Watir::Browser]
+    attr_accessor :browser
+
+    # The main application object.  See the README for specifics.
+    attr_accessor :application
+
+    # @return [Gless::Session] The session object that uses/created
+    #   this page.
+    attr_accessor :session
+
+    # Perform special variable substitution; used for url match
+    # patterns and entry urls.
+    def substitute str
+      if str.kind_of?(Regexp)
+        reg = str.source
+        reg.gsub!(/\:base_url/,@application.base_url)
+        return Regexp.new(reg)
+      else
+        return str.gsub(/\:base_url/,@application.base_url)
+      end
+    end
+
+    def initialize browser, session, application
+      # @session.log.debug "In GenericBasePage, for #{self.class.name}, init: #{browser}, #{session}, #{application}"
+      @browser = browser
+      @session = session
+      @application = application
+
+      # Couldn't do this any earlier, needed the application
+      if self.class.entry_url
+        self.class.entry_url = substitute self.class.entry_url 
+      end
+
+      # Fake inheritance time
+      self.class.validator_elements = self.class.validator_elements + self.class.ancestors.map { |x| x.respond_to?( :validator_elements ) ? x.validator_elements : nil }
+      self.class.validator_elements = self.class.validator_elements.flatten.compact.uniq
+
+      self.class.url_patterns.map! { |x| substitute x }
+
+      @session.log.debug "In GenericBasePage, for #{self.class.name}, init: class vars: #{self.class.entry_url}, #{self.class.url_patterns}, #{self.class.validator_elements}"
+    end
+
+    # Return true if the given url matches this page's patterns
+    def match_url( url )
+      self.class.url_patterns.each do |pattern|
+        if url =~ pattern
+          return true
+        end
+      end
+
+      return false
+    end
+
+    # Pass through anything we don't understand to the browser, just
+    # in case.
+    def method_missing sym, *args, &block
+      @browser.send sym, *args, &block
+    end
+
+    # Go to the page from who-cares-where, and make sure we're there
+    def enter
+      @session.log.debug "#{self.class.name}: enter"
+
+      arrived? do
+        @session.log.info "#{self.class.name}: about to goto #{self.class.entry_url} from #{@browser.url}"
+        @browser.goto self.class.entry_url
+      end
+    end
+
+    # Make sure that we've actually gotten to this page, after clicking a button or whatever; used by Session
+    #
+    # Takes an optional block; if that block exists, it's run before
+    # the per-loop validation attempt.
+    def arrived?
+      all_validate = true
+
+      6.times do
+        if ! match_url( @browser.url )
+          yield if block_given?
+        end
+
+        self.class.validator_elements.each do |x|
+          begin
+            if self.send(x).wait_until_present(5) 
+              @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: validator element #{x} found."
+            else
+              # Probably never reached
+              @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: validator element #{x} NOT found."
+            end
+          rescue Watir::Wait::TimeoutError => e
+            @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: validator element #{x} NOT found."
+            all_validate = false
+          end
+        end
+
+        if all_validate
+          if match_url( @browser.url )
+            @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: all validator elements found."
+            break
+          else
+            @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: all validator elements found, but the current URL (#{@browser.url}) doesn't match the expected URL(s) (#{self.class.url_patterns})"
+          end
+        else
+          @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: not all validator elements found, trying again."
+        end
+      end
+
+      begin
+        if respond_to? :has_expected_title?
+          has_expected_title?.should be_true
+        end
+
+        match_url( @browser.url ).should be_true
+
+        # We don't use all_validate here because we want to alert on the
+        # element with the problem
+        self.class.validator_elements.each do |x|
+          self.send(x).wait_until_present(5).should be_true
+        end
+
+        @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: completed successfully."
+        return true
+      rescue Exception => e
+        if @session.get_config :global, :debug
+          @session.log.debug "GenericBasePage, for #{self.class.name}, arrived?: something doesn't match (url or title or expected elements), exception information follows, then giving you a debugger"
+          @session.log.debug "Gless::BasePage: Had an exception in debug mode: #{e.inspect}"
+          @session.log.debug "Gless::BasePage: Had an exception in debug mode: #{e.message}"
+          @session.log.debug "Gless::BasePage: Had an exception in debug mode: #{e.backtrace.join("\n")}"
+          debugger
+        else
+          return false
+        end
+      end
+    end
+  end
+end

data/lib/gless/browser.rb

@@ -0,0 +1,43 @@
+require 'watir-webdriver'
+require 'selenium-webdriver'
+
+module Gless
+  # A very minor wrapper on the Watir::Browser class to use
+  # Gless's config file system. Other than that it just adds logging
+  # at this point.  It might do more later.
+  class Gless::Browser
+    # The underlying Watir::Browser
+    attr_reader :browser
+
+    # Takes a Gless::EnvConfig object, which it uses to
+    # decide what kind of browser to launch, and launches a browser.
+    #
+    # @param [Gless::EnvConfig] config A Gless::EnvConfig which has
+    #   :global => :browser => :type defined.
+    #
+    # @return [Gless::Browser]
+    def initialize( config, logger )
+      @config = config
+      @logger = logger
+      type=@config.get :global, :browser, :type
+      browser=@config.get :global, :browser, :browser
+      port=@config.get :global, :browser, :port
+      @logger.debug "Launching some browser; #{type}, #{port}, #{browser}"
+
+      if type == 'remote'
+        @logger.info "Launching remote browser #{browser} on port #{port}"
+        capabilities = Selenium::WebDriver::Remote::Capabilities.new( :browser_name => browser, :javascript_enabled=>true, :css_selectors_enabled=>true, :takes_screenshot=>true, :native_events=>true )
+        @browser = Watir::Browser.new(:remote, :url => "http://127.0.0.1:#{port}/wd/hub", :desired_capabilities => capabilities)
+      else
+        @logger.info "Launching local browser #{browser}"
+        @browser = Watir::Browser.new :browser
+      end
+    end
+
+    # Pass everything else through to the Watir::Browser
+    # underneath.
+    def method_missing(m, *args, &block)
+      @browser.send(m, *args, &block)
+    end
+  end
+end

data/lib/gless/config.rb

@@ -0,0 +1,80 @@
+require 'yaml'
+
+module Gless
+  # Provides a bit of a wraper around yaml config files; nothing
+  # terribly complicated.  Can merge multiple configs together.
+  # Expects all configs to be hashes.
+  class Gless::EnvConfig
+    # Bootstrapping method used to inform Gless as to where
+    # config files can be found.
+    #
+    # @param [String] dir The directory name that holds the config
+    #   files (under lib/config in said directory).
+    #
+    # @example
+    #
+    #   Gless::EnvConfig.env_dir = File.dirname(__FILE__)
+    #
+    def self.env_dir=(dir)
+      @@env_dir=dir
+    end
+
+    # Sets up the initial configuration environment. @@env_dir must
+    # be set before this, or things will go poorly.
+    # The file it wants to load is, loosely,
+    # @@env_dir/lib/config/ENVIRONMENT.yml, where ENVIRONMENT is the
+    # environment variable of that name.
+    #
+    # @return [Gless::EnvConfig]
+    def initialize
+      env = (ENV['ENVIRONMENT'] || 'development').to_sym
+
+      env_file = "#{@@env_dir}/config/#{env}.yml"
+      raise "You need to create a configuration file named '#{env}.yml' (generated from the ENVIRONMENT environment variable) under #{@@env_dir}/lib/config" unless File.exists? env_file
+
+      @config = YAML::load_file env_file
+    end
+
+    # Add a file to those in use for configuration data.
+    # Simply merges in the new data, so each file should probably
+    # have its own top level singleton hash.
+    #
+    def add_file file
+      @config.merge!(YAML::load_file "#{@@env_dir}/#{file}")
+    end
+
+    # Get an element from the configuration.  Takes an arbitrary
+    # number of arguments; each is taken to be a hash key.
+    #
+    # @example
+    #
+    #  @config.get :global, :debug 
+    #
+    # @return [Object] what's left after following each key; could be
+    #   basically anything.
+    def get( *args )
+      return get_sub_tree( @config, *args )
+    end
+
+    private
+
+    # Recursively does all the heavy lifting for get
+    def get_sub_tree items, elem, *args
+      # Can't use debug logging here, as it maybe isn't turned on yet
+      # puts "In Gless::EnvConfig, get_sub_tree: items: #{items}, elem: #{elem}, args: #{args}"
+
+      if items.nil?
+        raise "Could not locate '#{elem}' in YAML config" if sub_tree.nil?
+      end
+
+      new_items = items[elem.to_sym]
+      raise "Could not locate '#{elem}' in YAML config" if new_items.nil?
+
+      if args.empty?
+        return new_items
+      else
+        return get_sub_tree( new_items, *args )
+      end
+    end
+  end
+end

data/lib/gless/logger.rb

@@ -0,0 +1,122 @@
+module Gless
+  # Provides some wrapping around the normal Logger class.  In
+  # particular, Gless::Logger has a concept of a replay log, which
+  # is an attempt to lay out all the things that happened during its
+  # interactions with the browser, including screenshots and HTML
+  # source at each step.
+  #
+  # This does not improve performance.  :)
+  #
+  # It also tries to simplify the maintenance of multiple logging
+  # streams, so that tests can be parallelized without too much
+  # trouble.
+  #
+  # The core system creates a log object with the tag :master for
+  # logging during setup and teardown.  It is expected that each
+  # session object (i.e. each parallel browser instance) will create
+  # its own for logging of what happens during the actual session.
+  class Gless::Logger
+    # The log stream that goes to STDOUT.  Here in case you need to
+    # bypass the normal multi-log semantics.
+    attr_reader :replay_log
+    # The log stream that goes to the replay directory.  Here in
+    # case you need to bypass the normal multi-log semantics.
+    attr_reader :normal_log
+
+    # Sets up logging.
+    #
+    # @param [Symbol] tag A short tag describing this particular log
+    #   stream (as opposed to other parallel ones that might exist).
+    #
+    # @param [Boolean] replay Whether or not to generate a replay
+    #   log as part of this log stream.
+    #
+    # @param [String] replay_path The path to put the replay logs
+    #   in.  Passed through Kernel.sprintf with :home (ENV['HOME']),
+    #   :tag, and :replay defined as you'd expect.
+    def initialize( tag, replay = true, replay_path = '%{home}/public_html/watir_replay/%{tag}' )
+      require 'logger'
+      require 'fileutils'
+
+      @ssnum = 0  # For snapshot pictures
+
+      @replay_path=sprintf(replay_path, { :home => ENV['HOME'], :tag => tag, :replay => replay })
+      FileUtils.rm_rf(@replay_path)
+      FileUtils.mkdir(@replay_path)
+
+      replay_log_file = File.open("#{@replay_path}/index.html", "w")
+      @replay_log = ::Logger.new replay_log_file
+
+      #@replay_log.formatter = proc do |severity, datetime, progname, msg|
+      #  # I, [2012-08-14T15:30:10.736784 #14647]  INFO -- : <p>Launching remote browser</p>
+      #  "<p>#{severity[0]}, [#{datetime} #{progname}]: #{severity} -- : #{msg}</p>\n"
+      #end
+
+      original_formatter = ::Logger::Formatter.new
+
+      # Add in the tag and html-ify
+      @replay_log.formatter = proc { |severity, datetime, progname, msg|
+        # Can't flush after from here, so flush prior stuff
+        replay_log_file.flush
+        npn = "#{progname} #{tag} ".sub(/^\s*/,'').sub(/\s*$/,'')
+        stuff=original_formatter.call(severity, datetime, "#{progname} #{tag} ", msg)
+        #"<p>#{ERB::Util.html_escape(stuff.chomp)}</p>\n"
+        "<p>#{stuff.chomp}</p>\n"
+      }
+      @replay_log.level = ::Logger::WARN
+
+      @normal_log = ::Logger.new(STDOUT)
+      # Add in the tag
+      @normal_log.formatter = proc { |severity, datetime, progname, msg|
+        original_formatter.call(severity, datetime, "#{progname} #{tag} ", msg)
+      }
+
+      @normal_log.level = ::Logger::WARN
+    end
+
+    # Passes on all the normal Logger methods.  By default, logs to
+    # both the normal log and the replay log.
+    def method_missing(m, *args, &block)
+      @replay_log.send(m, *args, &block)
+      @normal_log.send(m, *args, &block)
+    end
+
+    # Adds a screenshot and HTML source into the replay log from the
+    # given browser.
+    #
+    # @param [Watir::Browser] browser
+    # @param [Gless::Session] session
+    def add_to_replay_log( browser, session )
+      @ssnum = @ssnum + 1
+
+      if session.get_config :global, :screenshots
+        begin
+          browser.driver.save_screenshot "#{@replay_path}/screenshot_#{@ssnum}.png"
+
+          if session.get_config :global, :thumbnails
+            require 'mini_magick'
+
+            image = MiniMagick::Image.open("#{@replay_path}/screenshot_#{@ssnum}.png")
+            image.resize "400"
+            image.write "#{@replay_path}/screenshot_#{@ssnum}_thumb.png"
+            FileUtils.chmod 0755, "#{@replay_path}/screenshot_#{@ssnum}_thumb.png"
+
+            @replay_log.debug "Screenshot: <a href='screenshot_#{@ssnum}.png'><img src='screenshot_#{@ssnum}_thumb.png' /></a>"
+          else
+            @replay_log.debug "Screenshot: <a href='screenshot_#{@ssnum}.png'>Screenshot</a>"
+          end
+        rescue Exception => e
+          @normal_log.warn "Screenshot failed with exception #{e}"
+        end
+      end
+
+      html=browser.html
+      htmlFile = File.new("#{@replay_path}/html_capture_#{@ssnum}.txt", "w")
+      htmlFile.write(html)
+      htmlFile.close
+
+      @replay_log.debug "<a href='html_capture_#{@ssnum}.txt'>HTML Source</a>"
+      @replay_log.debug "Force flush"
+    end
+  end
+end