rdp-rautomation 0.6.3.1

data/lib/rautomation/button.rb

@@ -0,0 +1,55 @@
+module RAutomation
+  class Button
+    # @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.
+    # By default click is considered successful if the button doesn't exist after clicking (e.g. window has closed)
+    # @yield [button] optional block specifying successful clicking condition.
+    # @yieldparam [Button] button which is being clicked on.
+    # @yieldreturn [Boolean] true if clicking on the button is successful, false otherwise.
+    # @raise [UnknownButtonException] if the button doesn't exist.
+    def click
+      wait_until_exists
+      if block_given?
+        @button.click {yield self}
+      else
+        @button.click
+      end
+    end
+
+    # 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
+
+    # Checks if the button exists.
+    # @return [Boolean] true if button exists, false otherwise.
+    def exists?
+      @button.exists?
+    end
+
+    alias_method :exist?, :exists?
+
+    # Allows to execute specific {Adapter} methods not part of the public API.
+    def method_missing(name, *args)
+      @button.send(name, *args)
+    end
+
+    private
+
+    def wait_until_exists
+      WaitHelper.wait_until {exists?}
+    rescue WaitHelper::TimeoutError
+      raise UnknownButtonException, "Button #{@locators.inspect} doesn't exist on window #{@window.locators.inspect}!"
+    end
+  end
+end

data/lib/rautomation/element_collections.rb

@@ -0,0 +1,47 @@
+module RAutomation
+  # @private
+  module ElementCollections
+    # Creates collection classes and methods for elements.
+    # @param [Array<Symbol>] elements for which to create collection classes
+    #   and methods.
+    def has_many(*elements)
+      elements.each do |element|
+        class_name_plural = element.to_s.split("_").map {|e| e.capitalize}.join
+        class_name = class_name_plural.chop
+        adapter_class = self.to_s.scan(/(.*)::/).flatten.first
+        clazz = RAutomation.constants.include?(class_name) ? RAutomation : class_eval(adapter_class)
+        clazz.class_eval %Q{
+            class #{class_name_plural}
+              include Enumerable
+
+              def initialize(window, locators)
+                @window = window
+                @locators = locators
+              end
+
+              def each
+                i = -1 
+                while true
+                  args = [@window, @locators.merge(:index => i += 1)].compact
+                  object = #{clazz}::#{class_name}.new(*args)
+                  break unless object.exists?
+                  yield object
+                end
+              end
+
+              def method_missing(name, *args)
+                ary = self.to_a
+                ary.respond_to?(name) ? ary.send(name, *args) : super
+              end
+            end
+        }
+
+        class_eval %Q{
+            def #{element}(locators = {})
+              #{class_name_plural}.new(@window, locators)
+            end
+        }
+      end
+    end
+  end
+end

data/lib/rautomation/text_field.rb

@@ -0,0 +1,60 @@
+module RAutomation
+  class TextField
+    # @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 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 text field's text.
+    # @raise [UnknownTextFieldException] if the text field doesn't exist.
+    def clear
+      wait_until_exists
+      @text_field.clear
+    end
+
+    # 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
+
+    # Checks if the text field exists.
+    # @return [Boolean] true if text field exists, false otherwise.
+    def exists?
+      @text_field.exists?
+    end
+
+    def hwnd
+      wait_until_exists
+      @text_field.hwnd
+    end
+
+    alias_method :exist?, :exists?
+
+    # Allows to execute specific {Adapter} methods not part of the public API.
+    def method_missing(name, *args)
+      @text_field.send(name, *args)
+    end
+
+    private
+
+    def wait_until_exists
+      WaitHelper.wait_until {exists?}
+    rescue WaitHelper::TimeoutError
+      raise UnknownTextFieldException, "Text field #{@locators.inspect} doesn't exist on window #{@window.locators.inspect}!" unless exists?
+    end
+  end
+end

data/lib/rautomation/wait_helper.rb

@@ -0,0 +1,23 @@
+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 = Window.wait_timeout, &block)
+      end_time = ::Time.now + timeout
+
+      until ::Time.now > end_time
+        result = yield(self)
+        return result if result
+        sleep 0.5
+      end
+
+      raise TimeoutError, "timed out after #{timeout} seconds"
+    end
+  end
+end

data/lib/rautomation/window.rb

@@ -0,0 +1,234 @@
+module RAutomation
+  class UnknownElementException < RuntimeError
+  end
+  class UnknownWindowException < UnknownElementException
+  end
+  class UnknownButtonException < UnknownElementException
+  end
+  class UnknownTextFieldException < UnknownElementException
+  end
+
+  class Window
+    include Adapter::Helper
+    extend ElementCollections
+
+    has_many :windows, :buttons, :text_fields
+
+    class << self
+      # @return [Windows] all windows. 
+      def windows
+        Windows.new(nil, {})
+      end
+    end
+    
+    # Retrieves all windows with similar locators to the current window.
+    # @param locators (see #initialize) 
+    # @return [Windows] all windows matching current window's _locators_ if no
+    #   explicit locators specified or windows matching the specified _locators_.
+    def windows(locators = @window.locators)
+      Windows.new(nil, locators)
+    end
+
+    # Currently used {Adapter}.
+    attr_reader :adapter
+
+    # Creates the window object.
+    #
+    # Possible window _locators_ may depend of the used platform and adapter, but
+    # following examples will use :title, :class and :hwnd.
+    #
+    # @example Use window with some title:
+    #   RAutomation::Window.new(:title => "some title")
+    #
+    # @example Use window with Regexp title:
+    #   RAutomation::Window.new(:title => /some title/i)
+    #
+    # @example Use window with handle (hwnd):
+    #   RAutomation::Window.new(:hwnd => 123456)
+    #
+    # @example Use multiple locators, every locator will be matched (AND-ed) to the window:
+    #   RAutomation::Window.new(:title => "some title", :class => "IEFrame")
+    #
+    # @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 the default adapter by using environment variable called
+    # __RAUTOMATION_ADAPTER__
+    #
+    # @note This constructor doesn't check for window's existance.
+    # @note Only visible windows are supported.
+    # @note If given _locators_ include :hwnd then every other possible _locator_ is ignored.
+    # @param [Hash] locators 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 {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
+
+    # @return [Fixnum] handle of the window which is used internally for other methods.
+    # @raise [UnknownWindowException] if the window doesn't exist.
+    def hwnd
+      wait_until_present
+      @window.hwnd
+    end
+
+    # @return [Fixnum] process identifier (PID) of the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
+    def pid
+      wait_until_present
+      @window.pid
+    end
+
+    # @return [String] title of the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
+    def title
+      wait_until_present
+      @window.title
+    end
+
+    # Activates the Window, e.g. brings it to the top of other windows.
+    def activate
+      @window.activate
+    end
+
+    # 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.
+    # @return [String] visible text of the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
+    def text
+      wait_until_present
+      @window.text
+    end
+
+    # 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?
+
+    # 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
+
+    # 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.
+    # @raise [UnknownWindowException] if the window doesn't exist.
+    def maximize
+      wait_until_present
+      @window.maximize
+    end
+
+    # Minimizes the window.
+    # @raise [UnknownWindowException] if the window doesn't exist.
+    def minimize
+      wait_until_present
+      @window.minimize
+    end
+
+    # 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_present
+      @window.minimized?
+    end
+
+    # 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_present
+      @window.restore
+    end
+
+    # 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_present
+      @window.send_keys(keys)
+    end
+
+    # Closes the window if it exists.
+    def close
+      return unless @window.exists?
+      @window.close
+    end
+
+    # 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_present
+      Button.new(@window, locators)
+    end
+
+    # 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_present
+      TextField.new(@window, locators)
+    end
+
+    # Allows to execute specific {Adapter} methods not part of the public API.
+    def method_missing(name, *args)
+      @window.send(name, *args)
+    end
+
+    private
+
+    def wait_until_present
+      WaitHelper.wait_until {present?}
+    rescue WaitHelper::TimeoutError
+      raise UnknownWindowException, "Window with locator #{@window.locators.inspect} doesn't exist or is not visible!"
+    end
+
+    def wait_until_exists
+      WaitHelper.wait_until {exists?}
+    rescue WaitHelper::TimeoutError
+      raise UnknownWindowException, "Window with locator #{@window.locators.inspect} doesn't exist!"
+    end
+
+    def normalize adapter
+      adapter.to_s.split("_").map {|word| word.capitalize}.join
+    end
+
+  end
+end

data/spec/adapter/win_ffi/button_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe "WinFfi::Button", :if => SpecHelper.adapter == :win_ffi do
+  it "find by id" do
+    window = RAutomation::Window.new(:title => SpecHelper::DATA[:window1_title])
+    window.button(:id => "aboutButton").should exist
+  end
+
+  it "check for button class" do
+    RAutomation::Window.new(:title => "MainFormWindow").button(:id => "textField").should_not exist
+  end
+
+
+  it "enabled/disabled" do
+    window = RAutomation::Window.new(:title => SpecHelper::DATA[:window1_title])
+    window.button(:id => "enabledButton").should be_enabled
+    window.button(:id => "enabledButton").should_not be_disabled
+
+    window.button(:id => "disabledButton").should be_disabled
+    window.button(:id => "disabledButton").should_not be_enabled
+  end
+
+  it "#set_focus" do
+    button = RAutomation::Window.new(:title => SpecHelper::DATA[:window1_title]).button(:id => "enabledButton")
+    button.should_not have_focus
+
+    button.set_focus
+    button.should have_focus
+  end
+
+  it "cannot click disabled button" do
+    window = RAutomation::Window.new(:title => SpecHelper::DATA[:window1_title])
+    lambda { window.button(:id => "disabledButton").click }.should raise_error
+  end
+
+  it "cannot set focus to disabled button" do
+    window = RAutomation::Window.new(:title => SpecHelper::DATA[:window1_title])
+    lambda { window.button(:id => "disabledButton").set_focus }.should raise_error
+  end
+
+end