win32-autogui 0.2.0

data/features/automating_an_application.feature

@@ -0,0 +1,11 @@
+Feature: Automating a GUI application
+
+  As a developer, I want to run automated tests on GUI applications
+  so that my specifications are testable in a repeatable manner.
+
+  Background: A running GUI application
+    Given a GUI application named calculator
+
+  Scenario: Simple calculation
+    When I type in "2+2="
+    Then the edit window text should match /4/

data/features/step_definitions/calculator_steps.rb

@@ -0,0 +1,37 @@
+require File.expand_path(File.dirname(__FILE__) + '../../../spec/applications/calculator')
+
+include Autogui::Input
+
+After('@calculator') do
+  if @calculator
+    @calculator.close(:wait_for_close => true) if @calculator.running?
+    @calculator.should_not be_running
+  end
+end
+
+Given /^a GUI application named calculator$/ do 
+  @calculator = Calculator.new
+  @calculator.should be_running
+end
+
+When /^I type in "([^"]*)"$/ do |string|
+  @calculator.set_focus
+  type_in(string)
+end
+
+# "the window text should match" allows regex in the partial_output, if
+# you don't need regex, use "the output should contain" instead since
+# that way, you don't have to escape regex characters that
+# appear naturally in the output
+Then /^the edit window text should match \/([^\/]*)\/$/ do |partial_output|
+  @calculator.edit_window.text.should =~ /#{partial_output}/
+end
+
+Then /^the edit window text should contain exactly "([^"]*)"$/ do |exact_output|
+  @calculator.edit_window.text.should == unescape(exact_output)
+end
+
+Then /^the edit window text should contain exactly:$/ do |exact_output|
+  @calculator.edit_window.text.should == exact_output
+end
+

data/features/support/env.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'win32/autogui'
+require 'aruba'
+require 'spec/expectations'

data/lib/win32/autogui.rb

@@ -0,0 +1,27 @@
+# require all files here
+require 'win32/autogui/input'
+require 'win32/autogui/window'
+require 'win32/autogui/application'
+
+# Master namespace
+module Autogui
+  
+  # Contents of the VERSION file
+  #
+  # Example format: 0.0.1
+  #
+  # @return [String] the contents of the version file in #.#.# format
+  def self.version
+    version_info_file = File.join(File.dirname(__FILE__), *%w[.. .. VERSION])
+    File.open(version_info_file, "r") do |f|
+      f.read.strip
+    end
+  end
+
+  # @return False (nil) or True (Integer)
+  def self.win32?
+    RUBY_PLATFORM =~ /mingw|mswin|cygwin/i
+  end
+
+end
+

data/lib/win32/autogui/application.rb

@@ -0,0 +1,249 @@
+require 'windows/process'
+require 'windows/synchronize'
+require 'windows/handle'
+require "win32/process"
+require "win32/clipboard"
+
+module Autogui
+
+  # Wrapper class for text portion of the RubyGem win32/clipboard 
+  # @see http://github.com/djberg96/win32-clipboard
+  class Clipboard
+
+    # Clipboard text getter
+    # 
+    # @return [String] clipboard data
+    #
+    def text 
+      Win32::Clipboard.data
+    end
+
+    # Clipboard text setter
+    #
+    # @param [String] str text to load onto the clipboard
+    #
+    def text=(str)
+      Win32::Clipboard.set_data(str)
+    end
+
+  end
+
+  # The Application class wraps a binary application so 
+  # that it can be started and controlled via Ruby.  This
+  # class is meant to be subclassed.
+  #
+  # @example
+  #
+  #   class Calculator < Autogui::Application
+  #
+  #     def initialize(options = {})
+  #       defaults = {
+  #                    :name => "calc",
+  #                    :title => "Calculator"
+  #                  }
+  #       super defaults.merge(options)
+  #     end
+  #
+  #     def edit_window
+  #       main_window.children.find {|w| w.window_class == 'Edit'}
+  #     end
+  #
+  #     def dialog_about
+  #       Autogui::EnumerateDesktopWindows.new.find do |w| 
+  #         w.title.match(/About Calculator/) && (w.pid == pid)
+  #       end
+  #     end
+  #
+  #     def clear_entry
+  #       set_focus
+  #       keystroke(VK_DELETE)
+  #     end
+  #   end
+  #
+  class Application
+    include Windows::Process           
+    include Windows::Synchronize
+    include Windows::Handle
+
+    # @return [String] the executable name of the application
+    attr_accessor :name  
+    
+    # @return [String] the executable application parameters 
+    attr_accessor :parameters  
+    
+    # @return [String] window title of the application
+    attr_accessor :title  
+
+    # @return [Number] the process identifier (PID) returned by Process.create
+    attr_reader :pid
+
+    # @return [Number] the process thread id returned by Process.create
+    attr_reader :thread_id
+
+    # @return [Number] the main_window wait timeout in seconds
+    attr_accessor :main_window_timeout
+    
+    # @return [Number] the wait timeout in seconds used by Process.create
+    attr_accessor :create_process_timeout
+    
+    # @example initialize an application on the path
+    #
+    #   Application.new :name => "calc"  
+    #
+    # @example initialize with full DOS path
+    #
+    #   Application.new :name => "\\windows\\system32\\calc.exe"  
+    #
+    # @param [Hash] options initialize options
+    # @option options [String] :name a valid win32 exe name with optional path
+    # @option options [String] :title the application window title, used along with the pid to locate the application main window, defaults to :name
+    # @option options [Number] :parameters command line parameters used by Process.create
+    # @option options [Number] :create_process_timeout (10) timeout in seconds to wait for the create_process to return 
+    # @option options [Number] :main_window_timeout (10) timeout in seconds to wait for main_window to appear
+    #
+    def initialize(options = {})
+
+      unless options.kind_of?(Hash)
+        raise ArgumentError, 'Initialize expecting options to be a Hash'
+      end
+
+      @name = options[:name] || name
+      @title = options[:title] || name
+      @main_window_timeout = options[:main_window_timeout] || 10
+      @create_process_timeout = options[:create_process_timeout] || 10
+      @parameters = options[:parameters]
+
+      # sanity checks
+      raise 'Application name not set' unless name 
+
+      start
+    end
+    
+    # Start up the binary application via Process.create and
+    # set the window focus to the main_window
+    #
+    # @raise [Exception] if create_process_timeout exceeded
+    # @raise [Exception] if start failed for any reason other than create_process_timeout
+    #
+    # @return [Number] the pid
+    #
+    def start
+      
+      command_line = name
+      command_line = name + ' ' + parameters if parameters
+
+      # returns a struct, raises an error if fails
+      process_info = Process.create(
+         :command_line => command_line,
+         :close_handles => false,
+         :creation_flags => Process::DETACHED_PROCESS
+      )
+      @pid = process_info.process_id
+      @thread_id = process_info.thread_id
+      process_handle = process_info.process_handle
+      thread_handle = process_info.thread_handle
+
+      # wait for process
+      ret = WaitForInputIdle(process_handle, (create_process_timeout * 1000))
+
+      # done with the handles
+      CloseHandle(process_handle)
+      CloseHandle(thread_handle)
+
+      raise "Start command failed on create_process_timeout" if ret == WAIT_TIMEOUT 
+      raise "Start command failed while waiting for idle input, reason unknown" unless (ret == 0)
+      @pid
+    end
+
+    # The application main window found by enumerating windows 
+    # by title and application pid.  This method will keep looking
+    # unit main_window_timeout (default: 10s) is exceeded.
+    #
+    # @raise [Exception] if the main window cannot be found
+    #
+    # @return [Autogui::Window]
+    # @see initialize for options
+    # 
+    def main_window
+      return @main_window if @main_window
+
+      timeout(main_window_timeout) do
+        begin
+          # There may be multiple instances, use title and pid to id our main window
+          @main_window = Autogui::EnumerateDesktopWindows.new.find do |w| 
+            w.title.match(title) && w.pid == pid 
+          end
+          sleep 0.1 
+         end until @main_window
+      end
+
+      # sanity checks
+      raise "cannot find main_window, check application title" unless @main_window
+
+      @main_window
+    end
+
+    # Call the main_window's close method
+    #
+    # PostMessage SC_CLOSE and optionally wait for the window to close
+    #
+    # @param [Hash] options
+    # @option options [Boolean] :wait_for_close (true) sleep while waiting for timeout or close
+    # @option options [Boolean] :timeout (5) wait_for_close timeout in seconds
+    #
+    def close(options={})
+      main_window.close(options)
+    end
+
+    # Send SIGKILL to force the application to die
+    def kill
+      Process::kill(9, pid)
+    end
+
+    # @return [Boolean] if the application is currently running
+    def running?
+      main_window && (main_window.is_window?)
+    end
+
+    # Set the application input focus to the main_window
+    # 
+    # @return [Number] nonzero number if sucess, nil or zero if failed
+    # 
+    def set_focus
+      main_window.set_focus if running? 
+    end
+
+    # The main_window text including all child windows 
+    # joined together with newlines. Faciliates matching text.
+    #
+    # @example partial match of the Window's calulator's about dialog copywrite text
+    #
+    #   dialog_about = @calculator.dialog_about
+    #   dialog_about.title.should == "About Calculator"
+    #   dialog_about.combined_text.should match(/Microsoft . Calculator/)
+    #
+    # @return [String] with newlines
+    #
+    def combined_text
+      main_window.combined_text if running? 
+    end
+
+    # @example set the clipboard text and paste it with Control-V
+    #
+    #   @calculator.edit_window.set_focus
+    #   @calculator.clipboard.text = "12345"
+    #   @calculator.edit_window.text.strip.should == "0."
+    #   keystroke(VK_CONTROL, VK_V) 
+    #   @calculator.edit_window.text.strip.should == "12,345."
+    #
+    # @return [Clipboard] 
+    #
+    def clipboard
+      @clipboard || Autogui::Clipboard.new
+    end
+
+  private
+
+  end
+
+end

data/lib/win32/autogui/input.rb

@@ -0,0 +1,238 @@
+# The algorithms in this module are presented in the book
+# Scripted GUI testing with Ruby by Ian Dees
+# @see http://pragprog.com/titles/idgtr/scripted-gui-testing-with-ruby
+
+require 'windows/api'
+
+# methods for simulating user input
+module Autogui
+  module Input
+
+    # MSDN virtual key codes
+    VK_LBUTTON = 0x01
+    VK_RBUTTON = 0x02
+
+    VK_CANCEL = 0x03
+    VK_BACK = 0x08
+    VK_TAB = 0x09
+    VK_CLEAR = 0x0c
+    VK_RETURN = 0x0d
+    VK_SHIFT = 0x10
+    VK_CONTROL = 0x11
+    VK_MENU = 0x12
+    VK_PAUSE = 0x13
+    VK_ESCAPE = 0x1b
+    VK_SPACE = 0x20
+    VK_PRIOR = 0x21
+    VK_NEXT = 0x22
+    VK_END = 0x23
+    VK_HOME = 0x24
+    VK_LEFT = 0x25
+    VK_UP = 0x26
+    VK_RIGHT = 0x27
+    VK_DOWN = 0x28
+    VK_SELECT = 0x29
+    VK_EXECUTE = 0x2b
+    VK_SNAPSHOT = 0x2c
+    VK_INSERT = 0x2d
+    VK_DELETE = 0x2e
+    VK_HELP = 0x2f
+
+    VK_0 = 0x30
+    VK_1 = 0x31
+    VK_2 = 0x32
+    VK_3 = 0x33
+    VK_4 = 0x34
+    VK_5 = 0x35
+    VK_6 = 0x36
+    VK_7 = 0x37
+    VK_8 = 0x38
+    VK_9 = 0x39
+    VK_A = 0x41
+    VK_B = 0x42
+    VK_C = 0x43
+    VK_D = 0x44
+    VK_E = 0x45
+    VK_F = 0x46
+    VK_G = 0x47
+    VK_H = 0x48
+    VK_I = 0x49
+    VK_J = 0x4a
+    VK_K = 0x4b
+    VK_L = 0x4c
+    VK_M = 0x4d
+    VK_N = 0x4e
+    VK_O = 0x4f
+    VK_P = 0x50
+    VK_Q = 0x51
+    VK_R = 0x52
+    VK_S = 0x53
+    VK_T = 0x54
+    VK_U = 0x55
+    VK_V = 0x56
+    VK_W = 0x57
+    VK_X = 0x58
+    VK_Y = 0x59
+    VK_Z = 0x5a
+
+    VK_LWIN = 0x5b
+    VK_RWIN = 0x5c
+    VK_APPS = 0x5d
+
+    VK_NUMPAD0 = 0x60
+    VK_NUMPAD1 = 0x61
+    VK_NUMPAD2 = 0x62
+    VK_NUMPAD3 = 0x63
+    VK_NUMPAD4 = 0x64
+    VK_NUMPAD5 = 0x65
+    VK_NUMPAD6 = 0x66
+    VK_NUMPAD7 = 0x67
+    VK_NUMPAD8 = 0x68
+    VK_NUMPAD9 = 0x69
+    VK_MULTIPLY = 0x6a
+    VK_ADD = 0x6b
+    VK_SEPARATOR = 0x6c
+    VK_SUBTRACT = 0x6d
+    VK_DECIMAL = 0x6e
+    VK_DIVIDE = 0x6f
+
+    VK_F1 = 0x70
+    VK_F2 = 0x71
+    VK_F3 = 0x72
+    VK_F4 = 0x73
+    VK_F5 = 0x74
+    VK_F6 = 0x75
+    VK_F7 = 0x76
+    VK_F8 = 0x77
+    VK_F9 = 0x78
+    VK_F10 = 0x79
+    VK_F11 = 0x7a
+    VK_F12 = 0x7b
+
+    VK_NUMLOCK = 0x90
+    VK_SCROLL = 0x91
+    VK_OEM_EQU = 0x92
+    VK_LSHIFT = 0xa0
+    VK_RSHIFT = 0xa1
+    VK_LCONTROL = 0xa2
+    VK_RCONTROL = 0xa3
+    VK_LMENU = 0xa4
+    VK_RMENU = 0xa5
+
+    VK_OEM_1 = 0xba
+    VK_OEM_PLUS = 0xbb
+    VK_OEM_COMMA = 0xbc
+    VK_OEM_MINUS = 0xbd
+    VK_OEM_PERIOD = 0xbe
+    VK_OEM_2 = 0xbf
+    VK_OEM_3 = 0xc0         # US '~' key
+    VK_OEM_4 = 0xdb
+    VK_OEM_5 = 0xdc         # US '\' key
+    VK_OEM_6 = 0xdd
+    VK_OEM_7 = 0xde         # US quotes key
+    VK_OEM_8 = 0xdf
+
+    # delay in seconds between keystrokes
+    KEYBD_KEYDELAY = 0.050
+
+    # keybd_event
+    KEYBD_EVENT_KEYUP = 2
+    KEYBD_EVENT_KEYDOWN = 0
+
+    Windows::API.auto_namespace = 'Autogui::Input'
+    Windows::API.auto_constant  = true
+    Windows::API.auto_method    = true
+    Windows::API.auto_unicode   = false
+
+    Windows::API.new('keybd_event', 'IILL', 'V', 'user32')
+    Windows::API.new('mouse_event', 'LLLLL', 'V', 'user32')
+
+    # Send keystroke to the focused window, keystrokes are virtual keycodes
+    #
+    # @example send 2+2<CR>
+    #
+    #     keystroke(VK_2, VK_ADD, VK_2, VK_RETURN) 
+    #
+    def keystroke(*keys)
+      return if keys.empty?
+      
+      keybd_event keys.first, 0, KEYBD_EVENT_KEYDOWN, 0
+      sleep KEYBD_KEYDELAY
+      keystroke *keys[1..-1]
+      sleep KEYBD_KEYDELAY
+      keybd_event keys.first, 0, KEYBD_EVENT_KEYUP, 0 
+    end
+
+    # String together keystrokes, simulates the user typing. 
+    #
+    # Note: This method can be slow for large strings.  Consider using
+    # the clipboard instead.  
+    #
+    # @see Clipboard 
+    #
+    # @example send 2+2<CR>
+    #
+    #     type_in("2+2\n")
+    #
+    # @param [String] string of characters to simulate typing
+    def type_in(string)
+      string.each_char do |char|
+        keystroke(*char_to_virtual_keycode(char))
+      end
+    end
+
+    private
+
+    # convert a single character to a virtual keycode
+    #
+    # @param [Char] char is the character to convert
+    #
+    # @return [Array] of virtual keycodes
+    def char_to_virtual_keycode(char)
+
+      unless char.size == 1
+        raise "virtual keycode conversion is for single characters only"
+      end
+      
+      code = char.unpack('U')[0]
+
+      case char
+        when '0'..'9'
+          [code - ?0 + 0x30]
+        when 'A'..'Z'
+          [VK_SHIFT, code]
+        when 'a'..'z'
+          [code - ?a + ?A]
+        when ' '
+          [code]
+        when '+'
+          [VK_ADD]
+        when '='
+          [VK_OEM_PLUS]
+        when ','
+          [VK_OEM_COMMA]
+        when '.'
+          [VK_OEM_PERIOD]
+        when '-'
+          [VK_OEM_MINUS]
+        when '_'
+          [VK_SHIFT, VK_OEM_MINUS]
+        when ':'
+          [VK_SHIFT, VK_OEM_1]
+        when ';'
+          [VK_OEM_1]
+        when '\''
+          [VK_OEM_7]
+        when '\"'
+          [VK_SHIFT, VK_OEM_7]
+        when "\\"
+          [VK_OEM_5]
+        when "\n"
+          [VK_RETURN]
+        else
+          raise "No conversion exists for character #{char}"
+      end
+    end  
+
+  end
+end