gless 1.1.3 → 1.2.0

data/.gitignore

@@ -11,6 +11,7 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+gless/lib/config/development.yml
 
 # YARD artifacts
 .yardoc

data/Changelog.txt

@@ -1,3 +1,5 @@
 - 1.1.0: 29 Jan 2013: By default, "element"s now ignore non-visible
   elements on the page; use { :invisible => true } to get the old
   behaviour.
+- 1.2.0: 10 Jun 2013: Changes by bairyn.  Added caching, finding
+based on parent element, and block validators.

data/examples/test_github/lib/config/development.yml.example

@@ -3,10 +3,11 @@
     :class: TestGithub
     :url: https://github.com
   :browser:
-    :type: local        # local or remote
-    :browser: firefox	# Which browser to use
+    :type: remote		# Local or remote
+    :browser: chrome	# Which browser to use
     :port: 4444		# If remote, port to connect to the selenimu server, otherwise ignored
   :verbose: false       # Whether to engage in more verbose/info level logging
   :debug: false	        # Whether to engage in debug logging
   :screenshots: false   # Whether, if debugging is on, to create screenshots as part of the replay log
   :thumbnails: false	# Whether, if screenshots are on, to create small-ish "thumbnail" pictures on the replay page; requires the imagemagick system package and the mini_magick gem
+  :cache: false  # Whether, by default, to cache elements, significantly improving performance.   For individual elements, caching can be disabled by adding ":cache => false" to the element specifier.

data/examples/test_github/lib/pages/test_github/blog_page.rb

@@ -5,7 +5,7 @@ module TestGithub
 
     url %r{^:base_url/blog$}
 
-    expected_title 'The Official GitHub Blog · GitHub'
+    expected_title 'The GitHub Blog · GitHub'
 
     # Stub page, but BasePage stuff still works
 

data/examples/test_github/lib/pages/test_github/search_page.rb

@@ -3,10 +3,17 @@
 module TestGithub
   class SearchPage < TestGithub::BasePage
 
-    element :search_input  , :text_field , :class => 'search-page-input' , :validator => true
-    element :search_button , :button     , :text => 'Search'             , :validator => true
+    element :search_form   , :form       , :id    => 'search_form'       , :validator => true
+    element :search_input  , :text_field , :class => 'search-page-input' , :validator => true , :parent => :search_form
+    element :search_button , :button     , :text  => 'Search'            , :validator => true , :parent => :search_form
+
+    # Test validator blocks.
+	add_validator do |browser, session|
+	  browser.url =~ /search/
+	end
 
     url %r{^:base_url/search}
+    set_entry_url ':base_url/search'
 
     expected_title %r{^(Code Search · GitHub|Search · \S+ · GitHub)$}
 
@@ -35,14 +42,14 @@ module TestGithub
     end
 
     def repositories
-      repos = self.divs.select { |div| div.class_name == 'result' }
+      repos = self.lis.select { |li| li.class_name == 'public source' }
 
       @session.log.debug "SearchPage: repositories: repos: #{repos.inspect}"
 
       repositories = Hash.new
       i = 0
       repos.each do |repo|
-        link = repo.h2.a
+        link = repo.h3.a
         data = Hash.new
         data[:index] = i
         data[:link] = link

data/examples/test_github/lib/pages/test_github_base_page.rb

@@ -1,11 +1,10 @@
 module TestGithub
   class TestGithub::BasePage < Gless::BasePage
 
-    element :home     , :link , :href => "https://github.com/"         , :validator => true , :click_destination => :LoginPage
-    element :explore  , :link , :href => "https://github.com/explore"  , :validator => true , :click_destination => :ExplorePage
-    element :search   , :link , :href => "https://github.com/search"   , :validator => true , :click_destination => :SearchPage
-    element :features , :link , :href => "https://github.com/features" , :validator => true , :click_destination => :FeaturesPage
-    element :blog     , :link , :href => "https://github.com/blog"     , :validator => true , :click_destination => :BlogPage
+    element :home     , :link , :href => %r{^(https://github.com|)/?$}          , :validator => true , :click_destination => :LoginPage
+    element :explore  , :link , :href => %r{^(https://github.com|)/explore/?$}  , :validator => true , :click_destination => :ExplorePage
+    element :features , :link , :href => %r{^(https://github.com|)/features/?$} , :validator => true , :click_destination => :FeaturesPage
+    element :blog     , :link , :href => %r{^(https://github.com|)/blog/?$}     , :validator => true , :click_destination => :BlogPage
 
   end
 end

data/examples/test_github/lib/test_github.rb

@@ -34,7 +34,7 @@ module TestGithub
     def goto_repository_from_anywhere name, repo_pattern
       @logger.info "TestGithub Application: going to repository #{name}"
 
-      @session.search.click
+      @session.enter TestGithub::SearchPage
 
       @session.search_for name
 
@@ -52,9 +52,6 @@ module TestGithub
       @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
 

data/lib/gless/base_page.rb

@@ -54,11 +54,21 @@ module Gless
       end
 
       # Calls back to Gless::Session.  See overview documentation
-      # fro +Gless::BasePage+
+      # for +Gless::BasePage+
       def inherited(klass)
         Gless::Session.add_page_class klass
       end
 
+      # @return [Array<String>] An list of element method names that the page
+      #   model contains.
+      attr_writer :elements
+
+      # @return [Array] Just sets up a default (to wit, []) for
+      #   elements
+      def elements
+        @elements ||= []
+      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
@@ -72,6 +82,17 @@ module Gless
         @validator_elements ||= []
       end
 
+      # @return [Array<String>] An list of validator procedures for this page.
+      #   This provides a more low-level version of validator elements.  For
+      #   more information, see the documentation for +add_validator+.
+      attr_writer :validator_blocks
+
+      # @return [Array] Just sets up a default (to wit, []) for
+      #   validator_blocks
+      def validator_blocks
+        @validator_blocks ||= []
+      end
+
       # Specifies the title that this page is expected to have.
       #
       # @param [String,Regexp] expected_title
@@ -98,8 +119,8 @@ module Gless
       # 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.
+      # rest is a hash.  +:validator+, +:click_destination+, +:parent+,
+      # +:proc+, and +:cache+ (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
@@ -126,6 +147,21 @@ module Gless
       #   bit of the class name of the page that clicking on this
       #   element leads to, if any.
       # 
+      # @option opts [Symbol] :parent (nil) A symbol of a parent element
+      #   to which matching is restricted.
+      # 
+      # @option opts [Symbol] :cache (nil) If non-nil, overrides the default
+      #   cache setting and determines whether caching is enabled for this
+      #   element.  If false, a new look-up will be performed each time the
+      #   element is accessed, and, if true, a look-up will only be performed
+      #   once until the session changes the page.
+      # 
+      # @option opts [Symbol] :proc (nil) If present, specifies a manual,
+      #   low-level procedure to return a watir element, which overrides other
+      #   selectors.  When the watir element is needed, this procedure is
+      #   called with the parent watir element passed as the argument (see
+      #   +:parent+) if it exists, and otherwise the browser.
+      # 
       # @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 = {}
@@ -134,11 +170,12 @@ module Gless
 
         # Promote various other things into selectors; do this before
         # we add in the default below
-        non_selector_opts = [ :validator, :click_destination ]
+        non_selector_opts = [ :validator, :click_destination, :parent, :cache ]
         if ! opts[:selector]
+          opts[:selector] = {} if ! opts.keys.empty?
           opts.keys.each do |key|
-            if ! non_selector_opts.member?(key)
-              opts[:selector] = { key => opts[key] }
+            if (! non_selector_opts.member?(key)) && (key != :selector)
+              opts[:selector][key] = opts[key]
               opts.delete(key)
             end
           end
@@ -152,9 +189,12 @@ module Gless
         selector = opts[:selector]
         click_destination = opts[:click_destination]
         validator = opts[:validator]
+        parent = opts[:parent]
+        cache = opts[:cache]
 
-        methname = basename.to_s.tr('-', '_')
+        methname = basename.to_s.tr('-', '_').to_sym
 
+        elements << methname
         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"
@@ -167,10 +207,21 @@ module Gless
         end
 
         define_method methname do
-          Gless::WrapWatir.new(@browser, @session, type, selector, click_destination)
+          cached_elements[methname] ||= Gless::WrapWatir.new(@browser, @session, self, type, selector, click_destination, parent, cache)
         end
       end
 
+      # Adds the given block to the list of validators to this page, which is
+      # run to ensure that the page is loaded.  This provides a low-level
+      # version of validator elements, which has more flexibility in
+      # determining whether the page is loaded.  The block is given two
+      # arguments: the browser, and the session.  The block is expected to
+      # return true if the validation succeeded; i.e., the page is currently
+      # loaded according to the validator's test; and otherwise false.
+      def add_validator &blk
+        validator_blocks << blk
+      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$}
@@ -235,12 +286,14 @@ module Gless
       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.elements += self.class.ancestors.map { |x| x.respond_to?( :elements ) ? x.elements : nil }
+      self.class.elements = self.class.elements.flatten.compact.uniq
+      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}"
+      @session.log.debug "In GenericBasePage, for #{self.class.name}, init: class vars: #{self.class.entry_url}, #{self.class.url_patterns}, #{self.class.elements}, #{self.class.validator_elements}"
     end
 
     # Return true if the given url matches this page's patterns
@@ -264,6 +317,8 @@ module Gless
     def enter
       @session.log.debug "#{self.class.name}: enter"
 
+      raise "#{self.class.name}.enter: no entry_url has been set" if self.class.entry_url.nil?
+
       arrived? do
         @session.log.info "#{self.class.name}: about to goto #{self.class.entry_url} from #{@browser.url}"
         @browser.goto self.class.entry_url
@@ -296,6 +351,13 @@ module Gless
           end
         end
 
+        self.class.validator_blocks.each do |x|
+          if ! x.call @browser, @session
+            @session.log.debug "In GenericBasePage, for #{self.class.name}, arrived?: a validator block failed."
+            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."
@@ -335,5 +397,19 @@ module Gless
         end
       end
     end
+
+    #******************************
+    # Object Level
+    #******************************
+
+    # @return [Hash] A hash of cached +WrapWatir+ elements indexed by the
+    #   symbol name.  This hash is cleared whenever the page changes.
+    attr_writer :cached_elements
+
+    # @return [Hash] A hash of cached +WrapWatir+ elements indexed by the
+    #   symbol name.  This hash is cleared whenever the page changes.
+    def cached_elements
+      @cached_elements ||= {}
+    end
   end
 end

data/lib/gless/browser.rb

@@ -30,7 +30,7 @@ module Gless
         @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
+        @browser = Watir::Browser.new browser
       end
     end
 

data/lib/gless/session.rb

@@ -123,6 +123,7 @@ module Gless
           @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)
+              clear_cache
               good_page    = true
               @current_page = page
               new_page = @pages[page]
@@ -281,21 +282,53 @@ module Gless
 
     # 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
+    #
+    # @param [Boolean] wait_for_alert (true) Whether to wait until an alert
+    # is present, failing if the request times out, before processing it;
+    # otherwise, handle any alerts if there are any currently present.
+    #
+    # @param [String,Regexp] expected_text (nil) If not nil, the text of the
+    # pop-up alert is checked against this parameter; if it
+    # differs, an exception will be raised.
+    def handle_alert wait_for_alert = true, expected_text = nil
+      @browser.alert.wait_until_present if wait_for_alert
 
       if @browser.alert.exists?
-        @browser.alert.ok
+        begin
+          if expected_text
+            current_text = @browser.alert.text
+            if (expected_text.kind_of? Regexp) ? expected_text !~ current_text : expected_text != current_text
+              msg = "The actual alert text differs from what was expected.  current_text: #{current_text}; expected_text: #{expected_text}"
+              @logger.error msg
+              raise msg
+            end
+          end
+
+          @browser.alert.ok
+        rescue Selenium::WebDriver::Error::NoAlertPresentError => e
+          msg = "Alert no longer exists; likely closed by user: #{e.message}"
+          if wait_for_alert
+            @logger.warn msg
+            raise
+          else
+            @logger.info msg
+          end
+        end
       end
     end
 
+    # Clears the cached elements.  Used before each page change.
+    #
+    # @param [Class] page_class The page class of the page whose cached
+    #   elements are to be cleared; defaults to the current page.
+    def clear_cache page_class = nil
+      @pages[page_class || current_page].cached_elements = Hash.new
+    end
+
     # Does the heavy lifting, such as it is, for +acceptable_pages=+
     #
     # @param [Class, Symbol, Array] newpage A page class, or a
@@ -372,6 +405,7 @@ module Gless
           @acceptable_pages.each do |page|
             log.debug "Session: change_pages: Checking our current url, #{url}, for a match in #{page.name}: #{@pages[page].match_url(url)}"
             if @pages[page].match_url(url) and @pages[page].arrived? == true
+              clear_cache
               good_page    = true
               @current_page = page
               new_page = @pages[page]

data/lib/gless/wrap_watir.rb

@@ -21,6 +21,10 @@ module Gless
     require 'rspec'
     include RSpec::Matchers
 
+    # @return [Gless::WrapWatir] The symbol for the parent of this element,
+    #   restricting the scope of its selectorselement.
+    attr_accessor :parent
+
     # Sets up the wrapping.
     #
     # As a special case, note that the selectors can include a :proc
@@ -38,6 +42,7 @@ module Gless
     #
     # @param [Gless::Browser] browser
     # @param [Gless::Session] session
+    # @param [Gless::BasePage] page
     # @param [Symbol] orig_type The type of the element; normally
     #   with watir you'd do something like
     #
@@ -51,32 +56,61 @@ module Gless
     #
     #   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)
+    # @param [Gless:WrapWatir] parents The symbol for the parent element under which the wrapped element is restricted.
+    # @param [Boolean] cache Whether to cache this element.  If false,
+    #   +find_elem+, unless overridden with its argument, performs a lookup
+    #   each time it is invoked; otherwise, the watir element is recorded
+    #   and kept until the session changes the page.  If nil, the default value
+    #   is retrieved from the config.
+    def initialize(browser, session, page, orig_type, orig_selector_args, click_destination, parent, cache)
       @browser = browser
       @session = session
+      @page = page
       @orig_type = orig_type
       @orig_selector_args = orig_selector_args
       @num_retries = 3
       @wait_time = 30
       @click_destination = click_destination
+      @parent = parent
+      @cache = cache.nil? ? @session.get_config(:global, :cache) : cache
     end
 
     # Finds the element in question; deals with the fact that the
-    # selector could actually be a Proc.
+    # selector could actually be a Proc.  If the element has already been
+    # found, return it; to find the element regardless, use find_elem_directly.
     #
     # Has no parameters because it uses @orig_type and
     # @orig_selector_args.  If @orig_selector_args has a :proc
     # element, runs that with the browser as an argument, otherwise
     # just passes those variables to the Watir browser as normal.
-    def find_elem
+    #
+    # @param [Boolean] use_cache If not nil, overrides the element's +cache+
+    # value.  If false, the element is re-located; otherwise, if the element
+    # has already been found, return it.
+    def find_elem use_cache = nil
+      use_cache = @cache if use_cache.nil?
+      if use_cache
+        @cached_elem ||= find_elem_directly
+      else
+        @cached_elem = find_elem_directly
+      end
+    end
+
+    # Find the element in question, regardless of whether the element has
+    # already been identified.  The cache is complete ignored and is not
+    # updated.  To update the cache and re-locate the element, use +find_elem
+    # false+
+    def find_elem_directly
       tries=0
       begin
-        # Do we want to return more than on element?
+        # Do we want to return more than one element?
         multiples = false
 
+        par = parent ? @page.send(parent).find_elem : @browser
+
         if @orig_selector_args.has_key? :proc
           # If it's a Proc, it can handle its own visibility checking
-          return @orig_selector_args[:proc].call @browser
+          return @orig_selector_args[:proc].call par
         else
           # We want all the relevant elements, so force that if it's
           # not what was asked for
@@ -91,7 +125,7 @@ module Gless
             end
           end
           @session.log.debug "WrapWatir: find_elem: elements type: #{type}"
-          elems = @browser.send(type, @orig_selector_args)
+          elems = par.send(type, @orig_selector_args)
         end
 
         @session.log.debug "WrapWatir: find_elem: elements identified by #{trimmed_selectors.inspect} initial version: #{elems.inspect}"
@@ -101,7 +135,7 @@ module Gless
           # Generally, watir-webdriver code expects *something*
           # back, and uses .present? to see if it's really there, so
           # we get the singleton to satisfy that need.
-          return @browser.send(@orig_type, @orig_selector_args)
+          return par.send(@orig_type, @orig_selector_args)
         end
 
         # We got something unexpected; just give it back

data/lib/gless.rb

@@ -6,7 +6,7 @@
 # project.
 module Gless
   # The current version number.
-  VERSION = '1.1.3'
+  VERSION = '1.2.0'
 
   # Sets up the config, logger and browser instances, the ordering
   # of which is slightly tricky.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gless
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-07 00:00:00.000000000 Z
+date: 2013-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -118,7 +118,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
-- .rvmrc
 - Changelog.txt
 - README.md
 - Rakefile
@@ -127,7 +126,6 @@ files:
 - examples/test_github/features/support/env.rb
 - examples/test_github/features/support/step_definitions/test_github_steps.rb
 - examples/test_github/features/test_github/test_github.feature
-- examples/test_github/lib/config/development.yml
 - examples/test_github/lib/config/development.yml.example
 - examples/test_github/lib/pages/test_github/blog_page.rb
 - examples/test_github/lib/pages/test_github/explore_page.rb
@@ -166,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: A wrapper for Watir-WebDriver based on modelling web page and web site structure.

data/.rvmrc

@@ -1,34 +0,0 @@
-#!/usr/bin/env bash
-
-# This is an RVM Project .rvmrc file, used to automatically load the ruby
-# development environment upon cd'ing into the directory
-
-# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
-# Only full ruby name is supported here, for short names use:
-#     echo "rvm use 1.9.3" > .rvmrc
-environment_id="ruby-1.9.3-p194@gless"
-
-# Uncomment the following lines if you want to verify rvm version per project
-# rvmrc_rvm_version="1.14.12 (stable)" # 1.10.1 seams as a safe start
-# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
-#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
-#   return 1
-# }
-
-# First we attempt to load the desired environment directly from the environment
-# file. This is very fast and efficient compared to running through the entire
-# CLI and selector. If you want feedback on which environment was used then
-# insert the word 'use' after --create as this triggers verbose mode.
-if [[ -d "${rvm_path:-$HOME/.rvm}/environments"
-  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
-then
-  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
-  [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]] &&
-    \. "${rvm_path:-$HOME/.rvm}/hooks/after_use" || true
-else
-  # If the environment file has not yet been created, use the RVM CLI to select.
-  rvm --create  "$environment_id" || {
-    echo "Failed to create RVM environment '${environment_id}'."
-    return 1
-  }
-fi

data/examples/test_github/lib/config/development.yml

@@ -1,12 +0,0 @@
-:global: # This tag distinguishes the global config from the per-test configs; *do not remove*
-  :site:
-    :class: TestGithub
-    :url: https://github.com
-  :browser:
-    :type: remote		# Local or remote
-    :browser: chrome	# Which browser to use
-    :port: 7444		# If remote, port to connect to the selenimu server, otherwise ignored
-  :verbose: false       # Whether to engage in more verbose/info level logging
-  :debug: false	        # Whether to engage in debug logging
-  :screenshots: false   # Whether, if debugging is on, to create screenshots as part of the replay log
-  :thumbnails: false	# Whether, if screenshots are on, to create small-ish "thumbnail" pictures on the replay page; requires the imagemagick system package and the mini_magick gem