watir-classic 3.3.0 → 3.4.0

data/CHANGES

@@ -1,3 +1,20 @@
+== 3.4.0 - 2013/01/06
+
+* All deprecated methods will print out warnings.
+* Documentation overhaul - http://rubydoc.info/github/watir/watir-classic/frames
+* Element#flash returns self instead of nil.
+* Fix frame locator in Frame#attach_command (issue #45).
+* Remove :zero_based_indexing option - from now on all index options are starting from zero.
+* Remove global variable $HIDE_IE - use IE.visible= method instead. Support for command line switch -b is also removed.
+* Remove global varialbe $FAST_SPEED - IE.speed= method instead. Support for command line switch -f is also removed.
+* Remove IE#close_all - use browser.windows.each(&:close) instead.
+* Remove IE#close_modal - use browser.modal_dialog.close instead. 
+* Remove IE#close_others - use browser.windows.reject(&:current?).each(&:close) instead.
+* Remove unused ie-new-process.rb.
+* Remove unused PageContainer module.
+* Remove unused PageContainer#check_for_http_error.
+* Remove unused PageContainer#enabled_popup - use browser.modal_dialog instead.
+
 == 3.3.0 - 2012/10/27
 
 * Add support for optional Element#style property argument, which allows to get specific css style attribute value.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    watir-classic (3.2.0)
+    watir-classic (3.3.0)
       ffi (~> 1.0)
       multi_json
       nokogiri
@@ -14,22 +14,23 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    builder (3.1.3)
+    builder (3.1.4)
     childprocess (0.3.4)
       ffi (~> 1.0, >= 1.0.6)
     diff-lcs (1.1.3)
     ffi (1.1.3-x86-mingw32)
-    hoe (3.0.8)
+    hoe (3.3.0)
       rake (~> 0.8)
     mini_magick (3.2.1)
       subexec (~> 0.0.4)
-    multi_json (1.3.6)
+    multi_json (1.3.7)
     nokogiri (1.5.5-x86-mingw32)
     rack (1.4.1)
     rack-protection (1.2.0)
       rack
-    rake (0.9.2.2)
-    rautomation (0.7.2)
+    rake (0.9.4)
+    rautomation (0.7.3)
+      ffi
     rspec (2.11.0)
       rspec-core (~> 2.11.0)
       rspec-expectations (~> 2.11.0)
@@ -63,8 +64,8 @@ GEM
     windows-pr (1.2.2)
       win32-api (>= 1.4.5)
       windows-api (>= 0.3.0)
-    xml-simple (1.1.1)
-    yard (0.8.2.1)
+    xml-simple (1.1.2)
+    yard (0.8.3)
 
 PLATFORMS
   x86-mingw32

data/LICENSE

@@ -2,6 +2,7 @@
 Copyright (c) 2004 - 2006, Paul Rogers
 Copyright (c) 2006 - 2007, Angrez Singh
 Copyright (c) 2004 - 2010, Bret Pettichord
+Copyright (c) 2010 - 2013, Jarmo Pertman
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/README.rdoc

@@ -1,18 +1,17 @@
 = Watir Classic
 
-Watir, pronounced water, is an open-source (BSD) family of Ruby libraries for automating web browsers.
-It supports your app no matter what technology it is developed in.
-They support Internet Explorer on Windows, Firefox and Chrome on Windows, Mac and Linux and Safari on Mac.
+Watir Classic is a Watir[https://github.com/watir/watir] driver for automating Internet Explorer on Windows.
 
 Project Home:: http://watir.com
+Documentation:: http://rubydoc.info/github/watir/watir-classic/frames
 Source Code:: http://github.com/watir/watir-classic
 Support:: http://watir.com/support
 Gem:: https://rubygems.org/gems/watir-classic
 
 == Install
 
-You have to install Ruby and RubyGems first.
-  gem update --system
+Install the gem:
+
   gem install watir-classic
 
 Detailed installation instructions are at http://watir.com/installation
@@ -25,7 +24,7 @@ Loading Watir gem to drive Internet Explorer on Windows
 
   require 'watir-classic'
 
-Starting a new browser & and going to our site
+Starting a new browser & going to our site
 
   browser = Watir::Browser.new
   browser.goto("http://bit.ly/watir-example")
@@ -56,7 +55,7 @@ Clicking a button
 Clearing, getting and selecting selection list values
 
   browser.select_list(:name => "entry.6.single").clear
-  puts browser.select_list(:name => "entry.6.single").options
+  puts browser.select_list(:name => "entry.6.single").options.map(&:text)
   browser.select_list(:name => "entry.6.single").select "Chrome"
 
 Clicking a button

data/Rakefile

@@ -13,7 +13,9 @@ RSpec::Core::RakeTask.new(:rcov) do |spec|
 end
 
 require 'yard'
-YARD::Rake::YardocTask.new
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/watir-classic/yard/global_macros.rb", "lib/**/*.rb"]
+end
 
 #
 # ------------------------------ watirspec -----------------------------------

data/VERSION

@@ -1 +1 @@
-3.3.0
+3.4.0

data/lib/watir-classic.rb

@@ -1,8 +1,3 @@
-#--
-#  The 'watir-classic' library loads the common watir-classic code, common to all watir-classic
-# implementations. The 'watir-classic/browser' library will autoload the actual
-# implementations.
-
 require 'watir-classic/version'
 require 'watir-classic/wait'
 require 'watir-classic/wait_helper'

data/lib/watir-classic/browser.rb

@@ -1,4 +1,3 @@
-# watir-classic/browser
 require 'watir-classic/options'
 module Watir
   
@@ -11,74 +10,82 @@ Watir drives browsers the same way people do. It clicks links, fills in forms,
 presses buttons. Watir also checks results, such as whether expected text 
 appears on a page.
 
-The Watir family currently includes support for Internet Explorer (on Windows),
-Firefox (on Windows, Mac and Linux) and Safari (on Mac). 
+The Watir Classic is a driver for Internet Explorer (on Windows).
 
-Project Homepage: http://wtr.rubyforge.org
+Project Homepage: http://watir.com
 
-This Browser module provides a generic interface
-that tests can use to access any browser. The actual browser (and thus
-the actual Watir driver) is determined at runtime based on configuration
-settings.
+@example usage
 
   require 'watir-classic'
   browser = Watir::Browser.new
   browser.goto 'http://google.com'
-  browser.text_field(:name, 'q').set 'pickaxe'  
-  browser.button(:name, 'btnG').click
+  browser.text_field(:name => 'q').set 'pickaxe'  
+  browser.button(:name => 'btnG').click
   if browser.text.include? 'Programming Ruby'
     puts 'Text was found'
   else
     puts 'Text was not found'
   end
 
-A comprehensive summary of the Watir API can be found here
-http://wiki.openqa.org/display/WTR/Methods+supported+by+Element
-
-There are two ways to configure the browser that will be used by your tests.
-
-One is to set the +watir_browser+ environment variable to +ie+ or +firefox+. 
-(How you do this depends on your platform.)
-
-The other is to create a file that looks like this.
-
-  browser: ie
-
-And then to add this line to your script, after the require statement and 
-before you invoke Browser.new.
-
-  Watir.options_file = 'path/to/the/file/you/just/created'
-
 =end rdoc
   
   class Browser
+    # @private
     @@browser_classes = {}
+
+    # @private
     @@sub_options = {}
+
+    # @private
     @@default = nil
+
     class << self
 
-      # Create a new instance of a browser driver, as determined by the
-      # configuration settings. (Don't be fooled: this is not actually 
-      # an instance of Browser class.)
-      def new ignored=nil # argument is needed to make watir-classic more compatible with watir-webdriver
+      # Create a new instance of the {Browser} object
+      # @param [Object] ignored Argument is only needed to make
+      #   watir-classic more compatible with watir-webdriver and is really ignored.
+      def new(ignored=nil)
         set_sub_options
         klass.new
       end
-      # Create a new instance as with #new and start the browser on the
+
+      # Create a new {Browser} instance as with {.new} and start the browser on the
       # specified url.
-      def start url
+      # @param [String] url Url to start the browser at.
+      def start(url)
         set_sub_options
         klass.start url
       end
-      # Attach to an existing browser.
+
+      # Attach to an existing IE {Browser}.
+      #
+      # @example Attach with full title:
+      #   Watir::Browser.attach(:title, "Full title of IE")
+      #
+      # @example Attach with part of the title using {Regexp}:
+      #   Watir::Browser.attach(:title, /part of the title of IE/)
+      #
+      # @example Attach with part of the url:
+      #   Watir::Browser.attach(:url, /google/)
+      #
+      # @example Attach with window handle:
+      #   Watir::Browser.attach(:hwnd, 123456)
+      #
+      # @param [Symbol] how type of the locator. Can be :title, :url or :hwnd.
+      # @param [Symbol] what value of the locator. Can be {String}, {Regexp} or {Fixnum}
+      #   depending of the type parameter.
       def attach(how, what)
         set_sub_options
         klass.attach(how, what)
       end
-      def set_options options
+      
+      # Set options for the {Browser}.
+      def set_options(options)
         return unless klass.respond_to?(:set_options)
         klass.set_options options
       end
+
+      # @return [Hash] options of the {Browser}.
       def options
         return {} unless klass.respond_to?(:options)
         klass.options
@@ -89,11 +96,14 @@ before you invoke Browser.new.
         eval @@browser_classes[key] # this triggers the autoload
       end
       private :klass
+
       # Add support for the browser option, using the specified class, 
       # provided as a string. Optionally, additional options supported by
       # the class can be specified as an array of symbols. Options specified
       # by the user and included in this list will be passed (as a hash) to 
       # the set_options class method (if defined) before creating an instance.
+      # @todo remove this and autoloading since now only IE is supported.
+      # @private
       def support hash_args
         option = hash_args[:name]
         class_string = hash_args[:class]
@@ -108,26 +118,37 @@ before you invoke Browser.new.
         activate_gem gem, option
       end
       
+      # @private
       def default
         @@default
       end
+
       # Specifies a default browser. Must be specified before options are parsed.
+      # @todo remove this since only IE is supported.
+      # @private
       def default= option
         @@default = option
       end
+
       # Returns the names of the browsers that are supported by this module.
       # These are the options for 'watir_browser' (env var) or 'browser:' (yaml).
+      # @todo remove this since only IE is supported.
+      # @private
       def browser_names
         @@browser_classes.keys
       end      
       
       private
+
+      # @todo remove this since only IE is supported.
       def autoload class_string, library
         mod, klass = class_string.split('::')
         eval "module ::#{mod}; autoload :#{klass}, '#{library}'; end"
       end
+
       # Activate the gem (if installed). The default browser will be set
       # to the first gem that activates.
+      # @todo remove this since only IE is supported.
       def activate_gem gem_name, option
         begin
           gem gem_name 
@@ -135,6 +156,8 @@ before you invoke Browser.new.
         rescue Gem::LoadError
         end
       end
+
+      # @todo remove this since only IE is supported.
       def set_sub_options
         sub_options = @@sub_options[Watir.options[:browser]]
         return if sub_options.nil?

data/lib/watir-classic/browsers.rb

@@ -4,4 +4,4 @@
 
 Watir::Browser.support :name => 'ie', :class => 'Watir::IE', 
   :library => 'watir-classic/ie', :gem => 'watir-classic',
-  :options => [:speed, :visible, :zero_based_indexing]
+  :options => [:speed, :visible]

data/lib/watir-classic/container.rb

@@ -1,5 +1,5 @@
 module Watir
-  # This module contains the factory methods that are used to access most html objects
+  # This module contains the factory methods that are used to access all html objects.
   #
   # For example, to access a button on a web page that has the following html
   #  <input type=button name='b1' value='Click Me' onClick='javascript:doSomething()'>
@@ -12,71 +12,77 @@ module Watir
   #
   #  browser.button(:value, 'Click Me').name
   #
-  # there are many methods available to the Button object
-  #--
-  # Is includable for classes that have @container, document and __ole_inner_elements
+  # there are many methods available to the {Button} object
   module Container
     include Watir::Exception
     
+    # The {Browser} object containing this element.
+    attr_accessor :page_container
+    alias_method :browser, :page_container
+    
     # Note: @container is the container of this object, i.e. the container
     # of this container.
     # In other words, for browser.table().this_thing().text_field().set,
     # container of this_thing is the table.
     
     # This is used to change the typing speed when entering text on a page.
+    # @private
     attr_accessor :typingspeed
+
+    # @private
     attr_accessor :type_keys
+
     # The color we want to use for the active object. This can be any valid web-friendly color.
-    attr_accessor :activeObjectHighLightColor
-    # The PageContainer object containing this element
-    attr_accessor :page_container
-    alias_method :browser, :page_container
-    
-    def copy_test_config(container) # only used by form and frame
-      @typingspeed = container.typingspeed
-      @type_keys = container.type_keys
-      @activeObjectHighLightColor = container.activeObjectHighLightColor
+    # @private
+    attr_accessor :active_object_highlight_color
+
+    # @return [ModalDialog] modal dialog instance.
+    def modal_dialog
+      ModalDialog.new(self)
     end
-    private :copy_test_config
-    
+
+    # Retrieve the JavaScript dialog instance.
+    # Supported dialogs are alert, confirm and prompt.
+    # @return [Alert] JavaScript dialog instance.
+    def alert
+      Alert.new(self)
+    end
+
     # Wait until Browser has finished loading the page.
     #--
     # called explicitly by most click and set methods
+    # @private
     def wait(no_sleep=false)
       @container.wait(no_sleep)
     end
     
-    def set_container container #:nodoc:
+    # @private
+    def set_container(container)
       @container = container 
       @page_container = container.page_container
     end
         
-    public
-
-    def modal_dialog
-      ModalDialog.new(self)
-    end
-
-    def alert
-      Alert.new(self)
-    end
-
     # Searching for Page Elements
     # Not for external consumption
-    #
-    #++
+    # @private
     def __ole_inner_elements
-      return document.body.all
+      document.body.all
     end
     
-    # Locator Methods
-    #
     # Not for external use, but cannot set to private due to usages in Element
     # classes.
-
+    # @private
     def locator_for(locator_class, specifiers, klass)
       locator_class.new self, specifiers, klass
     end
+
+    private
+
+    def copy_test_config(container) # only used by form and frame
+      @typingspeed = container.typingspeed
+      @type_keys = container.type_keys
+      @active_object_high_light_color = container.active_object_highlight_color
+    end
     
-  end # module
+  end
 end