awetestlib 0.1.13 → 0.1.14

data/lib/awetestlib.rb

@@ -20,7 +20,7 @@ module Awetestlib
 
   if USING_WINDOWS
     #require 'win32ole' <-- We'll load this later in Shamisen::AwetestLegacy::Runner. It has to be loaded after watir, see https://www.pivotaltracker.com/story/show/19249981
-    require 'win32/screenshot'
+    require 'win32/screenshot'  # triggering segmentation fault 10sep2012 pmn
   end
   #require 'active_support/inflector'
   #require 'active_support/core_ext/object'

data/lib/awetestlib/logging.rb

@@ -1,10 +1,20 @@
 module Awetestlib
 module Logging
 
+  # @deprecated
   def self.included(mod)
     # puts "RegressionSupport::Logging extended by #{mod}"
   end
 
+  # Format log message and write to STDOUT.  Write to physical log if indicated.
+  # @private
+  # @param [Fixnum] severity Severity level of message. Use constants DEBUG, INFO, WARN, ERROR, FATAL, or UNKNOWN
+  # @param [String] message The message to be placed in the log.
+  # @param [String, Fixnum] tag Indicates the type of message. Valid string values are 'FAIL' and 'PASS'.
+  # Valid number values are 0 to 9.
+  # @param [Fixnum] lnbr the line number in the calling script
+  # @param [Fixnum] addts Obsolete, no longer used.
+  # @param [String] exception Obsolete, no longer used.
   def log_message(severity, message, tag = '', lnbr = nil, addts = 1, exception=nil)
     # caller = get_caller(lnbr, exception)
 
@@ -50,6 +60,10 @@ module Logging
 
   #private log_message
 
+  # Translates tag value to corresponding value for +pass+ column in database.
+  # @private
+  # @param [String, Fixnum] tag
+  # @return [String] Single character
   def pass_code_for(tag)
     case
       when tag =~ /PASS/
@@ -204,7 +218,7 @@ tags: log, error, fail, reference, tag, report
     @my_failed_count += 1 if @my_failed_count
     parse_error_references(message, true)
     @report_class.add_to_report("#{message}" + " [#{get_caller(lnbr)}]","FAILED")
-    log_message(WARN, "#{message}" + " (#{lnbr})]", FAIL, lnbr)
+    log_message(WARN, "#{message}", FAIL, lnbr)
   end
 
   alias validate_failed_tolog failed_to_log
@@ -302,7 +316,7 @@ tags: log, caller, trace, report
       end
     end
     logger               = ActiveSupport::BufferedLogger.new(logFile)
-    logger.level         = Logger::DEBUG
+    logger.level         = ActiveSupport::BufferedLogger::DEBUG
     logger.auto_flushing = (true)
     logger.add(INFO, "#{logFile}\n#{ENV["OS"]}")
     logger
@@ -408,4 +422,4 @@ tags: error, fail, hits, reference, tag, tallies
   end
 
 end
-end
+end

data/lib/awetestlib/regression/browser.rb

@@ -1,32 +1,28 @@
 module Awetestlib
+  # Awetest DSL for browser based testing.
   module Regression
+    # Methods to manage browser windows: open, close, attach, verify health, and clean up.
     module Browser
 
-      def run   #DO WE NEED? Use this method to tell user they need to create a run method?
-        setup
-        set_script_variables
-        run_test
-      rescue
-        fatal_to_log("(#{__LINE__})  #{$!}")
-        browser.close
-        raise
-      end
-
-=begin rdoc
-  :category: A_rdoc_test
-Opens a browser and returns a reference to it. If *url* is specified the browser is
-opened to that url, otherwise it is opened to a bland page
-
-_Parameters_::
-
-*url* - a string containing the full url. Optional.
-
-_Example_
-
-  browser = open_browser('www.google.com')
-
-=end
-
+      #def run   #DO WE NEED? Use this method to tell user they need to create a run method?
+      ## Not here in any case.
+      #  setup
+      #  set_script_variables
+      #  run_test
+      #rescue
+      #  fatal_to_log("(#{__LINE__})  #{$!}")
+      #  browser.close
+      #  raise
+      #end
+
+      # @!group Browser
+
+      # Open a browser based on the command line parameters that identify the browser and
+      # version to use for the test.
+      # @example
+      #  browser = open_browser('www.google.com')
+      # @param [String, Regexp] url When provided, the browser will go to this url.
+      # @return [Watir::Browser]
       def open_browser(url = nil)
         debug_to_log("Opening browser: #{@targetBrowser.name}")
         case @targetBrowser.abbrev
@@ -34,7 +30,6 @@ _Example_
             @myBrowser = open_ie
             if @myBrowser.class.to_s == "Watir::IE"
               @myHwnd = @myBrowser.hwnd
-              @waiter = Watir::Waiter.new(WAIT)
             end
           when 'FF'
             @myBrowser = open_ff_for_version
@@ -52,6 +47,11 @@ _Example_
         @myBrowser
       end
 
+      # Open IE (Internet Explorer) browser instance.
+      # If global variable $watir_script is set to true in the first line of the script,
+      # classic Watir will be used to drive the browser,
+      # otherwise Watir Webdriver will be used.
+      # @return [Watir::Browser]
       def open_ie
         if $watir_script
           browser = Watir::IE.new
@@ -61,6 +61,10 @@ _Example_
         browser
       end
 
+      # Open FF (Firefox) browser instance.
+      # @param [Fixnum] version A number designating the version of the browser to be opened.
+      # @return [Watir::Browser, Firewatir::Browser]
+      # Returns Firewatir::Browser if target browser is Firefox version less than 4.0
       def open_ff_for_version(version = @targetVersion)
         if version.to_f < 4.0
           browser = open_ff
@@ -70,25 +74,205 @@ _Example_
         browser
       end
 
+      # Open FF (Firefox) browser instance under FireWatir.
+      # @return [Firewatir::Browser]
       def open_ff
         Watir::Browser.default = 'firefox'
         browser = Watir::Browser.new
       end
 
+      # Open GC (Google Chrome) browser instance.
+      # @return [Watir::Browser] Browser is Google Chrome.
       def open_chrome
         browser = Watir::Browser.new(:chrome)
       end
 
-      def go_to_url(browser, url = nil, redirect = nil)
+      # Instruct browser to navigate to a specific URL
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] url When provided, the browser will go to this url.
+      # and the instance variable @myURL will be set to this value.
+      # @return [Boolean] True when navigation to url succeeds.
+      def go_to_url(browser, url = nil)
         if url
           @myURL = url
         end
         message_tolog("URL: #{@myURL}")
         browser.goto(@myURL)
+        true
       rescue
         fatal_to_log("Unable to navigate to '#{@myURL}': '#{$!}'")
       end
 
+      # Return a reference to a browser window.  Used to attach a browser window to a variable
+      # which can then be passed to methods that require a *browser* parameter.
+      # @example
+      #  mainwindow = open_browser('www.google.com')
+      #  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
+      #  popup = attach_browser(mainwindow, :url, '[url of new window]')   #*or*
+      #  popup = attach_browser(mainwindow, :title, '[title of new window]')
+      # @todo Update to work with webdriver for IE.
+      # @param [Watir::Browser] browser A reference to the current browser window.
+      # @param [Symbol] how The element attribute used to identify the window: *:title* or :url.
+      # @param [String|Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::Browser] Internet Explorer
+      def attach_browser(browser, how, what, desc = '')
+        debug_to_log("Attaching browser window :#{how}=>'#{what}' #{desc}")
+        uri_decoded_pattern = ::URI.encode(what.to_s.gsub('(?-mix:', '').gsub(')', ''))
+        case @browserAbbrev
+          when 'IE'
+            tmpbrowser      = Watir::IE.attach(how, what)
+            browser.visible = true
+            if tmpbrowser
+              tmpbrowser.visible = true
+              tmpbrowser.speed   = :fast
+            else
+              raise "Browser window :#{how}=>'#{what}' has at least one doc not in completed ready state."
+            end
+          when 'FF'
+            #TODO: This may be dependent on Firefox version if webdriver doesn't support 3.6.17 and below
+            browser.driver.switch_to.window(browser.driver.window_handles[0])
+            browser.window(how, /#{uri_decoded_pattern}/).use
+            tmpbrowser = browser
+          when 'S'
+            Watir::Safari.attach(how, what)
+            tmpbrowser = browser
+          when 'C'
+            browser.window(how, /#{uri_decoded_pattern}/).use
+            tmpbrowser = browser
+        end
+        debug_to_log("#{__method__}: tmpbrowser:#{tmpbrowser.inspect}")
+        tmpbrowser
+      end
+
+
+      # Returns a reference to a new browser window.  Used to attach a new browser window to a variable
+      # which can then be passed to methods that require a *browser* parameter. Calls attach_browser().
+      # @example
+      #  mainwindow = open_browser('www.google.com')
+      #  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
+      #  popup = attach_popup(mainwindow, :url, '[url of new window]') *or*
+      #  popup = attach_popup(mainwindow, :title, '[title of new window]')
+      # @param [Watir::Browser] browser A reference to the current browser window.
+      # @param [Symbol] how The element attribute used to identify the window: *:title* or :url.
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::Browser] The new browser window.
+      def attach_popup(browser, how, what, desc = '')
+        msg   = "Attach popup :#{how}=>'#{what}'. #{desc}"
+        popup = attach_browser(browser, how, what, desc)
+        sleep_for(1)
+        debug_to_log("#{popup.inspect}")
+        if is_browser?(popup)
+          title = popup.title
+          passed_to_log("#{msg} title='#{title}'")
+          return popup
+        else
+          failed_to_log(msg)
+        end
+      rescue
+        failed_to_log("Unable to attach popup :#{how}=>'#{what}'. #{desc} '#{$!}' (#{__LINE__})")
+      end
+
+      # Locate and close instances of IE browsers
+      def find_other_browsers
+        cnt = 0
+        if @targetBrowser.abbrev == 'IE'
+          Watir::IE.each do |ie|
+            debug_to_log("#{ie.inspect}")
+            ie.close()
+            cnt = cnt + 1
+          end
+        end
+        debug_to_log("Found #{cnt} IE browser(s).")
+        return cnt
+      rescue
+        error_to_log("#{$!}  (#{__LINE__})\n#{Kernel.caller.to_yaml}", __LINE__)
+        return 0
+      end
+
+      # @!endgroup Browser
+
+      # @!group Login
+
+      # Simple login method
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] user Login ID for the user.
+      # @param [String] password Password for the user.
+      # @return [Boolean] True if login succeeds.
+      def login(browser, user, password)
+        #TODO: Needs to be more flexible about finding login id and password textfields
+        #TODO: Parameterize url and remove references to environment
+        myURL  = @myAppEnv.url
+        runenv = @myAppEnv.nodename
+        message_tolog("URL: #{myURL}") if @myAppEnv
+        message_tolog("Beginning login: User: #{user} Environment: #{@myAppEnv.nodename}") if @myAppEnv
+        if validate(browser, @myName, __LINE__)
+          browser.goto(@myAppEnv.url)
+          if validate(browser, @myName)
+            set_textfield_by_name(browser, 'loginId', user)
+            set_textfield_by_name(browser, 'password', password)
+            click_button_by_value(browser, 'Login')
+            if validate(browser, @myName)
+              passed_to_log("Login successful.")
+              true
+            end
+          else
+            failed_to_log("Unable to login to application: '#{$!}'")
+            #screen_capture( "#{@myRoot}/screens/#{myName}_#{@runid}_#{__LINE__.to_s}_#{Time.new.to_f.to_s}.jpg")
+          end
+        end
+      rescue
+        failed_to_log("Unable to login to application: '#{$!}'")
+      end
+
+      # Logon to webpage using Basic Authorization type of logon. Uses AutoIt
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] user Login ID for the user.
+      # @param [String] password Password for the user.
+      # @param [String] url The URL to log on to.
+      # @param [Boolean] bypass_validate When set to true, the call to validate(),
+      # which checks the health of the browser, is skipped..
+      def basic_auth(browser, user, password, url, bypass_validate = false)
+        mark_testlevel("Basic Authorization Login", 0)
+
+        message_to_report ("Login:    #{user}")
+        message_to_report ("URL:      #{url}")
+        message_to_report ("Password: #{password}")
+
+        @login_title = "Connect to"
+
+        a = Thread.new {
+          browser.goto(url)
+        }
+
+        sleep_for(2)
+        message_to_log("#{@login_title}...")
+
+        if (@ai.WinWait(@login_title, "", 90) > 0)
+          win_title = @ai.WinGetTitle(@login_title)
+          debug_to_log("Basic Auth Login window appeared: '#{win_title}'")
+          @ai.WinActivate(@login_title)
+          @ai.ControlSend(@login_title, '', "[CLASS:Edit; INSTANCE:2]", '!u')
+          @ai.ControlSend(@login_title, '', "[CLASS:Edit; INSTANCE:2]", user, 1)
+          @ai.ControlSend(@login_title, '', "[CLASS:Edit; INSTANCE:3]", password.gsub(/!/, '{!}'), 1)
+          @ai.ControlClick(@login_title, "", '[CLASS:Button; INSTANCE:1]')
+        else
+          debug_to_log("Basic Auth Login window did not appear.")
+        end
+        a.join
+
+        validate(browser, @myName) unless bypass_validate
+
+        message_to_report("URL: [#{browser.url}] User: [#{user}]")
+
+      end
+
+      # Provide an authorization token or passcode in a specified text field element identified by its *:id* attribute.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] role Usually a user role designation ('Administrator', 'User', etc.)
+      # @param [String] token Authentification token required by logon process.
+      # @param [String/Regexp] id Value of the *:id* attribute of the text field that will receive the *token*.
       def token_auth(browser, role, token, id = 'token_pass')
         set_textfield_by_id(browser, id, token)
         click_button_by_value(browser, 'Continue')
@@ -97,9 +281,19 @@ _Example_
         end
       end
 
-      def bail_out(browser, lnbr, msg)
+      # @!endgroup Logon
+
+      # @!group Error Handling
+
+      # Exit more or less gracefully from script when errors are too severe to continue.
+      # Normally not called in a test script or project library.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Fixnum] lnbr Line number in calling script.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      #
+      def bail_out(browser, lnbr, desc)
         ts  = Time.new
-        msg = "Bailing out at util line #{lnbr} #{ts} " + msg
+        msg = "Bailing out at util line #{lnbr} #{ts} " + desc
         puts "#{msg}"
         fatal_to_log(msg, nil, 1, lnbr)
         debug_to_log(dump_caller(lnbr))
@@ -118,15 +312,9 @@ _Example_
         raise(RuntimeError, msg, caller)
       end
 
-      def do_taskkill(severity, pid)
-        if pid and pid > 0 and pid < 538976288
-          info_to_log("Executing taskkill for pid #{pid}")
-          log_message(severity, %x[taskkill /t /f /pid #{pid}])
-        end
-      rescue
-        error_to_log("#{$!}  (#{__LINE__})")
-      end
 
+      # Check for the presence of IE browser instances.
+      # @return [Fixnum] The number of IE browser instances encountered.
       def check_for_other_browsers
         cnt1 = find_other_browsers
         cnt2 = Watir::Process.count 'iexplore.exe'
@@ -135,6 +323,7 @@ _Example_
         error_to_log("#{$!}  (#{__LINE__})\n#{Kernel.caller.to_yaml}")
       end
 
+      # Check for the presence of IE browser instances and close all that are found.
       def check_for_and_clear_other_browsers
         if @targetBrowser.abbrev == 'IE'
           debug_to_log("#{__method__}:")
@@ -174,7 +363,12 @@ _Example_
         error_to_log("#{__method__}: #{$!}  (#{__LINE__})\n#{Kernel.caller.to_yaml}")
       end
 
-      def kill_browser(hwnd, lnbr, browser = nil, doflag = false)
+      # Force browser instance to close, one way or the other.
+      # Instance is identified by *hwnd*, the Windows OS handle for the process.
+      # @param [String] hwnd The value for the window handle for the browser process.
+      # @param [Fixnum] lnbr Line number in calling script.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be closed.
+      def kill_browser(hwnd, lnbr, browser = nil)
         # TODO Firefox
         logit = false
         if @browserAbbrev == 'FF'
@@ -182,7 +376,7 @@ _Example_
             logit = true
             here  = __LINE__
             url   = browser.url
-            capture_screen(browser, Time.new.to_f) if @screenCaptureOn
+            #capture_screen(browser, Time.new.to_f) if @screenCaptureOn
             browser.close if url.length > 0
             @status = 'killbrowser'
             fatal_to_log("Kill browser called from line #{lnbr}")
@@ -194,7 +388,7 @@ _Example_
               here  = __LINE__
               logit = true
               url   = browser.url
-              capture_screen(browser, Time.new.to_f) if @screenCaptureOn
+              #capture_screen(browser, Time.new.to_f) if @screenCaptureOn
               browser.close
               sleep(2)
               if browser.exists?
@@ -210,159 +404,49 @@ _Example_
          end
        end
 
-=begin rdoc
-  :category: A_rdoc_test
-
-Returns a reference to a browser window.  Used to attach a browser window to a variable
-which can then be passed to methods that require a *browser* parameter.
-
-_Parameters_::
-
-*browser* - a reference to the browser window to be tested
-
-*how* - the browser attribute used to identify the window:  either :url or :title
-
-*what* - a string or a regular expression in the url or title
-
-*desc* - a string containing a message or description intended to appear in the log and/or report output
+      # @!endgroup Error Handling
 
+      # @!group Browser
 
-*_Example_*
-
-  mainwindow = open_browser('www.myapp.com')  # open a browser to www.google.com
-  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
-  popup = attach_browser(mainwindow, :url, '[url of new window]')   #*or*
-  popup = attach_browser(mainwindow, :title, '[title of new window]')
-
-=end
-
-      def attach_browser(browser, how, what, desc = '')
-        debug_to_log("Attaching browser window :#{how}=>'#{what}' #{desc}")
-        uri_decoded_pattern = URI.encode(what.to_s.gsub('(?-mix:', '').gsub(')', ''))
-        case @browserAbbrev
-          when 'IE'
-            tmpbrowser      = Watir::IE.attach(how, what)
-            browser.visible = true
-            if tmpbrowser
-              tmpbrowser.visible = true
-              tmpbrowser.speed   = :fast
-            else
-              raise "Browser window :#{how}=>'#{what}' has at least one doc not in completed ready state."
+      # Use enabled_popup and winclicker to determine if there is an active modal popup.
+      # Useful only when no wait action has been invoked.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] button The visible name of the button to be clicked to close the popup.
+      # @return [String] containing the window handle of the closed modal popup.
+      def modal_exists?(browser, button = nil)
+        rtrn = nil
+        if @browserAbbrev == 'IE'
+          Timeout::timeout(2) do
+            begin
+              if browser.enabled_popup
+                hwnd = browser.enabled_popup(5)
+                debug_to_log("Modal popup with handle #{hwnd} found. (#{__LINE__})")
+                wc = WinClicker.new
+                wc.makeWindowActive(hwnd)
+                rtrn = wc.getWindowTitle(hwnd)
+                if button
+                  wc.clickWindowsButton_hWnd(hwnd, button)
+                end
+                wc = nil
+              end
+            rescue Timeout::Error
+              debug_to_log("No Modal popup found. (#{__LINE__})")
+              return rtrn
             end
-          when 'FF'
-            #TODO: This may be dependent on Firefox version if webdriver doesn't support 3.6.17 and below
-            browser.driver.switch_to.window(browser.driver.window_handles[0])
-            browser.window(how, /#{uri_decoded_pattern}/).use
-            tmpbrowser = browser
-          when 'S'
-            browser.driver.switch_to.window(browser.driver.window_handles[0])
-            sleep 1
-            browser.window(how, /#{uri_decoded_pattern}/).use
-            tmpbrowser = browser
-          when 'C'
-            browser.window(how, /#{uri_decoded_pattern}/).use
-            tmpbrowser = browser
-        end
-        debug_to_log("#{__method__}: tmpbrowser:#{tmpbrowser.inspect}")
-        tmpbrowser
-      end
-
-=begin rdoc
-  :category: A_rdoc_test
-Returns a reference to a browser window using the window's url. Calls attach_browser().
-
-_Parameters_::
-
-*browser* - a reference to the browser window to be tested
-
-*pattern* - a string with the complete url or a regular expression containing part of the url
-that uniquely identifies it in the context of the test.
-
-*desc* - a string containing a message or description intended to appear in the log and/or report output
-
-
-_Example_
-
-  mainwindow = open_browser('www.myapp.com')  # open a browser to www.google.com
-  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
-  popup = attach_browser_by_url(mainwindow, '[url of new window]')
-
-=end
-
-      def attach_browser_by_url(browser, pattern, desc = '')
-        attach_browser(browser, :url, pattern, desc)
-      end
-
-      alias attach_browser_with_url attach_browser_by_url
-
-=begin rdoc
-  :category: A_rdoc_test
-Returns a reference to a new browser window.  Used to attach a new browser window to a variable
-which can then be passed to methods that require a *browser* parameter. Calls attach_browser().
-
-_Parameters_::
-
-*browser* - a reference to the browser window to be tested
-
-*how* - the browser attribute used to identify the window:  either :url or :title
-
-*what* - a string or a regular expression in the url or title
-
-*desc* - a string containing a message or description intended to appear in the log and/or report output
-
-
-_Example_
-
-  mainwindow = open_browser('www.myapp.com')  # open a browser to www.google.com
-  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
-  popup = attach_popup(mainwindow, :url, '[url of new window]') *or*
-  popup = attach_popup(mainwindow, :title, '[title of new window]')
-
-=end
-      def attach_popup(browser, how, what, desc = '')
-        msg   = "Attach popup :#{how}=>'#{what}'. #{desc}"
-        popup = attach_browser(browser, how, what, desc)
-        sleep_for(1)
-        debug_to_log("#{popup.inspect}")
-        if is_browser?(popup)
-          title = popup.title
-          passed_to_log("#{msg} title='#{title}'")
-          return popup
-        else
-          failed_to_log(msg)
-        end
-      rescue
-        failed_to_log("Unable to attach popup :#{how}=>'#{what}'. #{desc} '#{$!}' (#{__LINE__})")
-      end
-
-      def attach_popup_by_title(browser, strg, desc = '')
-        attach_popup(browser, :title, strg, desc)
-      end
-
-      def attach_popup_by_url(browser, pattern, desc = '')
-        attach_popup(browser, :url, pattern, desc)
-      end
-
-      alias get_popup_with_url attach_popup_by_url
-      alias attach_popup_with_url attach_popup_by_url
-      alias attach_iepopup attach_popup_by_url
-
-      def find_other_browsers
-        cnt = 0
-        if @targetBrowser.abbrev == 'IE'
-          Watir::IE.each do |ie|
-            debug_to_log("#{ie.inspect}")
-            ie.close()
-            cnt = cnt + 1
+            return rtrn
           end
+          rtrn
+        else
+          rtrn
         end
-        debug_to_log("Found #{cnt} IE browser(s).")
-        return cnt
-      rescue
-        error_to_log("#{$!}  (#{__LINE__})\n#{Kernel.caller.to_yaml}", __LINE__)
-        return 0
       end
 
+      # Close a browser window identified by its title.
+      # Uses AutoIt. Windows only.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] title The title of the window to be closed.  Matched from beginning of string.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @param [String] text (optional) The text of the window to be closed.  Matched from beginning of string.
       def close_window_by_title(browser, title, desc = '', text = '')
         msg = "Window '#{title}':"
         if @ai.WinWait(title, text, WAIT) > 0
@@ -383,74 +467,7 @@ _Example_
         failed_to_log("#{msg}: Unable to close: '#{$!}'. (#{__LINE__}) #{desc}")
       end
 
-=begin rdoc
-:category: Basic
-:tags:logon, login, user, password, url
-TODO: Needs to be more flexible about finding login id and password textfields
-TODO: Parameterize url and remove references to environment
-=end
-      def login(browser, user, password)
-        myURL  = @myAppEnv.url
-        runenv = @myAppEnv.nodename
-        message_tolog("URL: #{myURL}")
-        message_tolog("Beginning login: User: #{user} Environment: #{runenv}")
-        if validate(browser, @myName, __LINE__)
-          browser.goto(myURL)
-          if validate(browser, @myName)
-            set_textfield_by_name(browser, 'loginId', user)
-            set_textfield_by_name(browser, 'password', password)
-            click_button_by_value(browser, 'Login')
-            if validate(browser, @myName)
-              passed_to_log("Login successful.")
-            end
-          else
-            failed_to_log("Unable to login to application: '#{$!}'")
-            #          screen_capture( "#{@myRoot}/screens/#{myName}_#{@runid}_#{__LINE__.to_s}_#{Time.new.to_f.to_s}.jpg")
-          end
-        end
-      rescue
-        failed_to_log("Unable to login to application: '#{$!}'")
-      end
-
-=begin rdoc
-category: Logon
-:tags:logon, login, user, password, url, basic authorization
-=end
-      def basic_auth(browser, user, pswd, url, bypass_validate = false)
-        mark_testlevel("Basic Authorization Login", 0)
-
-        message_to_report ("Login:    #{user}")
-        message_to_report ("URL:      #{url}")
-        message_to_report ("Password: #{pswd}")
-
-        @login_title = "Connect to"
-
-        a = Thread.new {
-          browser.goto(url)
-        }
-
-        sleep_for(2)
-        message_to_log("#{@login_title}...")
-
-        if (@ai.WinWait(@login_title, "", 90) > 0)
-          win_title = @ai.WinGetTitle(@login_title)
-          debug_to_log("Basic Auth Login window appeared: '#{win_title}'")
-          @ai.WinActivate(@login_title)
-          @ai.ControlSend(@login_title, '', "[CLASS:Edit; INSTANCE:2]", '!u')
-          @ai.ControlSend(@login_title, '', "[CLASS:Edit; INSTANCE:2]", user, 1)
-          @ai.ControlSend(@login_title, '', "[CLASS:Edit; INSTANCE:3]", pswd.gsub(/!/, '{!}'), 1)
-          @ai.ControlClick(@login_title, "", '[CLASS:Button; INSTANCE:1]')
-        else
-          debug_to_log("Basic Auth Login window did not appear.")
-        end
-        a.join
-
-        validate(browser, @myName) unless bypass_validate
-
-        message_to_report("URL: [#{browser.url}] User: [#{user}]")
-
-      end
-
+      # Closes main browser session. Misnamed. Usually used at end of script to shut down browser.
       def logout(browser, where = @myName, lnbr = __LINE__)
         #TODO Firewatir 1.6.5 does not implement .exists for FireWatir::Firefox class
         debug_to_log("Logging out in #{where} at line #{lnbr}.", lnbr, true)
@@ -483,7 +500,7 @@ category: Logon
                 browser.close
               end
               if browser.exists? and pid > 0 and pid < 538976288 # value of uninitialized memory location
-                kill_browser(browser.hwnd, __LINE__, browser, true)
+                kill_browser(browser.hwnd, __LINE__, browser)
               end
             when 'S'
               if is_browser?(browser)
@@ -520,7 +537,8 @@ category: Logon
         #    end
       end
 
-      #close popup in new window
+      # Close a browser popup window. Does not apply to modal popups.
+      # @param [Watir::Browser] popup Reference to the popup to be closed
       def close_new_window_popup(popup)
         if is_browser?(popup)
           url = popup.url
@@ -530,24 +548,27 @@ category: Logon
         end
       end
 
-      def close_panel_by_text(browser, panel, strg = 'Close')
+      # Close an HTML panel or division by clicking a link within it identified by the *:text* value of the link.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Watir::Browser] panel Reference to the panel (usually a div element) to be closed
+      def close_panel_by_text(browser, panel, what = 'Close')
         if validate(browser, @myName, __LINE__)
           if @browserAbbrev == 'IE'
-            panel.link(:text, strg).click!
+            panel.link(:text, what).click!
           elsif $USE_FIREWATIR
             begin
-              panel.link(:text, strg).click
+              panel.link(:text, what).click
             rescue => e
-              if not rescue_me(e, __method__, "link(:text,'#{strg}').click", "#{panel.class}")
+              if not rescue_me(e, __method__, "link(:text,'#{what}').click", "#{panel.class}")
                 raise e
               end
             end
           else
-            panel.link(:text, strg).click(:wait => false)
+            panel.link(:text, what).click(:wait => false)
           end
           sleep_for(1)
           if validate(browser, @myName, __LINE__)
-            passed_to_log("Panel '#{strg}' (by :text) closed.")
+            passed_to_log("Panel '#{what}' (by :text) closed.")
             true
           end
         else
@@ -557,104 +578,110 @@ category: Logon
         failed_to_log("Click on '#{strg}'(by :text) failed: '#{$!}' (#{__LINE__})")
       end
 
-      #  def close_modal_ie(title="", button="OK", text='', side = 'primary', wait = WAIT)
-      def close_popup(title, button = "OK", text = '', side = 'primary', wait = WAIT, desc = '', quiet = false)
-        #TODO needs simplifying and debug code cleaned up
-        title = translate_popup_title(title)
-        msg   = "'#{title}'"
-        msg << " with text '#{text}'" if text.length > 0
-        msg << " (#{desc})" if desc.length > 0
-        @ai.Opt("WinSearchChildren", 1) # Match any substring in the title
-        if @ai.WinWait(title, text, wait) > 0
-          myHandle  = @ai.WinGetHandle(title, text)
-          full_text = @ai.WinGetText(title)
-          #debug_to_report("Found popup handle:'#{myHandle}', title:'#{title}', text:'#{full_text}'")
-          if myHandle.length > 0
-            debug_to_log("hwnd: #{myHandle.inspect}")
-            passed_to_log("#{msg} appeared.") unless quiet
-            sleep_for(0.5)
-            @ai.WinActivate(title, text)
-            if @ai.WinActive(title, text) #  > 0   #Hack to prevent fail when windows session locked
-              debug_to_log("#{msg} activated.")
-              if @ai.ControlFocus(title, text, button) #  > 0
-                controlHandle = @ai.ControlGetHandle(title, '', "[CLASS:Button; TEXT:#{button}]")
-                if not controlHandle
-                  button        = "&#{button}"
-                  controlHandle = @ai.ControlGetHandle(title, '', "[CLASS:Button; TEXT:#{button}]")
-                end
-                debug_to_log("Handle for button '#{button}': [#{controlHandle}]")
-                debug_to_log("#{msg} focus gained.")
-                #              sleep_for(2)
-                if @ai.ControlClick(title, text, button, side) # > 0
-                                                               #            if @ai.ControlClick(title, text, "[Handle:#{controlHandle}]", side) > 0
-                                                               #                debug_to_log("#{msg} #{side} click on 'Handle:#{controlHandle}'." )
-                  debug_to_log("#{msg} #{side} click on '#{button}' successful.")
-                  sleep_for(1)
-                  if @ai.WinExists(title, text) > 0
-                    debug_to_log("#{msg} close popup failed on click '#{button}'. Trying WinClose. (#{__LINE__})")
-                    @ai.WinClose(title, text)
-                    if @ai.WinExists(title, text) > 0
-                      debug_to_log("#{msg} close popup failed with WinClose('#{title}','#{text}'). (#{__LINE__})")
-                      @ai.WinKill(title, text)
-                      if @ai.WinExists(title, text) > 0
-                        debug_to_log("#{msg} close popup failed with WinKill('#{title}','#{text}'). (#{__LINE__})")
-                      else
-                        debug_to_log("#{msg} closed successfully with WinKill('#{title}','#{text}').")
-                      end
-                    else
-                      debug_to_log("#{msg} closed successfully with WinClose('#{title}','#{text}').")
-                    end
-                  else
-                    passed_to_log("#{msg} closed successfully.") unless quiet
-                  end
-                else
-                  failed_to_log("#{msg} #{side} click on '#{button}' failed. (#{__LINE__})")
-                end
-              else
-                failed_to_log("#{msg} Unable to gain focus on button (#{__LINE__})")
-              end
-            else
-              failed_to_log("#{msg} Unable to activate (#{__LINE__})")
-            end
-          else
-            failed_to_log("#{msg} did not appear after #{wait} seconds. (#{__LINE__})")
-          end
-        else
-          failed_to_log("#{msg} did not appear after #{wait} seconds. (#{__LINE__})")
-        end
-      rescue
-        failed_to_log("Close popup title=#{title} failed: '#{$!}' (#{__LINE__})")
-      end
-
-      alias close_popup_validate_text close_popup
-
-      def close_popup_by_text(popup, strg = 'Close', desc = '')
+      #def close_modal_ie(title, button = "OK", text = '', side = 'primary', wait = WAIT, desc = '', quiet = false)
+      #  #TODO needs simplifying and debug code cleaned up
+      #  title = translate_popup_title(title)
+      #  msg   = "'#{title}'"
+      #  msg << " with text '#{text}'" if text.length > 0
+      #  msg << " (#{desc})" if desc.length > 0
+      #  @ai.Opt("WinSearchChildren", 1) # Match any substring in the title
+      #  if @ai.WinWait(title, text, wait) > 0
+      #    myHandle  = @ai.WinGetHandle(title, text)
+      #    full_text = @ai.WinGetText(title)
+      #    #debug_to_report("Found popup handle:'#{myHandle}', title:'#{title}', text:'#{full_text}'")
+      #    if myHandle.length > 0
+      #      debug_to_log("hwnd: #{myHandle.inspect}")
+      #      passed_to_log("#{msg} appeared.") unless quiet
+      #      sleep_for(0.5)
+      #      @ai.WinActivate(title, text)
+      #      if @ai.WinActive(title, text) #  > 0   #Hack to prevent fail when windows session locked
+      #        debug_to_log("#{msg} activated.")
+      #        if @ai.ControlFocus(title, text, button) #  > 0
+      #          controlHandle = @ai.ControlGetHandle(title, '', "[CLASS:Button; TEXT:#{button}]")
+      #          if not controlHandle
+      #            button        = "&#{button}"
+      #            controlHandle = @ai.ControlGetHandle(title, '', "[CLASS:Button; TEXT:#{button}]")
+      #          end
+      #          debug_to_log("Handle for button '#{button}': [#{controlHandle}]")
+      #          debug_to_log("#{msg} focus gained.")
+      #          #              sleep_for(2)
+      #          if @ai.ControlClick(title, text, button, side) # > 0
+      #                                                         #            if @ai.ControlClick(title, text, "[Handle:#{controlHandle}]", side) > 0
+      #                                                         #                debug_to_log("#{msg} #{side} click on 'Handle:#{controlHandle}'." )
+      #            debug_to_log("#{msg} #{side} click on '#{button}' successful.")
+      #            sleep_for(1)
+      #            if @ai.WinExists(title, text) > 0
+      #              debug_to_log("#{msg} close popup failed on click '#{button}'. Trying WinClose. (#{__LINE__})")
+      #              @ai.WinClose(title, text)
+      #              if @ai.WinExists(title, text) > 0
+      #                debug_to_log("#{msg} close popup failed with WinClose('#{title}','#{text}'). (#{__LINE__})")
+      #                @ai.WinKill(title, text)
+      #                if @ai.WinExists(title, text) > 0
+      #                  debug_to_log("#{msg} close popup failed with WinKill('#{title}','#{text}'). (#{__LINE__})")
+      #                else
+      #                  debug_to_log("#{msg} closed successfully with WinKill('#{title}','#{text}').")
+      #                end
+      #              else
+      #                debug_to_log("#{msg} closed successfully with WinClose('#{title}','#{text}').")
+      #              end
+      #            else
+      #              passed_to_log("#{msg} closed successfully.") unless quiet
+      #            end
+      #          else
+      #            failed_to_log("#{msg} #{side} click on '#{button}' failed. (#{__LINE__})")
+      #          end
+      #        else
+      #          failed_to_log("#{msg} Unable to gain focus on button (#{__LINE__})")
+      #        end
+      #      else
+      #        failed_to_log("#{msg} Unable to activate (#{__LINE__})")
+      #      end
+      #    else
+      #      failed_to_log("#{msg} did not appear after #{wait} seconds. (#{__LINE__})")
+      #    end
+      #  else
+      #    failed_to_log("#{msg} did not appear after #{wait} seconds. (#{__LINE__})")
+      #  end
+      #rescue
+      #  failed_to_log("Close popup title=#{title} failed: '#{$!}' (#{__LINE__})")
+      #end
+
+      # Close an browser window (popup) by clicking a link within it identified by the *:text* value of the link.
+      # @param [Watir::Browser] popup A reference to the browser window or container element to be closed.
+      # @param [String] what Uniquely identify the *:link* element within the popup by the value in its *:text* attribute.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      def close_popup_by_text(popup, what = 'Close', desc = '')
         count = 0
         url   = popup.url
         if validate(popup, @myName, __LINE__)
-          count = string_count_in_string(popup.text, strg)
+          count = string_count_in_string(popup.text, what)
           if count > 0
-            #        @waiter.wait_until( browser.link(:text, strg).exists? ) if @waiter
             begin
-              popup.link(:text, strg).click
+              popup.link(:text, what).click
             rescue => e
-              if not rescue_me(e, __method__, "link(:text,'#{strg}')", "#{popup.class}")
+              if not rescue_me(e, __method__, "link(:text,'#{what}')", "#{popup.class}")
                 raise e
               end
             end
-            passed_to_log("Popup #{url} closed by clicking link with text '#{strg}'. #{desc}")
+            passed_to_log("Popup #{url} closed by clicking link with text '#{what}'. #{desc}")
             true
           else
-            failed_to_log("Link :text=>'#{strg}' for popup #{url} not found. #{desc}")
+            failed_to_log("Link :text=>'#{what}' for popup #{url} not found. #{desc}")
           end
         end
       rescue
-        failed_to_log("Close popup #{url} with click link :text+>'#{strg}' failed: '#{$!}' (#{__LINE__})")
+        failed_to_log("Close popup #{url} with click link :text+>'#{what}' failed: '#{$!}' (#{__LINE__})")
         debug_to_log("#{strg} appears #{count} times in popup.text.")
         raise
       end
 
-      #  #close a modal dialog
+      # Close a modal dialog.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] title The title of the window to be closed.  Matched from beginning of string.
+      # @param [String] button The display name of the button to be clicked.
+      # @param [String] text The text of the window to be closed.  Matched from beginning of string.
+      # @param [String] side A string identifying which mouse button to click.
+      # @param [Fixnum] wait Number of seconds to wait for the popup to be seen.
       def close_modal(browser, title="", button="OK", text='', side = 'primary', wait = WAIT)
         case @targetBrowser.abbrev
           when 'IE'
@@ -669,16 +696,27 @@ category: Logon
       end
 
     # TODO: Logging
-      def close_modal_c(browser, title)
-        browser.window(:url, title).close
+      # Close a Chrome modal popup by :url.
+      def close_modal_c(browser, url)
+        browser.window(:url, url).close
       end
 
     # TODO: Logging
+      # Close a Safari modal popup by closing the frontmost Safari dialog.  MacOS only
       def close_modal_s
         # simply closes the frontmost Safari dialog
         Appscript.app("Safari").activate; Appscript.app("System Events").processes["Safari"].key_code(52)
       end
 
+      # Close an IE modal popup by its title.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] title The title of the window to be closed.  Matched from beginning of string.
+      # @param [String] button The display name of the button to be clicked.
+      # @param [String] text The text of the window to be closed.  Matched from beginning of string.
+      # @param [String] side A string identifying which mouse button to click.
+      # @param [Fixnum] wait Number of seconds to wait for the popup to be seen.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @param [Boolean] quiet If true, fewer messages and pass/fail validations are logged.
       def close_modal_ie(browser, title="", button="OK", text='', side = 'primary', wait = WAIT, desc = '', quiet = false)
         #TODO needs simplifying, incorporating text verification, and debug code cleaned up
         title = translate_popup_title(title)
@@ -736,9 +774,19 @@ category: Logon
         failed_to_log("Close popup title=#{title} failed: '#{$!}' (#{__LINE__})")
       end
 
+      alias close_popup_validate_text close_modal_ie
+      alias close_popup close_modal_ie
+
       #  private :close_modal_ie
 
-      def close_modal_ff(browser, title="", button=nil, text="", side='')
+      # Close a Firefox modal popup by its title.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] title The title of the window to be closed.  Matched from beginning of string.
+      # @param [String] button The display name of the button to be clicked.
+      # @param [String] text The text of the window to be closed.  Matched from beginning of string.
+      # @param [String] side A string identifying which mouse button to click.
+      # @return [Boolean] True if the modal is successfully closed.
+      def close_modal_ff(browser, title="", button=nil, text='', side='')
         title = translate_popup_title(title)
         msg   = "Modal dialog (popup): title=#{title} button='#{button}' text='#{text}' side='#{side}':"
         modal = browser.modal_dialog(:timeout => WAIT)
@@ -762,6 +810,7 @@ category: Logon
             failed_to_log("#{msg} close failed. (#{__LINE__})")
           else
             passed_to_log("#{msg} closed successfully.")
+            true
           end
         else
           failed_to_log("#{msg} did not appear after #{WAIT} seconds. (#{__LINE__})")
@@ -770,6 +819,15 @@ category: Logon
         failed_to_log("#{msg} Unable to validate modal popup: '#{$!}'. (#{__LINE__})")
       end
 
+      # Wait for a modal popup to appear and then close it.
+      # Used when modal popup in response to browser action is intermittent or unpredictable.
+      # @param [String] title The title of the window to be closed.  Matched from beginning of string.
+      # @param [String] text The text of the window to be closed.  Matched from beginning of string.
+      # @param [String] button The display name of the button to be clicked.
+      # @param [String] side A string identifying which mouse button to click.
+      # @param [Fixnum] wait Number of seconds to wait for the popup to be seen.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Boolean] True if the modal is successfully closed.
       def handle_popup(title, text = '', button= 'OK', side = 'primary', wait = WAIT, desc = '')
         title = translate_popup_title(title)
         msg   = "'#{title}'"
@@ -846,6 +904,12 @@ category: Logon
 
       end
 
+      # Return a reference to an IE browser window based on one of its attributes.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [Symbol] how The element attribute used to identify the window: :url, :title, or :hwnd.
+      # @param [String, Regexp] what A string or a regular expression to be found in the *how* attribute that uniquely identifies the element.
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::IE] A reference to the popup.
       def find_popup(browser, how, what, desc = '')
         msg   = "Find popup :#{how}=>'#{what}'. #{desc}"
         popup = Watir::IE.find(how, what) # TODO: too browser specific
@@ -862,11 +926,13 @@ category: Logon
         failed_to_log("Unable to find popup :#{how}=>'#{what}'. #{desc} '#{$!}' (#{__LINE__})")
       end
 
+      # Confirm that the object passed in *browser* is actually a Browser object.
+      # @param [Watir::Browser] browser A reference to the window or container element to be tested.
       def is_browser?(browser)
         myClass = browser.class.to_s
         case @targetBrowser.abbrev
           when 'IE'
-            myClass =~ /Watir::/i # TODO: should this be /Watir::IE/i ?
+            myClass =~ /Watir::IE|Watir::Browser/i
           when 'FF'
             myClass =~ /Watir::Browser/i
           when 'S'
@@ -878,6 +944,11 @@ category: Logon
 
       alias is_browser is_browser?
 
+      # Translate window title supplied in *title* to a title appropriate for the targeted browser and version
+      # actually being run.
+      # Used primarily for handling of modal popups and dialogs.
+      # This allows cross-browser compatibility for handling modal popups and other windows accessed by titlt.
+      # @param [String] title The title of the window to be closed.
       def translate_popup_title(title)
         new_title = title
         case @browserAbbrev
@@ -943,6 +1014,9 @@ category: Logon
         new_title
       end
 
+      # Identify the exact version of the Browser currently being executed.
+      # @todo Bring up to date with newer browser versions
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
       def get_browser_version(browser)
         debug_to_log("starting get_browser_version")
         case @targetBrowser.abbrev
@@ -1020,45 +1094,48 @@ category: Logon
 
       protected :get_browser_version
 
-      def close_popup_by_button_title(popup, strg, desc = '')
-        click(popup, :link, :title, strg, desc)
-      end
+      #def filter_bailout_from_rescue(err, msg)
+      #  if msg =~ /bailing out/i
+      #    raise err
+      #  else
+      #    error_to_log(msg)
+      #  end
+      #end
 
-      def filter_bailout_from_rescue(err, msg)
-        if msg =~ /bailing out/i
-          raise err
-        else
-          error_to_log(msg)
-        end
-      end
+      # @!group Browser
 
+      # Open and attach a browser popup window where the link to open it and its title contain the same string.
+      # @deprecated
       def open_popup_through_link_title(browser, title, pattern, name)
         click_title(browser, title)
         #TODO need some kind of wait for process here
         sleep_for 2
-        attach_iepopup(browser, pattern, name)
+        attach_popup_by_url(browser, pattern, name)
       rescue
         failed_to_log("Unable to open popup '#{name}': '#{$!}' (#{__LINE__})")
       end
 
-=begin rdoc
-Verifies health of the browser. Looks for common http and system errors that are unrecoverable and
-attempts to gracefully bail out of the script.  Calls rescue_me() when trying to capture the text to filter out
-known false errors and handle container elements that don't respond to the .text method.
-category: bullet-proofing
-tags: system, http, fatal, error
-example: See click()
-related methods: rescue_me()
-=end
-      def validate(browser, fileName = '', lnbr = __LINE__, dbg = false)
+      # @!group Error Handling
+
+      # Verifies health of the browser. Looks for common http and system errors that are unrecoverable and
+      # attempts to gracefully bail out of the script.
+      # Calls rescue_me() when trying to capture the text to filter out known false errors
+      # and handle container elements that don't respond to the .text method.
+      # @param [Watir::Browser] browser A reference to the browser window or container element to be tested.
+      # @param [String] file_name The file name of the executing script.
+      # @param [Fixnum] lnbr Contains a message or description intended to appear in the log and/or report output
+      # @param [Boolean] dbg If set to true additional debug messages are written to the log.
+      #
+      # @return [Boolean] True if no error conditions have been encountered.
+      def validate(browser, file_name = '', lnbr = "#{__LINE__}", dbg = false)
         debug_to_log("#{__method__} begin") if dbg
         msg  = ''
         myOK = true
         if not browser
-          msg  = "#{fileName}----browser is nil object. (#{lnbr})"
+          msg  = "#{file_name}----browser is nil object. (#{lnbr})"
           myOK = false
         elsif not is_browser?(browser)
-          msg = "#{fileName}----not a browser. (#{lnbr})"
+          msg = "#{file_name}----not a browser. (#{lnbr})"
           debug_to_log(browser.inspect)
           myOK = false
 
@@ -1094,94 +1171,94 @@ related methods: rescue_me()
 
           if browser_text
             if browser_text.match(/unrecognized error condition has occurred/i)
-              msg  = "#{fileName}----Unrecognized Exception occurred. (#{lnbr})"
+              msg  = "#{file_name}----Unrecognized Exception occurred. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/cannot find server or dns error/i)
-              msg  = "#{fileName}----Cannot find server error or DNS error. (#{lnbr})"
+              msg  = "#{file_name}----Cannot find server error or DNS error. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/the rpc server is unavailable/i)
-              msg  = "#{fileName}----RPC server unavailable. (#{lnbr})"
+              msg  = "#{file_name}----RPC server unavailable. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/404 not found/i) or
                 browser_text.match(/the page you were looking for does\s*n[o']t exist/i)
-              msg  = "#{fileName}----RFC 2068 HTTP/1.1: 404 URI Not Found. (#{lnbr})"
+              msg  = "#{file_name}----RFC 2068 HTTP/1.1: 404 URI Not Found. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/we're sorry, but something went wrong/i) or
                 browser_text.match(/http status 500/i)
-              msg  = "#{fileName}----RFC 2068 HTTP/1.1: 500 Internal Server Error. (#{lnbr})"
+              msg  = "#{file_name}----RFC 2068 HTTP/1.1: 500 Internal Server Error. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/internet explorer cannot display the webpage/i)
-              msg  = "#{fileName}----Probably RFC 2068 HTTP/1.1: 500 Internal Server Error. (#{lnbr})"
+              msg  = "#{file_name}----Probably RFC 2068 HTTP/1.1: 500 Internal Server Error. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/503.*service unavailable/i)
-              msg  = "#{fileName}----RFC 2068 HTTP/1.1: 503 Service Unavailable. (#{lnbr})"
+              msg  = "#{file_name}----RFC 2068 HTTP/1.1: 503 Service Unavailable. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/java.lang.NullPointerException/i)
-              msg  = "#{fileName}----java.lang.NullPointerException. (#{lnbr})"
+              msg  = "#{file_name}----java.lang.NullPointerException. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/due to unscheduled maintenance/i)
-              msg  = "#{fileName}----Due to unscheduled maintenance. (#{lnbr})"
+              msg  = "#{file_name}----Due to unscheduled maintenance. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/network\s+error\s*(.+)$/i)
               $1.chomp!
-              msg  = "#{fileName}----Network Error #{$1}. (#{lnbr})"
+              msg  = "#{file_name}----Network Error #{$1}. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/warning: page has expired/i)
-              msg  = "#{fileName}----Page using information from form has expired. Not automatically resubmitted. (#{lnbr})"
+              msg  = "#{file_name}----Page using information from form has expired. Not automatically resubmitted. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/no backend server available/i)
-              msg  = "#{fileName}----Cannot Reach Server (#{lnbr})"
+              msg  = "#{file_name}----Cannot Reach Server (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/sign on\s+.+\s+unsuccessful/i)
-              msg  = "#{fileName}----Invalid Id or Password (#{lnbr})"
+              msg  = "#{file_name}----Invalid Id or Password (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/you are not authorized/i)
-              msg  = "#{fileName}----Not authorized to view this page. (#{lnbr})"
+              msg  = "#{file_name}----Not authorized to view this page. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/too many incorrect login attempts have been made/i)
-              msg  = "#{fileName}----Invalid Id or Password. Too many tries. (#{lnbr})"
+              msg  = "#{file_name}----Invalid Id or Password. Too many tries. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/system error\.\s+an error has occurred/i)
-              msg  = "#{fileName}----System Error. An error has occurred. Please try again or call the Help Line for assistance. (#{lnbr})"
+              msg  = "#{file_name}----System Error. An error has occurred. Please try again or call the Help Line for assistance. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/Internal Server failure,\s+NSAPI plugin/i)
-              msg  = "#{fileName}----Internal Server failure, NSAPI plugin. (#{lnbr})"
+              msg  = "#{file_name}----Internal Server failure, NSAPI plugin. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/Error Page/i)
-              msg  = "#{fileName}----Error Page. (#{lnbr})"
+              msg  = "#{file_name}----Error Page. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/The website cannot display the page/i)
-              msg  = "#{fileName}----HTTP 500. (#{lnbr})"
+              msg  = "#{file_name}----HTTP 500. (#{lnbr})"
               myOK = false
 
               #        elsif browser_text.match(/Insufficient Data/i)
-              #          msg  = "#{fileName}----Insufficient Data. (#{lnbr})"
+              #          msg  = "#{file_name}----Insufficient Data. (#{lnbr})"
               #          myOK = false
 
             elsif browser_text.match(/The timeout period elapsed/i)
-              msg  = "#{fileName}----Time out period elapsed or server not responding. (#{lnbr})"
+              msg  = "#{file_name}----Time out period elapsed or server not responding. (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/Unexpected\s+errors*\s+occur+ed\.\s+(?:-+)\s+(.+)/i)
-              msg = "#{fileName}----Unexpected errors occurred. #{$2.slice(0, 120)} (#{lnbr})"
+              msg = "#{file_name}----Unexpected errors occurred. #{$2.slice(0, 120)} (#{lnbr})"
               if not browser_text.match(/close the window and try again/i)
                 myOK = false
               else
@@ -1189,15 +1266,15 @@ related methods: rescue_me()
               end
 
             elsif browser_text.match(/Server Error in (.+) Application\.\s+(?:-+)\s+(.+)/i)
-              msg  = "#{fileName}----Server Error in #{1} Application. #{$2.slice(0, 100)} (#{lnbr})"
+              msg  = "#{file_name}----Server Error in #{1} Application. #{$2.slice(0, 100)} (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/Server Error in (.+) Application\./i)
-              msg  = "#{fileName}----Server Error in #{1} Application. '#{browser_text.slice(0, 250)}...' (#{lnbr})"
+              msg  = "#{file_name}----Server Error in #{1} Application. '#{browser_text.slice(0, 250)}...' (#{lnbr})"
               myOK = false
 
             elsif browser_text.match(/An error has occur+ed\. Please contact support/i)
-              msg  = "#{fileName}----An error has occurred. Please contact support (#{lnbr})"
+              msg  = "#{file_name}----An error has occurred. Please contact support (#{lnbr})"
               myOK = false
 
             end
@@ -1228,6 +1305,55 @@ related methods: rescue_me()
 
       alias validate_browser validate
 
+      # @!endgroup Error Handling
+
+      # @!group Backward compatible usages
+
+      # Returns a reference to a browser window using the window's *:url* attribute. Calls attach_browser().
+      # @example
+      #  mainwindow = open_browser('www.google.com')
+      #  click(mainwindow, :button, :id, 'an id string')  # click a button that opens another browser window
+      #  popup = attach_browser_by_url(mainwindow, '[url of new window]')
+      # @param [Watir::Browser] browser A reference to the current browser window.
+      # @param [String, Regexp] what The value in the targeted attribute that uniquely identifies the new window
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Watir::Browser]
+      def attach_browser_by_url(browser, what, desc = '')
+        attach_browser(browser, :url, what, desc)
+      end
+
+      alias attach_browser_with_url attach_browser_by_url
+
+      # Returns a reference to a new browser window identified by its *:title* attribute.  Used to attach a new browser window to a variable
+      # which can then be passed to methods that require a *browser* parameter. Calls attach_browser().
+      # @param (see #attach_browser_by_url)
+      def attach_popup_by_title(browser, what, desc = '')
+        attach_popup(browser, :title, what, desc)
+      end
+
+      # Returns a reference to a new browser window identified by its *:url* attribute.  Used to attach a new browser window to a variable
+      # which can then be passed to methods that require a *browser* parameter. Calls attach_browser().
+      # @param (see #attach_browser_by_url)
+      def attach_popup_by_url(browser, what, desc = '')
+        attach_popup(browser, :url, what, desc)
+      end
+
+      alias get_popup_with_url attach_popup_by_url
+      alias attach_popup_with_url attach_popup_by_url
+      alias attach_iepopup attach_popup_by_url
+
+      # Close a popup browser window (non-modal) by clicking on a link with :title *what*.
+      # This method does not check to make sure the popup is actually closed.
+      # @param [Watir::Browser] popup A reference to the current popup browser window.
+      # @param [String, Regexp] what The value in the targeted attribute that uniquely identifies the new window
+      # @param [String] desc Contains a message or description intended to appear in the log and/or report output
+      # @return [Boolean] True if the click is successful.
+      def close_popup_by_button_title(popup, what, desc = '')
+        click(popup, :link, :title, what, desc)
+      end
+
+      # @!endgroup Backward
+
 
     end
   end