watir-classic 3.3.0 → 3.4.0

data/lib/watir-classic/ie-process.rb

@@ -16,6 +16,7 @@ module Watir
       def initialize process_id
         @process_id = process_id
       end
+
       attr_reader :process_id
       
       def window

data/lib/watir-classic/ie.rb

@@ -1,22 +1,5 @@
 require 'watir-classic'
 require 'watir-classic/core'
-require 'watir-classic/close_all'
 require 'watir-classic/ie-process'
 require 'watir-classic/screenshot'
 require 'multi_json'      
-
-# these switches need to be deleted from ARGV to enable the Test::Unit
-# functionality that grabs
-# the remaining ARGV as a filter on what tests to run.
-# Note: this means that watir-classic must be require'd BEFORE test/unit.
-# (Alternatively, you could require test/unit first and then put the Watir::IE
-# arguments after the '--'.)
-
-# Make Internet Explorer invisible. -b stands for background
-$HIDE_IE ||= ARGV.delete('-b')
-
-# Run fast
-$FAST_SPEED = ARGV.delete('-f')
-
-# Eat the -s command line switch (deprecated)
-ARGV.delete('-s')

data/lib/watir-classic/image.rb

@@ -1,91 +1,50 @@
 module Watir
   
-  # This class is the means of accessing an image on a page.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#image method
-  #
-  # many of the methods available to this object are inherited from the Element class
-  #
+  # Returned by {Container#image}
   class Image < Element
     attr_ole :alt
     attr_ole :src
 
-    # this method produces the properties for an image as an array
-    def image_string_creator
-      n = []
-      n <<   "src:".ljust(TO_S_SIZE) + self.src.to_s
-      n <<   "file date:".ljust(TO_S_SIZE) + self.fileCreatedDate.to_s
-      n <<   "file size:".ljust(TO_S_SIZE) + self.fileSize.to_s
-      n <<   "width:".ljust(TO_S_SIZE) + self.width.to_s
-      n <<   "height:".ljust(TO_S_SIZE) + self.height.to_s
-      n <<   "alt:".ljust(TO_S_SIZE) + self.alt.to_s
-      return n
-    end
-    private :image_string_creator
-    
-    # returns a string representation of the object
-    def to_s
-      assert_exists
-      r = string_creator
-      r += image_string_creator
-      return r.join("\n")
-    end
-    
-    # this method returns the filesize of the image, as an int
+    # @return [Fixnum] file size of the image in bytes.
+    # @macro exists
     def file_size
       assert_exists
       @o.invoke("fileSize").to_i
     end
     
-    # returns the width in pixels of the image, as an int
+    # @return [Fixnum] width of the image in pixels.
+    # @macro exists
     def width
       assert_exists
       @o.invoke("width").to_i
     end
     
-    # returns the height in pixels of the image, as an int
+    # @return [Fixnum] height of the image in pixels.
+    # @macro exists
     def height
       assert_exists
       @o.invoke("height").to_i
     end
     
-    # This method attempts to find out if the image was actually loaded by the web browser.
-    # If the image was not loaded, the browser is unable to determine some of the properties.
-    # We look for these missing properties to see if the image is really there or not.
-    # If the Disk cache is full (tools menu -> Internet options -> Temporary Internet Files), it may produce incorrect responses.
+    # @return [Boolean] true if image is loaded by the browser, false otherwise.
+    # @macro exists
     def loaded?
       assert_exists
       file_size != -1
     end
     
-    # this method highlights the image (in fact it adds or removes a border around the image)
-    #  * set_or_clear   - symbol - :set to set the border, :clear to remove it
-    def highlight(set_or_clear)
-      if set_or_clear == :set
-        begin
-          @original_border = @o.border
-          @o.border = 1
-        rescue
-          @original_border = nil
-        end
-      else
-        begin
-          @o.border = @original_border
-          @original_border = nil
-        rescue
-          # we could be here for a number of reasons...
-        ensure
-          @original_border = nil
-        end
-      end
-    end
-    private :highlight
-    
-    # This method saves the image to the file path that is given.  The
-    # path must be in windows format (c:\\dirname\\somename.gif).  This method
-    # will not overwrite a previously existing image.  If an image already
-    # exists at the given path then a dialog will be displayed prompting
-    # for overwrite.
-    # path - directory path and file name of where image should be saved
+    # Save the image to the file.
+    #
+    # @example
+    #   browser.image.save("c:/foo/bar.jpg")
+    #
+    # @param [String] path path to the file.
+    #
+    # @note This method will not overwrite a previously existing image.
+    #   If an image already exists at the given path then a dialog
+    #   will be displayed prompting for overwrite.
+    #
+    # @todo it should raise an Exception if image already exists.
     def save(path)
       @container.goto(src)
       begin
@@ -95,7 +54,28 @@ module Watir
         @container.back
       end
     end
-    
+
+    def to_s
+      assert_exists
+      r = string_creator
+      r += image_string_creator
+      return r.join("\n")
+    end
+
+    private
+
+    # this method produces the properties for an image as an array
+    def image_string_creator
+      n = []
+      n <<   "src:".ljust(TO_S_SIZE) + self.src.to_s
+      n <<   "file date:".ljust(TO_S_SIZE) + self.fileCreatedDate.to_s
+      n <<   "file size:".ljust(TO_S_SIZE) + self.fileSize.to_s
+      n <<   "width:".ljust(TO_S_SIZE) + self.width.to_s
+      n <<   "height:".ljust(TO_S_SIZE) + self.height.to_s
+      n <<   "alt:".ljust(TO_S_SIZE) + self.alt.to_s
+      return n
+    end
+
     def fill_save_image_dialog(path)
       command = "require 'rubygems';require 'rautomation';" <<
                 "window=::RAutomation::Window.new(:title => 'Save Picture');" <<
@@ -103,7 +83,21 @@ module Watir
                 "window.button(:value => '&Save').click"
       IO.popen("ruby -e \"#{command}\"")
     end
-    private :fill_save_image_dialog
+
+    # Highlight the image (in fact it adds a border around the image).
+    def set_highlight
+      perform_highlight do
+        @original_border = @o.border
+        @o.border = 1
+      end
+    end
+
+    # Clear the highlight of the image (in fact it removes a border around the image).
+    def clear_highlight
+      perform_highlight do
+        @o.border = @original_border if @original_border
+      end
+    end
 
   end
   

data/lib/watir-classic/input_elements.rb

@@ -1,37 +1,41 @@
 module Watir
-  
-  class InputElement < Element #:nodoc:all
-    def locate
-      @o = @container.locator_for(InputElementLocator, @specifiers, self.class).locate
-    end
 
+  # Super-class for input elements like {SelectList}, {Button} etc.
+  class InputElement < Element
     attr_ole :disabled?
     attr_ole :name
     attr_ole :value
     attr_ole :alt
     attr_ole :src
     attr_ole :type
+
+    # @private
+    def locate
+      @o = @container.locator_for(InputElementLocator, @specifiers, self.class).locate
+    end
+
   end
 
-  #
-  # Input: Select
-  #
-  
-  # This class is the way in which select boxes are manipulated.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#select_list method
+  # Returned by {Container#select_list}.
   class SelectList < InputElement
     attr_ole :multiple?
 
-    # This method clears the selected items in the select box
+    # Clear the selected options in the select list.
+    #
+    # @macro exists
+    # @macro enabled
     def clear
       perform_action do
         options.each(&:clear)
       end
     end
 
-    # This method selects an item, or items in a select box, by text.
-    # Raises NoValueFoundException   if the specified value is not found.
-    #  * item   - the thing to select, string or reg exp
+    # Select an item or items in a select box.
+    #
+    # @param [String,Regexp] item option to select by text, label or value.
+    # @raise [NoValueFoundException] when no options found.
+    # @macro exists
+    # @macro enabled
     def select(item)
       matching_options = []
       perform_action do
@@ -43,30 +47,42 @@ module Watir
       end
       matching_options.first.text
     end
-       
-    # Selects an item, or items in a select box, by value.
-    # Raises NoValueFoundException if the specified value is not found.
-    #  * item   - the value of the thing to select, string or reg exp
+
+    # Select an item or items in a select box by option's value.
+    #
+    # @param [String,Regexp] item option to select by value.
+    # @raise [NoValueFoundException] when no options found.
+    # @macro exists
+    # @macro enabled
     def select_value(item)
       matching_options = matching_items_in_select_list(:value, item)
       raise NoValueFoundException, "No option with :value of #{item.inspect} in this select element" if matching_options.empty?
       matching_options.each(&:select)
       matching_options.first.value
     end
-    
-    # Returns array of the selected text items in a select box
-    # Raises UnknownObjectException if the select box is not found.
+
+    # @example Retrieve selected options as a text:
+    #   browser.select_list.selected_options.map(&:text)
+    #
+    # @return [Array<OptionCollection>] array of selected options.
+    # @macro exists
     def selected_options
       options.select(&:selected?)
     end
 
-    # Does the SelectList include the specified option (text)?
-    def include? text_or_regexp
+    # @param [String,Regexp] text_or_regexp option with text to search for.
+    # @return [Boolean] true when option with text includes in select list,
+    #   false otherwise.
+    # @macro exists
+    def include?(text_or_regexp)
       !options.map(&:text).grep(text_or_regexp).empty?
     end
 
-    # Is the specified option (text) selected? Raises exception of option does not exist.
-    def selected? text_or_regexp
+    # @param [String,Regexp] text_or_regexp option with text to search for.
+    # @return [Boolean] true when option with text is selected in select list,
+    #   false otherwise.
+    # @macro exists
+    def selected?(text_or_regexp)
       raise UnknownObjectException, "Option #{text_or_regexp.inspect} not found." unless include? text_or_regexp
       !selected_options.map(&:text).grep(text_or_regexp).empty?
     end
@@ -85,19 +101,29 @@ module Watir
       end
     end
   end
-  
+
+  # Returned by {Container#option}.
   class Option < Element
     attr_ole :disabled?
     attr_ole :name
     attr_ole :value
     attr_ole :label
 
+    # Select the option in its select list.
+    #
+    # @macro exists
+    # @macro enabled
     def select
       perform_action do
         change_selected true unless selected?
       end
     end
 
+    # Clear option in multi-select list.
+    #
+    # @raise [TypeError] when select list is not multi-select.
+    # @macro exists
+    # @macro enabled
     def clear
       raise TypeError, "you can only clear multi-selects" unless select_list.multiple?
 
@@ -106,11 +132,14 @@ module Watir
       end
     end
 
+    # @return [Boolean] true when option is selected, false otherwise.
+    # @macro exists
     def selected?
       assert_exists
       ole_object.selected
     end
 
+    # Text of the option.
     def text
       l = label
       l.empty? ? super : l rescue ''
@@ -135,14 +164,12 @@ module Watir
     end
   end
 
-  # 
-  # Input: Button
-  #
-  
-  # Returned by the Watir::Container#button method
+  # Returned by the {Container#button} method.
   class Button < InputElement
     alias_method :__value, :value
 
+    # @return [String] button contents of value attribute or inner text if there's no value.
+    # @see Element#text
     def text
       val = __value
       val.empty? ? super : val
@@ -151,59 +178,103 @@ module Watir
     alias_method :value, :text
   end
 
-  #
-  # Input: Text
-  #
-  
-  # This class is the main class for Text Fields
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#text_field method
+  # Returned be {Container#text_field}.
   class TextField < InputElement
     attr_ole :size
     attr_ole :readonly?
     alias_method :text, :value
 
-    #:startdoc:
-    
-    # return number of maxlength attribute
+    # @return [Fixnum] value of maxlength attribute.
+    # @macro exists
     def maxlength
-      assert_exists unless @o
+      assert_exists
       begin
         ole_object.invoke('maxlength').to_i
       rescue WIN32OLERuntimeError
         0
       end
     end
-        
-    def text_string_creator
-      n = []
-      n << "length:".ljust(TO_S_SIZE) + self.size.to_s
-      n << "max length:".ljust(TO_S_SIZE) + self.maxlength.to_s
-      n << "read only:".ljust(TO_S_SIZE) + self.readonly?.to_s
-      n
+
+    # @return [String] text field label's text.
+    def label
+      @container.label(:for => name).text
     end
-    private :text_string_creator
-    
-    def to_s
-      assert_exists
-      r = string_creator
-      r += text_string_creator
-      r.join("\n")
+
+    # Clear the contents of the text field.
+    #
+    # @macro exists
+    # @macro enabled
+    # @raise [ObjectReadOnlyException] if the text field is read only.
+    def clear
+      perform_action do
+        assert_not_readonly
+        @o.scrollIntoView
+        @o.focus(0)
+        @o.select(0)
+        dispatch_event("onSelect")
+        @o.value = ""
+        dispatch_event("onKeyPress")
+        dispatch_event("onChange")
+        @container.wait
+      end
     end
-    
-    def assert_not_readonly #:nodoc:
-      if self.readonly?
-        raise ObjectReadOnlyException, 
-          "Textfield #{@specifiers.inspect} is read only."
+
+    # Append the specified text value to the contents of the text field.
+    #
+    # @param [String] value text to append to current text field's value.
+    # @macro exists
+    # @macro enabled
+    # @raise [ObjectReadOnlyException] if the text field is read only.
+    def append(value)
+      perform_action do
+        assert_not_readonly
+        @o.scrollIntoView
+        @o.focus(0)
+        type_by_character(value)
       end
     end
-    
-    # Returns true if the text field contents is matches the specified target,
-    # which can be either a string or a regular expression.
-    #   Raises UnknownObjectException if the object can't be found
-    #--
-    # I vote for deprecating this
-    # we should use text_field().text.include?(some) or text.match(/some/) instead of this method
-    def verify_contains(target) #:nodoc:
+
+    # Sets the contents of the text field to the specified value.
+    #
+    # @param [String] value text to set as value.
+    # @macro exists
+    # @macro enabled
+    # @raise [ObjectReadOnlyException] if the text field is read only.
+    def set(value)
+      perform_action do
+        assert_not_readonly
+        @o.scrollIntoView
+        if type_keys
+          @o.focus(0)
+          @o.select(0)
+          dispatch_event("onSelect")
+          dispatch_event("onKeyPress")
+          @o.value = ""
+          type_by_character(value)
+          dispatch_event("onChange")
+          dispatch_event("onBlur")
+        else
+          @o.value = limit_to_maxlength(value)
+        end
+      end
+    end
+
+    # Sets the value of the text field directly.
+    #
+    # @note it does not cause any JavaScript events to be fired or exceptions
+    #   to be raised. Using {#set} is recommended.
+    #
+    # @param [String] value value to be set.
+    # @macro exists
+    def value=(value)
+      assert_exists
+      @o.value = value.to_s
+    end
+
+    # @deprecated Use "browser.text_field.value.include?(target)" or
+    #   "browser.text_field.value.match(target) instead."
+    def verify_contains(target)
+      Kernel.warn "Deprecated(TextField#verify_contains) - use \"browser.text_field.value.include?(target)\" or \"browser.text_field.value.match(target)\" instead."
       assert_exists
       if target.kind_of? String
         return true if self.value == target
@@ -212,22 +283,20 @@ module Watir
       end
       return false
     end
-    
-    # Drag the entire contents of the text field to another text field
-    #  19 Jan 2005 - It is added as prototype functionality, and may change
-    #   * destination_how   - symbol, :id, :name how we identify the drop target
-    #   * destination_what  - string or regular expression, the name, id, etc of the text field that will be the drop target
+
+    # @deprecated Not part of the WatirSpec API.
     def drag_contents_to(destination_how, destination_what)
+      Kernel.warn "Deprecated(TextField#drag_contents_to) - is not parf ot the WatirSpec API and might be deleted in the future."
       assert_exists
       destination = @container.text_field(destination_how, destination_what)
       unless destination.exists?
         raise UnknownObjectException, "Unable to locate destination using #{destination_how } and #{destination_what } "
       end
-      
+
       @o.focus(0)
       @o.select(0)
       value = self.value
-      
+
       dispatch_event("onSelect")
       dispatch_event("ondragstart")
       dispatch_event("ondrag")
@@ -235,96 +304,37 @@ module Watir
       destination.dispatch_event("onDragEnter")
       destination.dispatch_event("onDragOver")
       destination.dispatch_event("ondrop")
-      
+
       dispatch_event("ondragend")
       destination.value = destination.value + value.to_s
       self.value = ""
     end
-    
-    # Clears the contents of the text box.
-    #   Raises UnknownObjectException if the object can't be found
-    #   Raises ObjectDisabledException if the object is disabled
-    #   Raises ObjectReadOnlyException if the object is read only
-    def clear
-      assert_exists
-      assert_enabled
-      assert_not_readonly
-      
-      highlight(:set)
-      
-      @o.scrollIntoView
-      @o.focus(0)
-      @o.select(0)
-      dispatch_event("onSelect")
-      @o.value = ""
-      dispatch_event("onKeyPress")
-      dispatch_event("onChange")
-      @container.wait
-      highlight(:clear)
-    end
-    
-    # Appends the specified string value to the contents of the text box.
-    #   Raises UnknownObjectException if the object cant be found
-    #   Raises ObjectDisabledException if the object is disabled
-    #   Raises ObjectReadOnlyException if the object is read only
-    def append(value)
-      assert_exists
-      assert_enabled
-      assert_not_readonly
-      
-      highlight(:set)
-      @o.scrollIntoView
-      @o.focus(0)
-      type_by_character(value)
-      highlight(:clear)
-    end
-    
-    # Sets the contents of the text box to the specified text value
-    #   Raises UnknownObjectException if the object cant be found
-    #   Raises ObjectDisabledException if the object is disabled
-    #   Raises ObjectReadOnlyException if the object is read only
-    def set(value)
-      assert_exists
-      assert_enabled
-      assert_not_readonly
-
-      highlight(:set)
-      @o.scrollIntoView
-      if type_keys
-	      @o.focus(0)
-	      @o.select(0)
-	      dispatch_event("onSelect")
-	      dispatch_event("onKeyPress")
-	      @o.value = ""
-	      type_by_character(value)
-	      dispatch_event("onChange")
-	      dispatch_event("onBlur")
-	    else
-				@o.value = limit_to_maxlength(value)
-	    end
-      highlight(:clear)
-    end
 
-    # Sets the value of the text field directly.
-    # It causes no events to be fired or exceptions to be raised,
-    # so generally shouldn't be used.
-    # It is preffered to use the set method.
-    def value=(v)
+    def to_s
       assert_exists
-      @o.value = v.to_s
+      r = string_creator
+      r += text_string_creator
+      r.join("\n")
     end
 
-    def requires_typing #:nodoc:
-    	@type_keys = true
-    	self
+    # @private
+    def requires_typing
+      @type_keys = true
+      self
     end
-    def abhors_typing #:nodoc:
-    	@type_keys = false
-    	self
+
+    # @private
+    def abhors_typing
+      @type_keys = false
+      self
     end
 
-    def label
-      @container.label(:for => name).text
+    # @private
+    def assert_not_readonly
+      if self.readonly?
+        raise ObjectReadOnlyException, 
+          "Textfield #{@specifiers.inspect} is read only."
+      end
     end
 
     private
@@ -342,7 +352,7 @@ module Watir
         dispatch_event("onKeyUp")
       end
     end
-    
+
     # Supports double-byte characters
     def characters_in(value, &blk) 
       if RUBY_VERSION =~ /^1\.8/
@@ -356,7 +366,7 @@ module Watir
         value.each_char(&blk)
       end
     end
-    
+
     # Return the value (a string), limited to the maxlength of the element.
     def limit_to_maxlength(value)
       return value if @o.invoke('type') =~ /textarea/i # text areas don't have maxlength
@@ -366,31 +376,40 @@ module Watir
       value
     end
 
+    def text_string_creator
+      n = []
+      n << "length:".ljust(TO_S_SIZE) + self.size.to_s
+      n << "max length:".ljust(TO_S_SIZE) + self.maxlength.to_s
+      n << "read only:".ljust(TO_S_SIZE) + self.readonly?.to_s
+      n
+    end
+
   end
 
-  # this class can be used to access hidden field objects
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#hidden method
+  # Returned by the {Container#hidden}.
   class Hidden < TextField
-    # set is overriden in this class, as there is no way to set focus to a hidden field
-    def set(n)
-      self.value = n
+    # @see TextField#set
+    def set(value)
+      self.value = value
     end
-    
-    # override the append method, so that focus isnt set to the hidden object
-    def append(n)
-      self.value = self.value.to_s + n.to_s
+
+    # @see TextField#append
+    def append(value)
+      self.value = self.value.to_s + value.to_s
     end
-    
-    # override the clear method, so that focus isnt set to the hidden object
+
+    # @see TextField#clear
     def clear
       self.value = ""
     end
-    
-    # this method will do nothing, as you cant set focus to a hidden field
+
+    # This method will do nothing since it is impossible to set focus to
+    # a hidden field.
     def focus
     end
-    
-    # Hidden element is never visible - returns false.
+
+    # @return [Boolean] always false, since hidden element is never visible.
+    # @macro exists
     def visible?
       assert_exists
       false
@@ -398,7 +417,7 @@ module Watir
   end
 
   # This module contains common methods to both radio buttons and check boxes.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#checkbox or by Watir::Container#radio methods
+  # Normally a user would not need to create this object as it is returned by the {Container#checkbox} or by {Container#radio} methods.
   module RadioCheckCommon
     def self.included(base)
       base.instance_eval do
@@ -411,65 +430,51 @@ module Watir
       '#<%s:0x%x located=%s specifiers=%s value=%s>' % [self.class, hash*2, !!ole_object, @specifiers.inspect, @value.inspect]
     end
   end
-  
-  #--
-  #  this class makes the docs better
-  #++
-  # This class is the watir representation of a radio button.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#radio method
+
+  # Returned by {Container#radio}.
   class Radio < InputElement
     include RadioCheckCommon
-    # This method clears a radio button. One of them will almost always be set.
-    # Returns true if set or false if not set.
-    #   Raises UnknownObjectException if its unable to locate an object
-    #         ObjectDisabledException IF THE OBJECT IS DISABLED
+
+    # Clear a radio button.
+    #
+    # @macro exists
+    # @macro enabled
     def clear
-      assert_exists
-      assert_enabled
-      highlight(:set)
-      @o.checked = false
-      highlight(:clear)
-      highlight(:clear)
-    end
-    
-    # This method sets the radio list item.
-    #   Raises UnknownObjectException  if it's unable to locate an object
-    #         ObjectDisabledException  if the object is disabled
+      perform_action { @o.checked = false }
+    end
+
+    # Check a radio button.
+    #
+    # @macro exists
+    # @macro enabled
     def set
-      assert_exists
-      assert_enabled
-      highlight(:set)
-      @o.scrollIntoView
-      @o.checked = true
-      click
-      highlight(:clear)
+      perform_action do
+        @o.scrollIntoView
+        @o.checked = true
+        click
+      end
     end
 
   end
 
-  # This class is the watir representation of a check box.
-  # Normally a user would not need to create this object as it is returned by the Watir::Container#checkbox method
+  # Returned by the {Watir::Container#checkbox} method.
   class CheckBox < InputElement
     include RadioCheckCommon
-    # This method checks or unchecks the checkbox.
-    # With no arguments supplied it sets the checkbox.
-    # Setting false argument unchecks/clears the checkbox.
-    #   Raises UnknownObjectException if it's unable to locate an object
-    #         ObjectDisabledException if the object is disabled
+
+    # Check or clear the checkbox.
+    # @param [Boolean] value If set to true (default) then checkbox is set, cleared otherwise.
+    # @macro exists
+    # @macro enabled
     def set(value=true)
-      assert_exists
-      assert_enabled
-      highlight :set
-      current_value = @o.checked
-      unless value == current_value
-        click
+      perform_action do
+        current_value = @o.checked
+        click unless value == current_value
       end
-      highlight :clear
     end
-    
-    # Clears a check box.
-    #   Raises UnknownObjectException if its unable to locate an object
-    #         ObjectDisabledException if the object is disabled
+
+    # Clear the checkbox.
+    # @macro exists
+    # @macro enabled
     def clear
       set false
     end