rukuli 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 79bcc51a1ba07f799f46d15d579e03cc5f239fc1
+  data.tar.gz: 65a8c98c4ba3e54433c2379e5a4818593cd33a81
+SHA512:
+  metadata.gz: 0a821a6a259c5587cba8d0ade7608a68928dc2a34d4c909c4e512576d5777fbaca20bcb627866a4db9ed6f82f1f53c1cc754b9f2c41b43c314a68a8b0c92a428
+  data.tar.gz: a7fb19df115ec199224408e31c6ed0623d0034c1415f912ebc7f6206456a59d7ec28dbf9cc7136a87248b364f8223b5c02f5276393352905668f0ba4aaac87bb

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in sikuli_ruby.gemspec
+gemspec

data/License.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 - 2014 André Anastácio
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,67 @@
+# Rukuli
+
+[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/andreanastacio/rukuli/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
+
+This project is a fork of [sikuli_ruby](https://github.com/chaslemley/sikuli_ruby)!
+
+[Sikuli](http://sikuli.org/) allows you to interact with your application's user interface using image based search to automate user actions.
+
+## Requirements
+* [Sikuli-Script 1.0.1](https://launchpad.net/sikuli/+download) (Install Sikuli-Script via sikuli-setup.jar)
+* [JRuby](http://jruby.org/download) or ```rvm install jruby```
+
+## Compatibility
+
+Make sure to set SIKULI_HOME to the Sikuli installation directory and to add the Sikuli installation directory and Sikuli libs directory to the include path.
+
+### Windows
+
+```
+ setx SIKULI_HOME C:/path/to/sikuli-script.jar
+```
+
+### Linux / OSX
+```bash
+ export SIKULI_HOME="~/path/to/sikuli-script.jar"
+```
+
+# Installation
+```
+  gem install rukuli
+```
+
+# Usage
+
+```ruby
+  require 'java'
+  require 'rukuli'
+
+  Rukuli::Config.run do |config|
+    config.image_path = "#{Dir.pwd}/images/"
+    config.logging = false
+  end
+
+  screen = Rukuli::Screen.new
+  screen.click(10, 10) # should open your apple menu
+
+  app = Rukuli::App.new("iPhone Simulator")
+  app.window.click('ui_element.png') if app.window.find('ui_element.png')
+```
+
+# Running the test suite
+
+1. You need to open `test_area.jpg` in **Preview** from `spec/support/images/` directory
+before running tests.
+2. You also need to open the **TextEdit** app
+
+# Examples
+
+* [Cucumber Suite](https://github.com/chaslemley/cucumber_sikuli)
+
+# Contributing
+
+* Fork it
+* Create your feature branch (git checkout -b my-new-feature)
+* Commit your changes (git commit -am 'Add some feature')
+* Push to the branch (git push origin my-new-feature)
+* Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/lib/rukuli.rb

@@ -0,0 +1,10 @@
+require "rukuli/platform"
+require Rukuli::Platform.sikuli_script_path
+require "rukuli/version"
+
+require "rukuli/app"
+require "rukuli/exception"
+require "rukuli/region"
+require "rukuli/screen"
+require "rukuli/key_code"
+require "rukuli/config"

data/lib/rukuli/app.rb

@@ -0,0 +1,33 @@
+# An App object represents a running app on the system.
+#
+module Rukuli
+  class App
+
+    # Public: creates a new App instance
+    #
+    # app_name - String name of the app
+    #
+    # Examples
+    #
+    #   App.new("TextEdit")
+    #
+    # Returns the newly initialized App
+    def initialize(app_name)
+      @java_obj = org.sikuli.script::App.new(app_name)
+    end
+
+    # Public: brings the App to focus
+    #
+    # Returns nothing
+    def focus
+      @java_obj.focus()
+    end
+
+    # Public: the Region instance representing the app's window
+    #
+    # Returns the newly initialized Region
+    def window
+      Region.new(@java_obj.window())
+    end
+  end
+end

data/lib/rukuli/clickable.rb

@@ -0,0 +1,278 @@
+# The Clickable module defines interaction with the mouse. It is included in
+# the Region class.
+#
+module Rukuli
+  module Clickable
+
+    # Public: Performs a single click on an image match or point (x, y)
+    #
+    # args - String representing filename of image to find and click
+    # args - Fixnum, Fixnum representing x and y coordinates within
+    # a Region (0,0) is the top left
+    #
+    # Examples
+    #
+    #   region.click('smile.png')
+    #   region.click(123, 432)
+    #
+    # Returns nothing
+    def click(*args)
+      case args.length
+        when 1 then click_image(args[0])
+        when 2 then click_point(args[0], args[1])
+        else raise ArgumentError
+      end
+    end
+
+    # Public: Performs a double click on an image match or point (x, y)
+    #
+    # args - String representing filename of image to find and click
+    # args - Fixnum, Fixnum representing x and y coordinates within
+    # a Region (0,0) is the top left
+    #
+    # Examples
+    #
+    #   region.double_click('smile.png')
+    #   region.double_click(123, 432)
+    #
+    # Returns nothing
+    def double_click(*args)
+      case args.length
+        when 1 then click_image(args[0], true)
+        when 2 then click_point(args[0], args[1], true)
+        else raise ArgumentError
+      end
+    end
+
+    # Public: Performs a click and hold on an image match or point (x, y)
+    #
+    # args - String representing filename of image to find and click
+    # args - Fixnum, Fixnum representing x and y coordinates within
+    # a Region (0,0) is the top left
+    # seconds - Fixnum representing the number of seconds to hold down
+    # before releasing
+    #
+    # Examples
+    #
+    #   region.click_and_hold('smile.png', 2)
+    #   region.click_and_hold(123, 432, 2)
+    #
+    # Returns nothing
+    def click_and_hold(seconds = 1, *args)
+      case args.length
+        when 1 then click_image_and_hold(args[0], seconds)
+        when 2 then click_point_and_hold(args[0], args[1], seconds)
+        else raise ArgumentError
+      end
+    end
+
+    # Public: Performs a mouse down, drag, and mouse up
+    #
+    # start_x - Fixnum representing the x of the mouse down
+    # start_y - Fixnum representing the y of the mouse down
+    # end_x   - Fixnum representing the x of the mouse up
+    # end_y   - Fixnum representing the y of the mouse up
+    #
+    # Examples
+    #
+    #   region.drag_drop(20, 12, 23, 44)
+    #
+    # Returns nothing
+    def drag_drop(start_x, start_y, end_x, end_y)
+      @java_obj.dragDrop(
+        offset_location(start_x, start_y),
+        offset_location(end_x, end_y)
+      )
+    end
+
+    # Public: Simulates turning of the mouse wheel up
+    #
+    # steps - Fixnum representing the number of steps to turn the mouse wheel
+    #
+    # Examples
+    #
+    #   region.wheel_up(10)
+    #
+    # Returns nothing
+    def wheel_up(steps = 1)
+      @java_obj.wheel(-1, steps)
+    end
+
+    # Public: Simulates turning of the mouse wheel down
+    #
+    # steps - Fixnum representing the number of steps to turn the mouse wheel
+    #
+    # Examples
+    #
+    #   region.wheel_down(10)
+    #
+    # Returns nothing
+    def wheel_down(steps = 1)
+      @java_obj.wheel(1, steps)
+    end
+
+    # Public: Performs a hover on an image match or point (x, y)
+    #
+    # args - String representing filename of image to find and hover
+    # args - Fixnum, Fixnum representing x and y coordinates within
+    # a Region (0,0) is the top left
+    #
+    # Examples
+    #
+    #   region.hover('smile.png')
+    #   region.hover(123, 432)
+    #
+    # Returns nothing
+    def hover(*args)
+      case args.length
+        when 1 then hover_image(args[0])
+        when 2 then hover_point(args[0], args[1])
+        else raise ArgumentError
+      end
+    end
+
+    private
+
+    # Private: turns the mouse wheel
+    #
+    # direction - Fixnum represeting direction to turn wheel
+    # steps - the number of steps to turn the mouse wheel
+    #
+    # Returns nothing
+    def wheel(direction, steps)
+      @java_obj.wheel(direction, steps)
+    end
+
+    # Private: clicks on a matched Region based on an image based search
+    #
+    # filename - A String representation of the filename of the region to
+    # match against
+    # seconds  - The length in seconds to hold the mouse
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def click_image_and_hold(filename, seconds)
+      begin
+        pattern = org.sikuli.script::Pattern.new(filename).similar(0.9)
+        @java_obj.hover(pattern)
+        @java_obj.mouseDown(java.awt.event.InputEvent::BUTTON1_MASK)
+        sleep(seconds.to_i)
+        @java_obj.mouseUp(0)
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Private: clicks on a point within the region
+    #
+    # filename - A String representation of the filename of the region to
+    # match against
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def click_point_and_hold(x, y, seconds)
+      begin
+        @java_obj.hover(location(x, y))
+        @java_obj.mouseDown(java.awt.event.InputEvent::BUTTON1_MASK)
+        sleep(seconds.to_i)
+        @java_obj.mouseUp(0)
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Private: clicks on a matched Region based on an image based search
+    #
+    # filename - A String representation of the filename of the region to
+    # match against
+    # is_double - (optional) Boolean determining if should be a double click
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def click_image(filename, is_double = false, and_hold = false)
+      begin
+        if is_double
+          @java_obj.doubleClick(filename, 0)
+        else
+          @java_obj.click(filename, 0)
+        end
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Private: clicks on a point relative to a Region's top left corner
+    #
+    # x         - a Fixnum representing the x component of the point to click
+    # y         - a Fixnum representing the y component of the point to click
+    # is_double - (optional) Boolean determining if should be a double click
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def click_point(x, y, is_double = false)
+      if is_double
+        @java_obj.doubleClick(offset_location(x, y))
+      else
+        @java_obj.click(offset_location(x, y))
+      end
+    end
+
+    # Private: hovers on a matched Region based on an image based search
+    #
+    # filename - A String representation of the filename of the region to
+    # match against
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def hover_image(filename)
+      begin
+        @java_obj.hover(filename)
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Private: hovers on a point relative to a Region's top left corner
+    #
+    # x         - a Fixnum representing the x component of the point to hover
+    # y         - a Fixnum representing the y component of the point to hover
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def hover_point(x, y)
+      @java_obj.hover(offset_location(x, y))
+    end
+
+    # Private: create a new instance of Location
+    #
+    # x         - a Fixnum representing the x component of the point to hover
+    # y         - a Fixnum representing the y component of the point to hover
+    #
+    # Return location class instance
+    def location(x, y)
+      org.sikuli.script::Location.new(x, y)
+    end
+
+    # Private: location with offset
+    #
+    # x         - a Fixnum representing the x component of the point to hover
+    # y         - a Fixnum representing the y component of the point to hover
+    #
+    # Return new location
+    def offset_location(x, y)
+      location(x, y).offset(x(), y())
+    end
+  end
+end

data/lib/rukuli/config.rb

@@ -0,0 +1,67 @@
+# Config variables for the Sikuli driver
+#
+module Rukuli
+  class Config
+    class << self
+
+      # Public: the Boolean representing whether or not to perform a 1 second
+      # highlight when an image is matched through Searchable#find,
+      # Searchable#find_all. Defaults to false.
+      attr_accessor :highlight_on_find
+
+      # Public: the absolute file path where Sikuli will look for images when
+      # a just a filename is passed to a search or click method
+      #
+      # Returns the String representation of the path
+      def image_path
+        java.lang.System.getProperty("SIKULI_IMAGE_PATH")
+      end
+
+      # Public: the setter for the absolute file path where Sikuli will search
+      # for images with given a filename as an image
+      #
+      # Examples
+      #
+      #  Rukuli::Config.image_path = "/Users/andreanastacio/rukuli/images/"
+      #
+      # Returns nothing
+      def image_path=(path)
+        java.lang.System.setProperty("SIKULI_IMAGE_PATH", path)
+      end
+
+      # Public: turns stdout logging on and off for the Sikuli java classes.
+      # Defaults to true.
+      #
+      # Examples
+      #
+      #  Rukuli::Config.logging = false
+      #
+      # Returns nothing
+      def logging=(boolean)
+        return unless [TrueClass, FalseClass].include? boolean.class
+        org.sikuli.basics::Settings.InfoLogs   = boolean
+        org.sikuli.basics::Settings.ActionLogs = boolean
+        org.sikuli.basics::Settings.DebugLogs  = boolean
+      end
+
+      # Public: convienence method for grouping the setting of config
+      # variables
+      #
+      # Examples
+      #
+      #   Rukuli::Config.run do |config|
+      #     config.logging = true
+      #     config.image_path = "/User/andreanastacio/images"
+      #     config.highlight_on_find = true
+      #   end
+      #
+      # Returns nothing
+      def run(*args)
+        if block_given?
+          yield self
+        end
+      end
+
+    end
+  end
+end

data/lib/rukuli/exception.rb

@@ -0,0 +1,14 @@
+# Exception classes for Sikuli image searching and matching
+#
+module Rukuli
+
+  # Thrown when Sikuli is unable to find a match within the region for the
+  # file given.
+  #
+  class ImageNotFound < StandardError; end
+
+  # Thrown when a filename is given that is not found on disk in the image
+  # path. Image path can be configured using Rukuli::Config.image_path
+  #
+  class FileDoesNotExist < StandardError; end
+end

data/lib/rukuli/key_code.rb

@@ -0,0 +1,21 @@
+require 'java'
+java_import 'org.sikuli.script.Key'
+java_import 'org.sikuli.script.KeyModifier'
+
+#
+# These constants represent keyboard codes for interacting with the keyboard.
+# Keyboard interaction is defined in the Rukuli::Typeable module.
+#
+module Rukuli
+  KEY_CMD   = KeyModifier::META
+  KEY_SHIFT = KeyModifier::SHIFT
+  KEY_CTRL  = KeyModifier::CTRL
+  KEY_ALT   = KeyModifier::ALT
+  
+  KEY_BACKSPACE = Key::BACKSPACE
+  KEY_RETURN    = Key::ENTER
+  LEFT_ARROW    = Key::LEFT
+  RIGHT_ARROW   = Key::RIGHT
+  UP_ARROW      = Key::UP
+  DOWN_ARROW    = Key::DOWN
+end

data/lib/rukuli/platform.rb

@@ -0,0 +1,12 @@
+module Rukuli
+  class Platform
+
+    def self.sikuli_script_path
+      path = "#{ENV['SIKULI_HOME']}"
+      if ENV['SIKULI_HOME'].nil?
+        raise LoadError, "Failed to load 'sikuli-script.jar'\nMake sure SIKULI_HOME is set!"
+      end
+      path
+    end
+  end
+end

data/lib/rukuli/region.rb

@@ -0,0 +1,85 @@
+# A Region represents a rectangle on screen. Regions are the main point of
+# interaction for Sikuli actions. Regions can receive actions from the mouse,
+# keyboard, and image search.
+#
+require "rukuli/clickable"
+require "rukuli/typeable"
+require "rukuli/searchable"
+
+module Rukuli
+  class Region
+    include Clickable
+    include Typeable
+    include Searchable
+
+    # Public: creates a new Region object
+    #
+    # args - Array representing x (left bound), y (top), width, height
+    #        4 Fixnums left, top, width, height
+    #        An instance of an org.sikuli.script::Region
+    #
+    #   Examples
+    #
+    #     Region.new([10, 10, 200, 300])
+    #     Region.new(10, 10, 200, 300)
+    #     Region.new(another_region)
+    #
+    # Returns the newly initialized object
+    def initialize(*args)
+      @java_obj = org.sikuli.script::Region.new(*args)
+    end
+
+    # Public: highlight the region with a ~ 5 pixel red border
+    #
+    # seconds - Fixnum length of time to show border
+    #
+    # Returns nothing
+    def highlight(seconds = 1)
+      @java_obj.java_send(:highlight, [Java::int], seconds)
+    end
+
+    # Public: the x component of the top, left corner of the Region
+    def x
+      @java_obj.x()
+    end
+
+    # Public: the y component of the top, left corner of the Region
+    def y
+      @java_obj.y()
+    end
+
+    # Public: the width in pixels of the Region
+    def width
+      @java_obj.w()
+    end
+
+    # Public: the height in pixels of the Region
+    def height
+      @java_obj.h()
+    end
+
+    # Public: provide access to all region methods provided by the SikuliScript API
+    # See http://sikuli.org/doc/java/edu/mit/csail/uid/Region.html
+    def method_missing method_name, *args, &block
+      @java_obj.send method_name, *args, &block
+    end
+
+    private
+
+    # Private: interpret a java NativeException and raises a more descriptive
+    # exception
+    #
+    # exception - The original java exception thrown by the sikuli java_obj
+    # filename  - A string representing the filename to include in the
+    # exception message
+    #
+    # Returns nothing
+    def raise_exception(exception, filename)
+      if exception.message == "org.sikuli.script.FindFailed: ImageFile null not found on disk"
+        raise Rukuli::FileDoesNotExist, "The file '#{filename}' does not exist."
+      else
+        raise Rukuli::ImageNotFound, "The image '#{filename}' did not match in this region."
+      end
+    end
+  end
+end

data/lib/rukuli/screen.rb

@@ -0,0 +1,20 @@
+# A Screen object defines a special type of Rukuli::Region that represents
+# the entire screen.
+#
+# TODO: Test the Screen object with multiple monitors attached.
+#
+module Rukuli
+  class Screen < Region
+
+    # Public: creates a new Screen object
+    #
+    # Examples
+    #
+    #   screen = Rukuli::Screen.new
+    #
+    # Returns the newly initialized Screen object
+    def initialize
+      @java_obj = org.sikuli.script::Screen.new()
+    end
+  end
+end

data/lib/rukuli/searchable.rb

@@ -0,0 +1,134 @@
+# The Rukuli::Searchable module is the heart of Sikuli. It defines the
+# wrapper around Sikuli's on screen image searching and matching capability
+# It is implemented by the Region class.
+#
+module Rukuli
+  module Searchable
+
+    # Public: search for an image within a Region
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #   region.find('needle.png')
+    #   region.find('needle.png', 0.5)
+    #
+    # Returns an instance of Region representing the best match
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def find(filename, similarity = 0.9)
+      begin
+        pattern = build_pattern(filename, similarity)
+        match = Region.new(@java_obj.find(pattern))
+        match.highlight if Rukuli::Config.highlight_on_find
+        match
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Public: search for an image within a region (does not raise ImageNotFound exceptions)
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #   region.find!('needle.png')
+    #   region.find!('needle.png', 0.5)
+    #
+    # Returns the match or nil if no match is found
+    def find!(filename, similarity = 0.9)
+      begin
+        find(filename, similarity)
+      rescue Rukuli::ImageNotFound => e
+        nil
+      end
+    end
+
+    # Public: search for an image within a Region and return all matches
+    #
+    # TODO: Sort return results so they are always returned in the same order
+    # (top left to bottom right)
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #   region.find_all('needle.png')
+    #   region.find_all('needle.png', 0.5)
+    #
+    # Returns an array of Region objects that match the given file and
+    # threshold
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def find_all(filename, similarity = 0.9)
+      begin
+        pattern = build_pattern(filename, similarity)
+        matches = @java_obj.findAll(pattern)
+        regions = matches.collect do |r|
+          match = Region.new(r)
+          match.highlight if Rukuli::Config.highlight_on_find
+          match
+        end
+        regions
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    # Public: wait for a match to appear within a region
+    #
+    # filename   - A String representation of the filename to match against
+    # time       - A Fixnum representing the amount of time to wait defaults
+    # to 2 seconds
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Examples
+    #
+    #    region.wait('needle.png') # wait for needle.png to appear for up to 1 second
+    #    region.wait('needle.png', 10) # wait for needle.png to appear for 10 seconds
+    #
+    # Returns nothing
+    #
+    # Throws Rukuli::FileNotFound if the file could not be found on the system
+    # Throws Rukuli::ImageNotMatched if no matches are found within the region
+    def wait(filename, time = 2, similarity = 0.9)
+      begin
+        pattern = build_pattern(filename, similarity)
+        match = Region.new(@java_obj.wait(pattern, time))
+        match.highlight if Rukuli::Config.highlight_on_find
+        match
+      rescue NativeException => e
+        raise_exception e, filename
+      end
+    end
+
+    private
+
+    # Private: builds a java Pattern to check
+    #
+    # filename   - A String representation of the filename to match against
+    # similarity - A Float between 0 and 1 representing the threshold for
+    # matching an image. Passing 1 corresponds to a 100% pixel for pixel
+    # match. Defaults to 0.9 (90% match)
+    #
+    # Returns a org.sikuli.script::Pattern object to match against
+    def build_pattern(filename, similarity)
+      org.sikuli.script::Pattern.new(filename).similar(similarity)
+    end
+  end
+end

data/lib/rukuli/typeable.rb

@@ -0,0 +1,32 @@
+# Defines interactions with the keyboard. Implemented in the Region class.
+#
+module Rukuli
+  module Typeable
+
+    # Public: Types text as if it was being typed on the keyboard with an
+    # optional key modifier
+    #
+    # text - String representing text to be typed on keyboard
+    # modifier - (optional) Sikilu constant (defined in key_code.rb)
+    # representing key to hold while typing text
+    #
+    # Examples
+    #
+    #   region.type("Hello World")
+    #   region.type("s", Rukuli::KEY_CMD) # saves a file
+    #
+    # Returns nothing
+    def type(text, modifier = 0)
+      @java_obj.type(nil, text, modifier)
+    end
+
+    # Public: Types text then presses the return/enter key on the keyboard
+    #
+    # text - String
+    #
+    # Returns nothing
+    def enter(text)
+      @java_obj.type(text + Sikuli::KEY_RETURN)
+    end
+  end
+end

data/lib/rukuli/version.rb

@@ -0,0 +1,3 @@
+module Rukuli
+  VERSION = "1.0.0"
+end

data/rukuli.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rukuli/version"
+
+Gem::Specification.new do |s|
+  s.add_development_dependency "rspec"
+  s.name        = "rukuli"
+  s.version     = Rukuli::VERSION
+  s.authors     = ["Chas Lemley"]
+  s.email       = ["chas.lemley@gmail.com"]
+  s.homepage    = "https://github.com/andreanastacio/rukuli"
+  s.summary     = %q{Ruby wrapper for Sikuli GUI automation library}
+  s.description = %q{Sikuli allows you to interact with your application's user interface using image based search to automate user actions.}
+
+  s.rubyforge_project = "rukuli"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/spec/rukuli/app_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Rukuli::App do
+  subject { Rukuli::App.new(application "FILE_EXPLORER") }
+
+  its(:window) { should be_an_instance_of Rukuli::Region }
+end

data/spec/rukuli/clickable_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe Rukuli::Region, "#Clickable" do
+  before(:all) do
+    @region = setup_test_area
+  end
+
+  it "should perform a click at 10, 10" do
+    expect { @region.click(12, 12) }.not_to raise_error
+  end
+
+  it "should perform a double click 10, 1040" do
+    expect { @region.double_click(12, 491) }.not_to raise_error
+  end
+
+  it "should perform a double click on an image" do
+    expect { @region.double_click("smiley_face.png") }.not_to raise_error
+  end
+
+  it "should perform a drag and drop" do
+    expect { @region.drag_drop(12, 12, 491, 491) }.not_to raise_error
+  end
+
+  it "should perform a click on an image" do
+    expect { @region.click("smiley_face.png") }.not_to raise_error
+  end
+
+  it "should not perform a click on an image that is outside of the region" do
+    expect { @region.click("apple.png") }.to raise_error(Rukuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
+  end
+
+  it "should perform a click and hold on an image" do
+    expect { @region.click_and_hold(2, "green_apple.png") }.not_to raise_error
+  end
+
+  it "should perform a click and hold on a point" do
+    expect { @region.click_and_hold(2, 100, 100) }.not_to raise_error
+  end
+
+  it "should simulate a mouse scroll wheel up event" do
+    expect { @region.wheel_up(10) }.not_to raise_error
+  end
+
+  it "should simulate a mouse scroll wheel down event" do
+    expect { @region.wheel_down(10) }.not_to raise_error
+  end
+end

data/spec/rukuli/config_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe Rukuli::Config do
+  it "should retain a list of directories to search in for images" do
+    Rukuli::Config.image_path = ""
+    java.lang.System.getProperty("SIKULI_IMAGE_PATH").should == ""
+  end
+
+  it "should allow a path to be added" do
+    Rukuli::Config.run do |config|
+      config.image_path = '/Users/images/'
+    end
+
+    java.lang.System.getProperty("SIKULI_IMAGE_PATH").should == '/Users/images/'
+    Rukuli::Config.image_path.should == '/Users/images/'
+  end
+
+  it "should allow logging to be turned on" do
+    Rukuli::Config.run do |config|
+      config.logging = true
+    end
+
+    org.sikuli.basics::Settings.InfoLogs.should be_true
+    org.sikuli.basics::Settings.ActionLogs.should be_true
+    org.sikuli.basics::Settings.DebugLogs.should be_true
+  end
+
+  it "should allow logging to be turned off" do
+    Rukuli::Config.run do |config|
+      config.logging = false
+    end
+
+    org.sikuli.basics::Settings.InfoLogs.should be_false
+    org.sikuli.basics::Settings.ActionLogs.should be_false
+    org.sikuli.basics::Settings.DebugLogs.should be_false
+  end
+
+  it "should allow us to turn off highlighting on find" do
+    Rukuli::Config.highlight_on_find = false
+    Rukuli::Config.highlight_on_find.should be_false
+  end
+
+  it "should allow us to turn on highlighting on find" do
+    Rukuli::Config.highlight_on_find = true
+    Rukuli::Config.highlight_on_find.should be_true
+  end
+end

data/spec/rukuli/region_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe Rukuli::Region, 'when initialized with a rectangle' do
+  subject { Rukuli::Region.new(10, 15, 250, 400) }
+  its(:x) { should == 10 }
+  its(:y) { should == 15 }
+  its(:width) { should == 250 }
+  its(:height) { should == 400 }
+end
+
+describe Rukuli::Region, 'when initialzed with a sikuli region' do
+  subject { Rukuli::Region.new org.sikuli.script::Region.new(11, 16, 251, 401) }
+  its(:x) { should == 11 }
+  its(:y) { should == 16 }
+  its(:width) { should == 251 }
+  its(:height) { should == 401 }
+end

data/spec/rukuli/screen_spec.rb

@@ -0,0 +1,12 @@
+require 'spec_helper'
+
+describe Rukuli::Screen, 'when initialized' do
+  subject { Rukuli::Screen.new }
+
+  its(:x) { should == 0 }
+  its(:y) { should == 0 }
+  its(:width) { should > 0 } # screen's resolution
+  its(:width) { should be_instance_of Fixnum }
+  its(:height) { should > 0 } # screen's resolution
+  its(:height) { should be_instance_of Fixnum }
+end

data/spec/rukuli/searchable_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+describe Rukuli::Region, "#Searchable" do
+  before(:all) do
+    @region = setup_test_area
+  end
+
+  it "should find an image within the region" do
+    @region.find("smiley_face.png").should_not be_nil
+  end
+
+  it "should return a region containing the found image" do
+    @region.find("smiley_face.png").should be_an_instance_of Rukuli::Region
+  end
+
+  it "should raise an error if a file can not be found" do
+    expect { @region.find("no_photo.png") }.to raise_error(Rukuli::FileDoesNotExist, "The file 'no_photo.png' does not exist.")
+  end
+
+  it "should not find an image that is not in the region" do
+    expect { @region.find("apple.png") }.to raise_error(Rukuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
+  end
+
+  it "should return true if the image is found" do
+    @region.find!("smiley_face.png").should be_an_instance_of Rukuli::Region
+  end
+
+  it "should return nil if the image is not found" do
+    @region.find!("apple.png").should be_nil
+  end
+
+  it "should raise an exception if the file does not exist" do
+    expect { @region.find!("no_photo.png") }.to raise_error(Rukuli::FileDoesNotExist, "The file 'no_photo.png' does not exist.")
+  end
+
+  context "#wait" do
+    it "should raise an error if no match is found after a given time" do
+      expect { @region.wait('apple.png') }.to raise_error(Rukuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
+    end
+
+    it "should return a Region object when a match is found" do
+      match = @region.wait('green_apple.png', 5)
+      match.should be_an_instance_of Rukuli::Region
+    end
+  end
+
+  context "#find_all" do
+    before(:all) do
+      @matches = @region.find_all("green_apple.png")
+    end
+
+    it "should raise an error if no matches are found" do
+      expect { @region.find_all("apple.png") }.to raise_error(Rukuli::ImageNotFound, "The image 'apple.png' did not match in this region.")
+    end
+
+    it "should return an array" do
+      @matches.should be_an_instance_of Array
+    end
+
+    it "should contain 4 matches" do
+      @matches.length.should == 4
+    end
+
+    it "should contain regions" do
+      @matches.each do |m|
+        m.should be_an_instance_of Rukuli::Region
+      end
+    end
+  end
+end

data/spec/rukuli/typeable_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+describe Rukuli::Region, "#Typeable" do
+  before(:all) do
+    app = Rukuli::App.new(application "TEXT_EDIT")
+    app.focus
+    @region = app.window
+  end
+
+  context "modifying text input with" do
+    it "apple key" do
+      @region.type("n", Rukuli::KEY_CMD)
+    end
+
+    it "shift key" do
+      @region.type("this should be lower case")
+      @region.type("this should be upper case", Rukuli::KEY_SHIFT)
+    end
+  end
+
+  context "unicode characters" do
+    it("backspace")   { @region.type(Rukuli::KEY_BACKSPACE * 50) }
+    it("return")      { @region.type(Rukuli::KEY_RETURN) }
+    it("left arrow")  { @region.type(Rukuli::LEFT_ARROW) }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+require 'java'
+
+require 'yaml'
+require 'rspec'
+require 'rukuli'
+
+APPLICATIONS = YAML.load(File.open("#{Dir.pwd}/spec/support/applications.yml"))
+
+Rukuli::Config.logging = false
+
+def application(app)
+  APPLICATIONS[app].select { |k, _| k =~ /#{RbConfig::CONFIG['host_os']}/ }.shift[1]
+end
+
+def setup_test_area
+  Rukuli::Config.image_path = "#{Dir.pwd}/spec/support/images/"
+  screen = Rukuli::Screen.new
+  app = Rukuli::App.new(application "IMAGE_VIEWER")
+  app.focus()
+  center = screen.find("#{Dir.pwd}/spec/support/images/smiley_face.png")
+
+  test_area = Rukuli::Region.new(center.x - 212, center.y - 212, 503, 503)
+  test_area.highlight
+
+  test_area
+end

data/spec/support/applications.yml

@@ -0,0 +1,15 @@
+IMAGE_VIEWER:
+  darwin|mac os:
+    'Preview'
+  cygwin|mswin|mingw|bccwin|wince|emx|mswin32:
+    "explorer"
+FILE_EXPLORER:
+  darwin|mac os:
+    'Finder'
+  cygwin|mswin|mingw|bccwin|wince|emx|mswin32:
+    "explorer"
+TEXT_EDIT:
+  darwin|mac os:
+    'TextEdit'
+  cygwin|mswin|mingw|bccwin|wince|emx|mswin32:
+    "notepad"

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: rukuli
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chas Lemley
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2014-01-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  prerelease: false
+  type: :development
+description: Sikuli allows you to interact with your application's user interface using image based search to automate user actions.
+email:
+- chas.lemley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- License.txt
+- README.md
+- Rakefile
+- lib/rukuli.rb
+- lib/rukuli/app.rb
+- lib/rukuli/clickable.rb
+- lib/rukuli/config.rb
+- lib/rukuli/exception.rb
+- lib/rukuli/key_code.rb
+- lib/rukuli/platform.rb
+- lib/rukuli/region.rb
+- lib/rukuli/screen.rb
+- lib/rukuli/searchable.rb
+- lib/rukuli/typeable.rb
+- lib/rukuli/version.rb
+- rukuli.gemspec
+- spec/rukuli/app_spec.rb
+- spec/rukuli/clickable_spec.rb
+- spec/rukuli/config_spec.rb
+- spec/rukuli/region_spec.rb
+- spec/rukuli/screen_spec.rb
+- spec/rukuli/searchable_spec.rb
+- spec/rukuli/typeable_spec.rb
+- spec/spec_helper.rb
+- spec/support/applications.yml
+- spec/support/images/apple.png
+- spec/support/images/green_apple.png
+- spec/support/images/smiley_face.png
+- spec/support/images/test_area.jpg
+homepage: https://github.com/andreanastacio/rukuli
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: rukuli
+rubygems_version: 2.1.9
+signing_key:
+specification_version: 4
+summary: Ruby wrapper for Sikuli GUI automation library
+test_files:
+- spec/rukuli/app_spec.rb
+- spec/rukuli/clickable_spec.rb
+- spec/rukuli/config_spec.rb
+- spec/rukuli/region_spec.rb
+- spec/rukuli/screen_spec.rb
+- spec/rukuli/searchable_spec.rb
+- spec/rukuli/typeable_spec.rb
+- spec/spec_helper.rb
+- spec/support/applications.yml
+- spec/support/images/apple.png
+- spec/support/images/green_apple.png
+- spec/support/images/smiley_face.png
+- spec/support/images/test_area.jpg