rautomation 0.1.0 → 0.2.0

data/History.rdoc

@@ -1,3 +1,7 @@
+=== Version 0.2.0 / 2010-12-17
+
+* added Window#pid method
+
 === Version 0.1.0 / 2010-12-14
 
 * added new default adapter for Windows: FFI

data/README.rdoc

@@ -5,14 +5,14 @@
 
 == DESCRIPTION
 
-RAutomation tries to be a small and easy to use library for helping out to automate windows and their controls
+RAutomation is a small and easy to use library for helping out to automate windows and their controls
 for automated testing.
 
-RAutomation aims to provide:
-* Easy to use and user-friendly API (inspired by Watir http://www.watir.com).
+RAutomation provides:
+* Easy to use and user-friendly API (inspired by Watir http://www.watir.com)
 * Cross-platform compatibility
-* Easy extensibility - have some application, which uses some specialized technology, but isn't supported by RAutomation?
-  You can get dirty and create a new adapter for RAutomation right away!
+* Easy extensibility - with small scripting effort it's possible to add support for not yet
+  supported platforms or technologies
 
 == USAGE
 
@@ -30,16 +30,17 @@ RAutomation aims to provide:
     button.click
 
     window2 = RAutomation::Window.new(:title => "Other Title", :adapter => :autoit) # use AutoIt adapter
-    window2.WinClose("[TITLE:Other Title]") # use adapter's (in this case AutoIt's) internal methods directly
+    # use adapter's (in this case AutoIt's) internal methods not part of the public API directly
+    window2.WinClose("[TITLE:Other Title]")
 
-See more examples in spec directory!
+Check out the documentation for other possible usages!
 
 == INSTALL
 
 === Windows
 
 1. gem install rautomation
-2. create some script and run it
+2. create script and run it
 
 Available adapters:
 * :ffi - uses Windows API directly with FFI (default)
@@ -51,18 +52,32 @@ You might need administrative privileges if running for the first time and you h
 === Linux
 
 Feel yourself at home on Linux and know how to automate windows and their controls? I would be happy if you'd contact me
-about that matter - or even better, send me a pull request!
+about that matter - or even better, follow the instructions at "How to create a new adapter?" 
 
 === OS X
 
 Feel yourself at home on OS X and know how to automate windows and their controls? I would be happy if you'd contact me
-about that matter - or even better, send me a pull request!
+about that matter - or even better, follow the instructions at "How to create a new adapter?"
 
 === Others
 
 Feel yourself at home on some operating system not listed in here and know how to automate windows and their controls?
 Does Ruby also work on that operating system? I would be happy if you'd contact me
-about that matter - or even better, send me a pull request!
+about that matter - or even better, follow the instructions at "How to create a new adapter?"
+
+== How to create a new adapter?
+
+1. Fork the project.
+2. Create entry point file to lib/rautomation/adapter which should load all adapter specific files.
+3. Add `autoload` statement into lib/rautomation/adapter/helper.rb for that file.
+4. Copy button.rb, text_field.rb and window.rb from some of the existing adapter's directory.
+5. Add spec data for your adapter into spec/spec_helper DATA constant.
+6. Use environment variable __RAUTOMATION_ADAPTER__ to point to that adapter.
+7. Start coding and spec-ing.
+
+Don't forget to fix the documentation for that adapter also!
+
+In case of any problems, feel free to contact me.
 
 == Note on Patches/Pull Requests
  

data/Rakefile

@@ -6,14 +6,14 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "rautomation"
     gem.summary = %Q{Automate windows and their controls through user-friendly API with Ruby}
-    gem.description = %Q{RAutomation tries to be a small and easy to use library for helping out to automate windows and their controls
+    gem.description = %Q{RAutomation is a small and easy to use library for helping out to automate windows and their controls
 for automated testing.
 
-RAutomation aims to provide:
-* Easy to use and user-friendly API (inspired by Watir http://www.watir.com).
+RAutomation provides:
+* Easy to use and user-friendly API (inspired by Watir http://www.watir.com)
 * Cross-platform compatibility
-* Easy extensibility - have some application, which uses some specialized technology, but isn't supported by RAutomation?
-  You can get dirty and create a new adapter for RAutomation!}
+* Easy extensibility - with small scripting effort it's possible to add support for not yet
+  supported platforms or technologies}
     gem.email = "jarmo.p@gmail.com"
     gem.homepage = "http://github.com/jarmo/RAutomation"
     gem.authors = ["Jarmo Pertman"]

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/rautomation/adapter/autoit/button.rb

@@ -5,6 +5,7 @@ module RAutomation
         include WaitHelper
         include Locators
 
+        # @private
         # Special-cased locators
         LOCATORS = {
                 [:class, Regexp] => :regexpclass,
@@ -12,13 +13,22 @@ module RAutomation
                 :value => :text
         }
 
-        # Possible locators are :value, :id, :class and :index.
+        # Creates the button object.
+        # @note this method is not meant to be accessed directly, but only through {RAutomation::Window#button}!
+        # @param [RAutomation::Window] window this button belongs to.
+        # @param [Hash] locators for searching the button.
+        # @option locators [String, Regexp] :value Value (text) of the button
+        # @option locators [String, Regexp] :class Internal class name of the button
+        # @option locators [String, Fixnum] :id Internal ID of the button
+        # @option locators [String, Fixnum] :index 0-based index to specify n-th button if all other criteria match
+        # @see RAutomation::Window#button
         def initialize(window, locators)
           @window = window
           extract(locators)
         end
 
-        def click #:nodoc:
+        # @see RAutomation::Button#click 
+        def click
           clicked = false
           wait_until do
             @window.activate
@@ -31,11 +41,13 @@ module RAutomation
           end
         end
 
-        def value #:nodoc:
+        # @see RAutomation::Button#value
+        def value
           Window.autoit.ControlGetText(@window.locator_hwnd, "", @locators)
         end
 
-        def exists? #:nodoc:
+        # @see RAutomation::Button#exists?
+        def exists?
           not Window.autoit.ControlGetHandle(@window.locator_hwnd, "", @locators).empty?
         end
       end

data/lib/rautomation/adapter/autoit/locators.rb

@@ -1,11 +1,12 @@
 module RAutomation
   module Adapter
     module Autoit
+      # @private
       module Locators
 
         private
 
-        def extract(locators) #:nodoc:
+        def extract(locators)
           @locators = "[#{locators.map do |locator, value|
             locator_key = self.class::LOCATORS[locator] || self.class::LOCATORS[[locator, value.class]]
             value = value.to_i + 1 if locator == :index # use 0-based indexing

data/lib/rautomation/adapter/autoit/text_field.rb

@@ -5,19 +5,30 @@ module RAutomation
         include WaitHelper
         include Locators
 
+        # @private
         # Special-cased locators
         LOCATORS = {
                 [:class, Regexp] => :regexpclass,
-                :index => :instance
+                :index => :instance,
+                :value => :text
         }
 
-        # Possible locators are :id, :class and :index.
+        # Creates the text field object.
+        # @note this method is not meant to be accessed directly, but only through {RAutomation::Window#text_field}!
+        # @param [RAutomation::Window] window this text field belongs to.
+        # @param [Hash] locators for searching the text field.
+        # @option locators [String, Regexp] :class Internal class name of the text field
+        # @option locators [String, Regexp] :value Value (text) of the text field
+        # @option locators [String, Fixnum] :id Internal ID of the text field
+        # @option locators [String, Fixnum] :index 0-based index to specify n-th text field if all other criteria match
+        # @see RAutomation::Window#text_field
         def initialize(window, locators)
           @window = window
           extract(locators)
         end
 
-        def set(text) #:nodoc:
+        # @see RAutomation::TextField#set
+        def set(text)
           wait_until do
             @window.activate
             @window.active? &&
@@ -27,15 +38,18 @@ module RAutomation
           end
         end
 
-        def clear #:nodoc:
+        # @see RAutomation::TextField#clear
+        def clear
           set ""
         end
 
-        def value #:nodoc:
+        # @see RAutomation::TextField#value
+        def value
           Window.autoit.ControlGetText(@window.locator_hwnd, "", @locators)
         end
 
-        def exists? #:nodoc:
+        # @see RAutomation::TextField#exists?
+        def exists?
           not Window.autoit.ControlGetHandle(@window.locator_hwnd, "", @locators).empty?
         end
       end

data/lib/rautomation/adapter/autoit/window.rb

@@ -6,11 +6,13 @@ module RAutomation
         include Locators
 
         class << self
-          def autoit #:nodoc:
+          # @private
+          def autoit
             @@autoit
           end
 
-          def load_autoit #:nodoc:
+          # @private
+          def load_autoit
             @@autoit = WIN32OLE.new('AutoItX3.Control')
           rescue WIN32OLERuntimeError
             dll = File.dirname(__FILE__) + "/../../../../ext/AutoItX/AutoItX3.dll"
@@ -22,8 +24,10 @@ module RAutomation
         load_autoit
         @@autoit.AutoItSetOption("WinWaitDelay", 350)
 
+        # Locators of the window.
         attr_reader :locators
 
+        # @private
         # Special-cased locators
         LOCATORS = {
                 [:title, Regexp] => :regexptitle,
@@ -31,69 +35,95 @@ module RAutomation
                 :hwnd => :handle
         }
 
-        # Possible locators are :title, :text, :hwnd, :class and :index.
+        # Creates the window object.
+        # @note this method is not meant to be accessed directly, but only through {RAutomation::Window#initialize}!
+        # @param [Hash] locators for searching the window.
+        # @option locators [String, Regexp] :title Title of the window
+        # @option locators [String, Regexp] :text Visible text of the window
+        # @option locators [String, Regexp] :class Internal class name of the window
+        # @option locators [String, Fixnum] :hwnd Window handle in decimal format
+        # @option locators [String, Fixnum] :index 0-based index to specify n-th window if all other criteria match
+        # @see RAutomation::Window#initialize
         def initialize(locators)
           @hwnd = locators[:hwnd]
           @locator_text = locators.delete(:text)
           extract(locators)
         end
 
-        # Returns handle of the found window.
-        # Searches only for visible windows with having some text at all.
-        def hwnd #:nodoc:
+        # Retrieves handle of the window.
+        # @note Searches only for visible windows with having some text at all.
+        # @see RAutomation::Window#hwnd
+        def hwnd
           @hwnd ||= @@autoit.WinList(@locators, @locator_text).pop.compact.
                   find {|handle| w = self.class.new(:hwnd => handle.hex); w.visible? && !w.text.empty?}.
                   hex rescue nil
         end
 
-        def title #:nodoc:
+        # @see RAutomation::Window#pid
+        def pid
+          @@autoit.WinGetProcess(hwnd)
+        end
+
+        # @see RAutomation::Window#title
+        def title
           @@autoit.WinGetTitle(locator_hwnd)
         end
 
-        def activate #:nodoc:
+        # @see RAutomation::Window#activate
+        def activate
           @@autoit.WinWait(locator_hwnd, "", 1)
           @@autoit.WinActivate(locator_hwnd)
           sleep 1
         end
 
-        def active? #:nodoc:
+        # @see RAutomation::Window#active?
+        def active?
           @@autoit.WinActive(locator_hwnd) == 1
         end
 
-        def text #:nodoc:
+        # @see RAutomation::Window#text
+        def text
           @@autoit.WinGetText(locator_hwnd)
         end
 
-        def exists? #:nodoc:
+        # @see RAutomation::Window#exists?
+        def exists?
           @@autoit.WinExists(locator_hwnd) == 1
         end
 
-        def visible? #:nodoc:
+        # @see RAutomation::Window#visible?
+        def visible?
           @@autoit.WinGetState(locator_hwnd) & 2 == 2
         end
 
-        def maximize #:nodoc:
+        # @see RAutomation::Window#maximize
+        def maximize
           @@autoit.WinSetState(locator_hwnd, "", @@autoit.SW_MAXIMIZE)
           sleep 1
         end
 
-        def minimize #:nodoc:
+        # @see RAutomation::Window#minimize
+        def minimize
           @@autoit.WinSetState(locator_hwnd, "", @@autoit.SW_MINIMIZE)
           sleep 1
         end
 
-        def minimized? #:nodoc:
+        # @see RAutomation::Window#minimized?
+        def minimized?
           @@autoit.WinGetState(locator_hwnd) & 16 == 16
         end
 
-        def restore #:nodoc:
+        # @see RAutomation::Window#restore
+        def restore
           @@autoit.WinSetState(locator_hwnd, "", @@autoit.SW_RESTORE)
           sleep 1
         end
 
-        # Activates the Window and sends keys to it.
+        # Activates the window and sends keys to it.
         #
-        # Refer to AutoIt documentation for keys syntax.
+        # Refer to AutoIt documentation at http://www.autoitscript.com/autoit3/docs/appendix/SendKeys.htm
+        # for keys syntax.
+        # @see RAutomation::Window#send_keys
         def send_keys(keys)
           wait_until do
             activate
@@ -102,24 +132,32 @@ module RAutomation
           @@autoit.Send(keys)
         end
 
-        def close #:nodoc:
+        # @see RAutomation::Window#close
+        def close
           @@autoit.WinClose(locator_hwnd)
           @@autoit.WinKill(locator_hwnd)
         end
 
-        def button(locator) #:nodoc:
+        # @see Button#initialize
+        # @see RAutomation::Window#button
+        def button(locator)
           Button.new(self, locator)
         end
 
-        def text_field(locator) #:nodoc:
+        # @see TextField#initialize
+        # @see RAutomation::Window#text_field
+        def text_field(locator)
           TextField.new(self, locator)
         end
 
-        def method_missing(name, *args) #:nodoc:
+        # Redirects all method calls not part of the public API to the AutoIt directly.
+        # @example execute AutoIt's WinGetTitle function:
+        #   RAutomation::Window.new(:hwnd => 123456).WinGetTitle(...)
+        # @see RAutomation::Window#method_missing
+        def method_missing(name, *args)
           @@autoit.send(name, *args)
         end
 
-        # Used internally.
         # @private
         def locator_hwnd
           "[HANDLE:#{hwnd.to_i.to_s(16)}]"

data/lib/rautomation/adapter/ffi/button.rb

@@ -5,13 +5,22 @@ module RAutomation
         include WaitHelper
         include Locators
 
-        # Possible locators are :value, :id, :class and :index.
+        # Creates the button object.
+        # @note this method is not meant to be accessed directly, but only through {RAutomation::Window#button}!
+        # @param [RAutomation::Window] window this button belongs to.
+        # @param [Hash] locators for searching the button.
+        # @option locators [String, Regexp] :value Value (text) of the button
+        # @option locators [String, Regexp] :class Internal class name of the button
+        # @option locators [String, Fixnum] :id Internal ID of the button
+        # @option locators [String, Fixnum] :index 0-based index to specify n-th button if all other criteria match
+        # @see RAutomation::Window#button
         def initialize(window, locators)
           @window = window
           extract(locators)
         end
 
-        def click #:nodoc:
+        # @see RAutomation::Button#click
+        def click
           clicked = false
           wait_until do
             hwnd = Functions.control_hwnd(@window.hwnd, @locators)
@@ -24,11 +33,13 @@ module RAutomation
           end
         end
 
-        def value #:nodoc:
+        # @see RAutomation::Button#value
+        def value
           Functions.control_value(Functions.control_hwnd(@window.hwnd, @locators))
         end
 
-        def exists? #:nodoc:
+        # @see RAutomation::Button#exists?
+        def exists?
           !!Functions.control_hwnd(@window.hwnd, @locators)
         end
 

data/lib/rautomation/adapter/ffi/constants.rb

@@ -1,6 +1,7 @@
 module RAutomation
   module Adapter
     module Ffi
+      # @private
       module Constants
         WM_GETTEXT = 0xD
         WM_SETTEXT = 0xC
@@ -20,10 +21,6 @@ module RAutomation
         BM_CLICK = 0xF5
 
         # keybd_event constants
-        # http://msdn.microsoft.com/en-us/library/ms646304(VS.85).aspx
-        #
-        # keycodes themselves are at:
-        # http://msdn.microsoft.com/en-us/library/dd375731(v=VS.85).aspx
         KEYEVENTF_EXTENDEDKEY = 0x1
         KEYEVENTF_KEYUP = 0x2
       end

data/lib/rautomation/adapter/ffi/functions.rb

@@ -1,6 +1,7 @@
 module RAutomation
   module Adapter
     module Ffi
+      # @private
       module Functions
         extend FFI::Library
 
@@ -88,6 +89,12 @@ module RAutomation
             end
           end
 
+          def window_pid(hwnd)
+            pid = FFI::MemoryPointer.new :int
+            window_thread_process_id(hwnd, pid)
+            pid.read_int
+          end
+
           def window_class(hwnd)
             class_name = FFI::MemoryPointer.new :char, 512
             _window_class(hwnd, class_name, 512)
@@ -102,9 +109,7 @@ module RAutomation
                                           0, nil, Constants::SMTO_ABORTIFHUNG, 1000, nil)
             # force it to close
             unless closed
-              pid = FFI::MemoryPointer.new :int
-              window_thread_process_id(hwnd, pid)
-              process_hwnd = open_process(Constants::PROCESS_ALL_ACCESS, false, pid.read_int)
+              process_hwnd = open_process(Constants::PROCESS_ALL_ACCESS, false, window_pid(hwnd))
               terminate_process(process_hwnd, 0)
               close_handle(process_hwnd)
             end

data/lib/rautomation/adapter/ffi/locators.rb

@@ -1,13 +1,19 @@
 module RAutomation
   module Adapter
     module Ffi
+      # @private
       module Locators
 
         private
 
-        def extract(locators) #:nodoc:
-          locators[:id] = locators[:id].to_i if locators[:id]
+        def extract(locators)
+          # windows locators
+          @hwnd = locators[:hwnd].to_i if locators[:hwnd]
+          locators[:pid] = locators[:pid].to_i if locators[:pid]
           locators[:index] = locators[:index].to_i if locators[:index]
+
+          # control locator
+          locators[:id] = locators[:id].to_i if locators[:id]
           @locators = locators
         end
       end

data/lib/rautomation/adapter/ffi/text_field.rb

@@ -5,13 +5,22 @@ module RAutomation
         include WaitHelper
         include Locators
 
-        # Possible locators are :id, :class and :index.
+        # Creates the text field object.
+        # @note this method is not meant to be accessed directly, but only through {RAutomation::Window#text_field}!
+        # @param [RAutomation::Window] window this text field belongs to.
+        # @param [Hash] locators for searching the text field.
+        # @option locators [String, Regexp] :class Internal class name of the text field
+        # @option locators [String, Regexp] :value Value (text) of the text field
+        # @option locators [String, Fixnum] :id Internal ID of the text field
+        # @option locators [String, Fixnum] :index 0-based index to specify n-th text field if all other criteria match
+        # @see RAutomation::Window#text_field
         def initialize(window, locators)
           @window = window
           extract(locators)
         end
 
-        def set(text) #:nodoc:
+        # @see RAutomation::TextField#set
+        def set(text)
           wait_until do
             hwnd = Functions.control_hwnd(@window.hwnd, @locators)
             @window.activate
@@ -22,15 +31,18 @@ module RAutomation
           end
         end
 
-        def clear #:nodoc:
+        # @see RAutomation::TextField#clear
+        def clear
           set ""
         end
 
-        def value #:nodoc:
+        # @see RAutomation::TextField#value
+        def value
           Functions.control_value(Functions.control_hwnd(@window.hwnd, @locators))
         end
 
-        def exists? #:nodoc:
+        # @see RAutomation::TextField#exists?
+        def exists?
           !!Functions.control_hwnd(@window.hwnd, @locators)
         end
 

data/lib/rautomation/adapter/ffi/window.rb

@@ -5,71 +5,100 @@ module RAutomation
         include WaitHelper
         include Locators
 
+        # Locators of the window.
         attr_reader :locators
 
-        # Possible locators are :title, :text, :hwnd and :class.
+        # Possible locators are :title, :text, :hwnd, :pid, :class and :index.
+
+        # Creates the window object.
+        # @note this method is not meant to be accessed directly, but only through {RAutomation::Window#initialize}!
+        # @param [Hash] locators for searching the window.
+        # @option locators [String, Regexp] :title Title of the window
+        # @option locators [String, Regexp] :text Visible text of the window
+        # @option locators [String, Regexp] :class Internal class name of the window
+        # @option locators [String, Fixnum] :hwnd Window handle in decimal format
+        # @option locators [String, Fixnum] :pid Window process ID (PID)
+        # @option locators [String, Fixnum] :index 0-based index to specify n-th window if all other criteria match
+        #   all other criteria match
+        # @see RAutomation::Window#initialize
         def initialize(locators)
-          @hwnd = locators.delete(:hwnd)
           extract(locators)
         end
 
-        # Returns handle of the found window.
-        # Searches only for visible windows with having some text at all.
-        def hwnd #:nodoc:
+        # Retrieves handle of the window.
+        # @note Searches only for visible windows with having some text at all.
+        # @see RAutomation::Window#hwnd
+        def hwnd
           @hwnd ||= Functions.window_hwnd(@locators)
         end
 
-        def title #:nodoc:
+        # @see RAutomation::Window#pid
+        def pid
+          Functions.window_pid(hwnd)
+        end
+
+        # @see RAutomation::Window#title
+        def title
           Functions.window_title(hwnd)
         end
 
-        def activate #:nodoc:
+        # @see RAutomation::Window#activate
+        def activate
           return if !exists? || active?
           restore if minimized?
           Functions.activate_window(hwnd)
           sleep 1
         end
 
-        def active? #:nodoc:
+        # @see RAutomation::Window#active?
+        def active?
           exists? && Functions.foreground_window == hwnd
         end
 
-        def text #:nodoc:
+        # @see RAutomation::Window#text
+        def text
           Functions.window_text(hwnd)
         end
 
-        def exists? #:nodoc:
+        # @see RAutomation::Window#exists?
+        def exists?
           result = hwnd && Functions.window_exists(hwnd)
           !!result
         end
 
-        def visible? #:nodoc:
+        # @see RAutomation::Window#visible?
+        def visible?
           Functions.window_visible(hwnd)
         end
 
-        def maximize #:nodoc:
+        # @see RAutomation::Window#maximize
+        def maximize
           Functions.show_window(hwnd, Constants::SW_MAXIMIZE)
           sleep 1
         end
 
-        def minimize #:nodoc:
+        # @see RAutomation::Window#minimize
+        def minimize
           Functions.show_window(hwnd, Constants::SW_MINIMIZE)
           sleep 1
         end
 
-        def minimized? #:nodoc:
+        # @see RAutomation::Window#minimized?
+        def minimized?
           Functions.minimized(hwnd)
         end
 
-        def restore #:nodoc:
+        # @see RAutomation::Window#restore
+        def restore
           Functions.show_window(hwnd, Constants::SW_RESTORE)
           sleep 1
         end
 
-        # Activates the Window and sends keys to it.
+        # Activates the window and sends keys to it.
         #
         # Refer to MSDN documentation at http://msdn.microsoft.com/en-us/library/dd375731(v=VS.85).aspx
-        # for keycodes.
+        # for the keycodes.
+        # @see RAutomation::Window#send_keys
         def send_keys(*keys)
           keys.each do |key|
             wait_until do
@@ -81,21 +110,29 @@ module RAutomation
           end
         end
 
-        def close #:nodoc:
+        # @see RAutomation::Window#close
+        def close
           Functions.close_window(hwnd)
         end
 
-        def button(locator) #:nodoc:
+        # @see Button#initialize
+        # @see RAutomation::Window#button
+        def button(locator)
           Button.new(self, locator)
         end
 
-        def text_field(locator) #:nodoc:
+        # @see TextField#initialize
+        # @see RAutomation::Window#text_field
+        def text_field(locator)
           TextField.new(self, locator)
         end
 
-        def method_missing(name, *args) #:nodoc:
+        # Redirects all method calls not part of the public API to the {Functions} directly.
+        # @see RAutomation::Window#method_missing
+        def method_missing(name, *args)
           Functions.respond_to?(name) ? Functions.send(name, *args) : super
         end
+
       end
     end
   end

data/lib/rautomation/adapter/helper.rb

@@ -7,6 +7,7 @@ module RAutomation
       extend self
 
       # @private
+      # Retrieves default {Adapter} for the current platform.
       def default_adapter
         case RUBY_PLATFORM
           when /mswin|msys|mingw32/

data/lib/rautomation/button.rb

@@ -1,29 +1,30 @@
 module RAutomation
   class Button
-    # This constructor is meant to be accessed only through RAutomation::Window#button method.
-    def initialize(window, locators) #:nodoc:
+    # @private
+    # This constructor is meant to be accessed only through {Window#button} method.
+    def initialize(window, locators)
       @window = window
       @locators = locators
       @button = @window.button(@locators)
     end
 
     # Performs a click on the Button.
-    #
-    # Raises an UnknownButtonException if the Button itself doesn't exist.
+    # @raise [UnknownButtonException] if the button doesn't exist.
     def click
       wait_until_exists
       @button.click
     end
 
-    # Retrieves the value of the Button, usually the visible text.
-    #
-    # Raises an UnknownButtonException if the Button itself doesn't exist.
+    # Retrieves the value (text) of the button, usually the visible text.
+    # @return [String] the value (text) of the button.
+    # @raise [UnknownButtonException] if the button doesn't exist.
     def value
       wait_until_exists
       @button.value
     end
 
-    # Returns true if Button exists, false otherwise.
+    # Checks if the button exists.
+    # @return [Boolean] true if button exists, false otherwise.
     def exists?
       @button.exists?
     end

data/lib/rautomation/text_field.rb

@@ -1,37 +1,38 @@
 module RAutomation
   class TextField
-    # This constructor is meant to be accessed only through RAutomation::Window#text_field method.
+    # @private
+    # This constructor is meant to be accessed only through {Window#text_field} method.
     def initialize(window, locators) #:nodoc:
       @window = window
       @locators = locators
       @text_field = @window.text_field(@locators)
     end
 
-    # Sets TextField's text to +text+.
-    #
-    # Raises an UnknownTextFieldException if the TextField itself doesn't exist.
+    # Sets text of the text field.
+    # @param [String] text of the field to set.
+    # @raise [UnknownTextFieldException] if the text field doesn't exist.
     def set(text)
       wait_until_exists
       @text_field.set(text)
     end
 
-    # Clears TextField's text.
-    #
-    # Raises an UnknownTextFieldException if the TextField itself doesn't exist.
+    # Clears text field's text.
+    # @raise [UnknownTextFieldException] if the text field doesn't exist.
     def clear
       wait_until_exists
       @text_field.clear
     end
 
-    # Returns TextField's text.
-    #
-    # Raises an UnknownTextFieldException if the TextField itself doesn't exist.
+    # Returns text field's current value (text).
+    # @return [String] the value (text) of the text field.
+    # @raise [UnknownTextFieldException] if the text field doesn't exist.
     def value
       wait_until_exists
       @text_field.value
     end
 
-    # Returns true if TextField exists, false otherwise.
+    # Checks if the text field exists.
+    # @return [Boolean] true if text field exists, false otherwise.
     def exists?
       @text_field.exists?
     end

data/lib/rautomation/wait_helper.rb

@@ -1,13 +1,13 @@
 module RAutomation
+  # Waiting with timeout
   module WaitHelper
     extend self
     
     class TimeoutError < StandardError
     end
 
-    #
+    # @private
     # Wait until the block evaluates to true or times out.
-    #
     def wait_until(timeout = 60, &block)
       end_time = ::Time.now + timeout
 

data/lib/rautomation/window.rb

@@ -9,173 +9,181 @@ module RAutomation
   class Window
     include Adapter::Helper
 
+    # Currently used {Adapter}.
     attr_reader :adapter
 
-    # Creates a new Window object using the _locators_ Hash parameter.
+    # Creates the window object.
     #
-    # Possible Window _locators_ may depend of the used platform and adapter, but
+    # Possible window _locators_ may depend of the used platform and adapter, but
     # following examples will use :title, :class and :hwnd.
     #
-    # Use window with _some title_ being part of it's title:
+    # @example Use window with some title:
     #   RAutomation::Window.new(:title => "some title")
     #
-    # Use window with Regexp title:
+    # @example Use window with Regexp title:
     #   RAutomation::Window.new(:title => /some title/i)
     #
-    # Use window with handle _123456_:
+    # @example Use window with handle (hwnd):
     #   RAutomation::Window.new(:hwnd => 123456)
     #
-    # It is possible to use multiple locators together where every locator will be matched (AND-ed) to the window:
+    # @example Use multiple locators, every locator will be matched (AND-ed) to the window:
     #   RAutomation::Window.new(:title => "some title", :class => "IEFrame")
     #
-    # Refer to all possible locators in each adapter's documentation.
+    # @note Refer to all possible _locators_ in each {Adapter} documentation.
     #
     # _locators_ may also include a key called :adapter to change default adapter,
     # which is dependent of the platform, to automate windows and their controls.
     #
-    # It is also possible to change default adapter by using environment variable:
-    # <em>RAUTOMATION_ADAPTER</em>
+    # It is also possible to change the default adapter by using environment variable called
+    # __RAUTOMATION_ADAPTER__
     #
-    # * Object creation doesn't check for window's existence.
-    # * Window to be searched for has to be visible!
+    # @note This constructor doesn't ensure window's existance.
+    # @note Window to be searched for has to be visible.
+    # @param [Hash] locators for the window.
     def initialize(locators)
       @adapter = locators.delete(:adapter) || ENV["RAUTOMATION_ADAPTER"] && ENV["RAUTOMATION_ADAPTER"].to_sym || default_adapter
       @window = Adapter.const_get(normalize(@adapter)).const_get(:Window).new(locators)
     end
 
     class << self
-      # Timeout for waiting until object exists. If the timeout exceeds then an Exception is thrown.
+      # Timeout for waiting until object exists. If the timeout exceeds then an {WaitHelper::TimeoutError} is raised.
       @@wait_timeout = 60
 
+      # Change the timeout to wait before {WaitHelper::TimeoutError} is raised.
+      # @param [Fixnum] timeout in seconds.
       def wait_timeout=(timeout)
         @@wait_timeout = timeout
       end
 
+      # Retrieve current timeout in seconds to wait before {WaitHelper::TimeoutError} is raised.
+      # @return [Fixnum] timeout in seconds
       def wait_timeout
         @@wait_timeout
       end
     end
 
-    # Returns handle of the Window.
-    #
-    # This handle will be used internally for all operations.
+    # @return [Fixnum] handle of the window which is used internally for other methods.
     def hwnd
       wait_until_exists
       @window.hwnd
     end
 
-    # Returns title of the Window.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # @return [Fixnum] process identifier (PID) of the window.
+    def pid
+      wait_until_exists
+      @window.pid
+    end
+
+    # @return [String] title of the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def title
       wait_until_exists
       @window.title
     end
 
-    # Activates the Window, e.g. brings to the top.
+    # Activates the Window, e.g. brings it to the top of other windows.
     def activate
       @window.activate
     end
 
-    # Returns true if the Window is active, false otherwise.
+    # Checks if the window is active, e.g. on the top of other windows.
+    # @return [Boolean] true if the window is active, false otherwise.
     def active?
       @window.active?
     end
 
     # Returns visible text of the Window.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # @return [String] visible text of the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def text
       wait_until_exists
       @window.text
     end
 
-    # Returns true if the Window exists, false otherwise.
+    # Checks if the window exists (does have to be visible).
+    # @return [Boolean] true if the window exists, false otherwise.
     def exists?
       @window.exists?
     end
 
     alias_method :exist?, :exists?
 
-    # Returns true if the Window is visible, false otherwise.
-    # Window is also visible, if it is behind other windows or minimized.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Checks if window is visible.
+    # @note Window is also visible, if it is behind other windows or minimized.
+    # @return [Boolean] true if window is visible, false otherwise.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def visible?
       wait_until_exists
       @window.visible?
     end
 
-    # Returns true if the Window exists and is visible, false otherwise.
+    # Checks if the window exists and is visible.
+    # @return [Boolean] true if window exists and is visible, false otherwise
     def present?
       exists? && visible?
     end
 
-    # Maximizes the Window.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Maximizes the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def maximize
       wait_until_exists
       @window.maximize
     end
 
-    # Minimizes the Window.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Minimizes the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def minimize
       wait_until_exists
       @window.minimize
     end
 
-    # Returns true if the Window is minimized, false otherwise.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Checks if window is minimized.
+    # @return [Boolean] true if window is minimized, false otherwise.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def minimized?
       wait_until_exists
       @window.minimized?
     end
 
-    # Restores the Window.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Restores the window size and position.
+    # @note If the window is minimized, makes it visible again.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def restore
       wait_until_exists
       @window.restore
     end
 
-    # Sends keys to the Window. Refer to specific adapter's documentation for possible values.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Sends keyboard keys to the window. Refer to specific {Adapter} documentation for all possible values.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def send_keys(*keys)
       wait_until_exists
       @window.send_keys(*keys)
     end
 
-    # Closes the Window if it exists.
+    # Closes the window if it exists.
     def close
       return unless @window.exists?
       @window.close
     end
 
-    # Returns the Button object by the _locators_ on the Window.
-    # Refer to specific adapter's documentation for possible parameters.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Retrieves {Button} on the window.
+    # @note Refer to specific {Adapter} documentation for possible _locator_ parameters.
+    # @param [Hash] locators for the {Button}.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def button(locators)
       wait_until_exists
       Button.new(@window, locators)
     end
 
-    # Returns the TextField object by the _locators_ on the Window.
-    # Refer to specific adapter's documentation for possible parameters.
-    #
-    # Raises an UnknownWindowException if the Window itself doesn't exist.
+    # Retrieves {TextField} on the window.
+    # @note Refer to specific {Adapter} documentation for possible _locators_ parameters.
+    # @raise [UnknownWindowException] if the window doesn't exist.
     def text_field(locators)
       wait_until_exists
       TextField.new(@window, locators)
     end
 
-    # Allow to execute adapter's methods not part of the public API
+    # Allows to execute specific {Adapter} methods not part of the public API.
     def method_missing(name, *args)
       @window.send(name, *args)
     end

data/rautomation.gemspec

@@ -5,19 +5,19 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rautomation}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jarmo Pertman"]
-  s.date = %q{2010-12-14}
-  s.description = %q{RAutomation tries to be a small and easy to use library for helping out to automate windows and their controls
+  s.date = %q{2010-12-17}
+  s.description = %q{RAutomation is a small and easy to use library for helping out to automate windows and their controls
 for automated testing.
 
-RAutomation aims to provide:
-* Easy to use and user-friendly API (inspired by Watir http://www.watir.com).
+RAutomation provides:
+* Easy to use and user-friendly API (inspired by Watir http://www.watir.com)
 * Cross-platform compatibility
-* Easy extensibility - have some application, which uses some specialized technology, but isn't supported by RAutomation?
-  You can get dirty and create a new adapter for RAutomation!}
+* Easy extensibility - with small scripting effort it's possible to add support for not yet
+  supported platforms or technologies}
   s.email = %q{jarmo.p@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",

data/spec/spec_helper.rb

@@ -31,6 +31,7 @@ module SpecHelper
                   :window2_button_text => "OK",
                   # Window 2 should have a text field with the specified class name.
                   :window2_text_field_class => "Edit",
+                  # Adapter internal method invocation for getting title of window2
                   :title_proc => lambda {|win| win.WinGetTitle("[TITLE:Explorer User Prompt]")}
           },
           # This adapter needs Windows OS with Internet Explorer installed into 'c:\program files\internet explorer'.
@@ -53,6 +54,7 @@ module SpecHelper
                   :window2_button_text => "OK",
                   # Window 2 should have a text field with the specified class name.
                   :window2_text_field_class => "Edit",
+                  # Adapter internal method invocation for getting title of window2
                   :title_proc => lambda {|win| win.window_title(win.hwnd)}
           }
   }[ENV["RAUTOMATION_ADAPTER"] && ENV["RAUTOMATION_ADAPTER"].to_sym || RAutomation::Adapter::Helper.default_adapter]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rautomation
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jarmo Pertman
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-14 00:00:00 +02:00
+date: 2010-12-17 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -34,14 +34,14 @@ dependencies:
   type: :development
   version_requirements: *id001
 description: |-
-  RAutomation tries to be a small and easy to use library for helping out to automate windows and their controls
+  RAutomation is a small and easy to use library for helping out to automate windows and their controls
   for automated testing.
   
-  RAutomation aims to provide:
-  * Easy to use and user-friendly API (inspired by Watir http://www.watir.com).
+  RAutomation provides:
+  * Easy to use and user-friendly API (inspired by Watir http://www.watir.com)
   * Cross-platform compatibility
-  * Easy extensibility - have some application, which uses some specialized technology, but isn't supported by RAutomation?
-    You can get dirty and create a new adapter for RAutomation!
+  * Easy extensibility - with small scripting effort it's possible to add support for not yet
+    supported platforms or technologies
 email: jarmo.p@gmail.com
 executables: []