AXElements 0.6.0beta1

data/lib/mouse.rb

@@ -0,0 +1,185 @@
+##
+# [Reference](http://developer.apple.com/library/mac/#documentation/Carbon/Reference/QuartzEventServicesRef/Reference/reference.html).
+#
+# @todo Inertial scrolling
+# @todo Bezier paths
+# @todo More intelligent default duration
+# @todo Point arguments should accept a pair tuple...or should they?
+# @todo Refactor to try and reuse the same event for a single action
+#       instead of creating new events.
+# @todo Pause between down/up clicks
+module Mouse; end
+
+class << Mouse
+
+  ##
+  # Number of animation steps per second.
+  #
+  # @return [Number]
+  FPS     = 120
+
+  ##
+  # @note We keep the number as a rational to try and avoid rounding
+  #       error introduced by the way MacRuby deals with floats.
+  #
+  # Smallest unit of time allowed for an animation step.
+  #
+  # @return [Number]
+  QUANTUM = Rational(1, FPS)
+
+  ##
+  # Available constants for the type of units to use when scrolling.
+  #
+  # @return [Hash{Symbol=>Fixnum}]
+  UNIT = {
+    line:  KCGScrollEventUnitLine,
+    pixel: KCGScrollEventUnitPixel
+  }
+
+  ##
+  # The coordinates of the mouse using the flipped coordinate system
+  # (origin in top left).
+  #
+  # @return [CGPoint]
+  def current_position
+    CGEventGetLocation(CGEventCreate(nil))
+  end
+
+  ##
+  # Move the mouse from the current position to the given point.
+  #
+  # @param [CGPoint]
+  # @param [Float] duration animation duration, in seconds
+  def move_to point, duration = 0.2
+    animate KCGEventMouseMoved, KCGMouseButtonLeft, current_position, point, duration
+  end
+
+  ##
+  # Click and drag from the current position to the given point.
+  #
+  # @param [CGPoint]
+  # @param [Float] duration animation duration, in seconds
+  def drag_to point, duration = 0.2
+    event = CGEventCreateMouseEvent(nil, KCGEventLeftMouseDown, current_position, KCGMouseButtonLeft)
+    CGEventPost(KCGHIDEventTap, event)
+    animate KCGEventLeftMouseDragged, KCGMouseButtonLeft, current_position, point, duration
+    event = CGEventCreateMouseEvent(nil, KCGEventLeftMouseUp, current_position, KCGMouseButtonLeft)
+    CGEventPost(KCGHIDEventTap, event)
+  end
+
+  ##
+  # @todo Need to double check to see if I introduce any inaccuracies.
+  #
+  # Scroll at the current position the given amount of units.
+  #
+  # Scrolling too much or too little in a period of time will cause the
+  # animation to look weird, possibly causing the app to mess things up.
+  #
+  # @param [Fixnum] amount number of units to scroll; positive to scroll
+  #   up or negative to scroll down
+  # @param [Float] duration animation duration, in seconds
+  # @param [Fixnum] units `:line` scrolls by line, `:pixel` scrolls by pixel
+  def scroll amount, duration = 0.2, units = :line
+    units   = UNIT[units] || raise(ArgumentError, "#{units} is not a valid unit")
+    steps   = (FPS * duration).floor
+    current = 0.0
+    steps.times do |step|
+      done     = (step+1).to_f / steps
+      scroll   = ((done - current)*amount).floor
+      # the fixnum arg represents the number of scroll wheels
+      # on the mouse we are simulating (up to 3)
+      event = CGEventCreateScrollWheelEvent(nil, units, 1, scroll)
+      CGEventPost(KCGHIDEventTap, event)
+      sleep QUANTUM
+      current += scroll.to_f / amount
+    end
+  end
+
+  ##
+  # A standard click. Default position is the current position.
+  #
+  # @param [CGPoint]
+  def click point = current_position
+    event = CGEventCreateMouseEvent(nil, KCGEventLeftMouseDown, point, KCGMouseButtonLeft)
+    CGEventPost(KCGHIDEventTap, event)
+    # @todo Should not set number of sleep frames statically.
+    12.times do sleep QUANTUM end
+    CGEventSetType(event, KCGEventLeftMouseUp)
+    CGEventPost(KCGHIDEventTap, event)
+  end
+
+  ##
+  # Standard secondary click. Default position is the current position.
+  #
+  # @param [CGPoint]
+  def secondary_click point = current_position
+    event = CGEventCreateMouseEvent(nil, KCGEventRightMouseDown, point, KCGMouseButtonRight)
+    CGEventPost(KCGHIDEventTap, event)
+    CGEventSetType(event, KCGEventRightMouseUp)
+    CGEventPost(KCGHIDEventTap, event)
+  end
+  alias_method :right_click, :secondary_click
+
+  ##
+  # A standard double click. Defaults to clicking at the current position.
+  #
+  # @param [CGPoint]
+  def double_click point = current_position
+    event = CGEventCreateMouseEvent(nil, KCGEventLeftMouseDown, point, KCGMouseButtonLeft)
+    CGEventPost(KCGHIDEventTap, event)
+    CGEventSetType(event,       KCGEventLeftMouseUp)
+    CGEventPost(KCGHIDEventTap, event)
+
+    CGEventSetIntegerValueField(event, KCGMouseEventClickState, 2)
+    CGEventSetType(event,       KCGEventLeftMouseDown)
+    CGEventPost(KCGHIDEventTap, event)
+    CGEventSetType(event,       KCGEventLeftMouseUp)
+    CGEventPost(KCGHIDEventTap, event)
+  end
+
+  ##
+  # Click with an arbitrary mouse button, using numbers to represent
+  # the mouse button. At the time of writing, the documented values are:
+  #
+  #  - KCGMouseButtonLeft   = 0
+  #  - KCGMouseButtonRight  = 1
+  #  - KCGMouseButtonCenter = 2
+  #
+  # And the rest are not documented! Though they should be easy enough
+  # to figure out. See the `CGMouseButton` enum in the reference
+  # documentation for the most up to date list.
+  #
+  # @param [CGPoint]
+  # @param [Number]
+  def arbitrary_click point = current_position, button = KCGMouseButtonCenter
+    event = CGEventCreateMouseEvent(nil, KCGEventOtherMouseDown, point, button)
+    CGEventPost(KCGHIDEventTap, event)
+    CGEventSetType(event, KCGEventOtherMouseUp)
+    CGEventPost(KCGHIDEventTap, event)
+  end
+  alias_method :other_click, :arbitrary_click
+
+
+  private
+
+  ##
+  # Executes a mouse movement animation. It can be a simple cursor
+  # move or a drag depending on what is passed to `type`.
+  def animate type, button, from, to, duration
+    steps = (FPS * duration).floor
+    xstep = (to.x - from.x) / steps
+    ystep = (to.y - from.y) / steps
+    steps.times do
+      from.x += xstep
+      from.y += ystep
+      event = CGEventCreateMouseEvent(nil, type, from, button)
+      CGEventPost(KCGHIDEventTap, event)
+      sleep QUANTUM
+    end
+    $stderr.puts 'Not moving anywhere' if from == to
+    event = CGEventCreateMouseEvent(nil, type, to, button)
+    CGEventPost(KCGHIDEventTap, event)
+    sleep QUANTUM
+  end
+
+end

data/lib/rspec/expectations/ax_elements.rb

@@ -0,0 +1,15 @@
+require 'rspec/expectations'
+
+##
+# Custom RSpec matchers for AXElements.
+module RSpec::Expectations
+
+  ##
+  # app.window.button.should be_visible
+  class BeVisible
+  end
+
+  class BeInFrame
+  end
+
+end

data/test/elements/test_application.rb

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+class TestAXApplication < TestAX
+
+  APP = AX::Application.new REF, AX.attrs_of_element(REF)
+
+  def test_is_a_direct_subclass_of_element
+    assert_equal AX::Element, AX::Application.superclass
+  end
+
+  def app inst
+    inst.instance_variable_get :@app
+  end
+
+  def test_can_set_focus_to_an_app
+    app(APP).hide
+    sleep 0.2
+    refute APP.active?
+    APP.set_attribute :focused, true
+    sleep 0.2
+    assert APP.active?
+  ensure
+    app(APP).activateWithOptions NSApplicationActivateIgnoringOtherApps
+  end
+
+  def test_can_hide_the_app
+    APP.set_attribute :focused, false
+    sleep 0.2
+    refute APP.active?
+  ensure
+    app(APP).activateWithOptions NSApplicationActivateIgnoringOtherApps
+  end
+
+  def test_attribute_has_special_case_for_focused
+    assert_instance_of_boolean APP.attribute :focused?
+    assert_instance_of_boolean APP.attribute :focused
+  end
+
+  def test_attribute_still_works_for_other_attributes
+    assert_equal 'AXElementsTester', APP.title
+  end
+
+  def test_inspect_includes_pid
+    assert_match /\spid=\d+/, APP.inspect
+  end
+
+  def test_inspect_includes_focused
+    assert_match /\sfocused\[(?:✔|✘)\]/, APP.inspect
+  end
+
+  def test_type_string_forwards_call
+    class << AX
+      alias_method :old_keyboard_action, :keyboard_action
+      def keyboard_action element, string
+        true if string == 'test' && element == TestAX::REF
+      end
+    end
+    assert APP.type_string('test')
+  ensure
+    class << AX; alias_method :keyboard_action, :old_keyboard_action; end
+  end
+
+  def test_terminate_kills_app
+    skip 'Not sure how to reset state after this test...'
+    assert AX::DOCK.terminate
+  end
+
+  def test_dock_constant_is_set
+    assert_instance_of AX::Application, AX::DOCK
+    assert_equal 'Dock', AX::DOCK.attribute(:title)
+  end
+
+end

data/test/elements/test_row.rb

@@ -0,0 +1,27 @@
+class TestElementsRowChildInColumn < TestAX
+
+  # these tests depend on Search already working
+
+  APP = AX::Application.new REF, AX.attrs_of_element(REF)
+
+  def table
+    @@table ||= APP.main_window.table
+  end
+
+  def rows
+    @@rows ||= table.rows
+  end
+
+  def test_returns_correct_column
+    row = rows.first
+    assert_equal row.children.second, row.child_in_column(header: 'Two')
+    assert_equal row.children.first,  row.child_in_column(header: 'One')
+  end
+
+  def test_raises_seach_failure_if_nothing_found
+    assert_raises AX::Element::SearchFailure do
+      rows.first.child_in_column(header: 'Fifty')
+    end
+  end
+
+end

data/test/elements/test_systemwide.rb

@@ -0,0 +1,38 @@
+class TestAXSystemWide < MiniTest::Unit::TestCase
+
+  def test_is_singleton
+    assert_raises NoMethodError do
+      AX::SystemWide.new
+    end
+    assert_respond_to AX::SystemWide, :instance
+  end
+
+  def test_type_string_makes_appropriate_callback
+    class << AX
+      alias_method :old_keyboard_action, :keyboard_action
+      def keyboard_action element, string
+        true if string == 'test' && element == AXUIElementCreateSystemWide()
+      end
+    end
+    assert AX::SYSTEM.type_string('test')
+  ensure
+    class << AX; alias_method :keyboard_action, :old_keyboard_action; end
+  end
+
+  def test_search_not_allowed
+    assert_raises NoMethodError do
+      AX::SYSTEM.search
+    end
+  end
+
+  def test_notifications_not_allowed
+    assert_raises NoMethodError do
+      AX::SYSTEM.search
+    end
+  end
+
+  def test_expose_instance_as_constant
+    assert_instance_of AX::SystemWide, AX::SYSTEM
+  end
+
+end

data/test/helper.rb

@@ -0,0 +1,119 @@
+require 'rubygems'
+
+require 'ax_elements'
+require 'stringio'
+
+# Accessibility.log.level = Logger::DEBUG
+
+# We want to launch the test app and make sure it responds to
+# accessibility queries, but that is difficult, so we just sleep
+APP_BUNDLE_URL = NSURL.URLWithString File.expand_path './test/fixture/Release/AXElementsTester.app'
+
+error = Pointer.new :id
+TEST_APP = NSWorkspace.sharedWorkspace.launchApplicationAtURL APP_BUNDLE_URL,
+                                                     options: NSWorkspaceLaunchAsync,
+                                               configuration: {},
+                                                       error: error
+if error[0]
+  $stderr.puts 'You need to build AND run the fixture app before running tests'
+  $stderr.puts 'Run `rake fixture`'
+  exit 3
+else
+  sleep 3 # I haven't yet figured out a good way of knowing exactly
+          # when the app is ready
+  # Make sure the test app is closed when testing finishes
+  at_exit do TEST_APP.terminate end
+end
+
+
+gem     'minitest'
+require 'minitest/autorun'
+
+# preprocessor powers, assemble!
+if ENV['BENCH']
+  require 'minitest/benchmark'
+else
+  require'minitest/pride'
+end
+
+
+class MiniTest::Unit::TestCase
+  # You may need this to help track down an issue if a test is crashing MacRuby
+  # def self.test_order
+  #   :alpha
+  # end
+
+  def assert_instance_of_boolean value
+    message = "Expected #{value.inspect} to be a boolean"
+    assert value.is_a?(TrueClass) || value.is_a?(FalseClass), message
+  end
+
+  def self.bench_range
+    bench_exp 10, 10_000
+  end
+end
+
+##
+# A mix in module to allow capture of logs
+module LoggingCapture
+  def setup
+    super
+    @log_output = StringIO.new
+    Accessibility.log = Logger.new @log_output
+  end
+end
+
+module AXHelpers
+  def pid_for name
+    NSWorkspace.sharedWorkspace.runningApplications.find do |app|
+      app.bundleIdentifier == name
+    end.processIdentifier
+  end
+
+  # returns raw attribute
+  def attribute_for element, attr
+    ptr = Pointer.new :id
+    AXUIElementCopyAttributeValue(element, attr, ptr)
+    ptr[0]
+  end
+
+  def children_for element
+    attribute_for element, KAXChildrenAttribute
+  end
+
+  def value_for element
+    attribute_for element, KAXValueAttribute
+  end
+
+  def action_for element, action
+    AXUIElementPerformAction(element, action)
+  end
+
+  # remember to wrap structs in an AXValueRef
+  def set_attribute_for element, attr, value
+    AXUIElementSetAttributeValue(element, attr, value)
+  end
+end
+
+class TestAX < MiniTest::Unit::TestCase
+  include AXHelpers
+  extend AXHelpers
+
+  APP_BUNDLE_IDENTIFIER = 'com.marketcircle.AXElementsTester'
+  PID = pid_for APP_BUNDLE_IDENTIFIER
+  REF = AXUIElementCreateApplication(PID)
+
+  # execute the block with full logging turned on
+  def with_logging level = Logger::DEBUG
+    original_level = Accessibility.log.level
+    Accessibility.log.level = level
+    yield
+    Accessibility.log.level = original_level
+  end
+end
+
+##
+# Just pretend that you didnt' see this hack
+class AX::Element
+  attr_reader :ref
+end

data/test/test_accessibility.rb

@@ -0,0 +1,127 @@
+class TestAccessibility < TestAX
+
+  APP = AX::Application.new REF, AX.attrs_of_element(REF)
+
+  def close_button
+    @@button ||= APP.attribute(:main_window).attribute(:children).find do |item|
+      item.class == AX::CloseButton
+    end
+  end
+
+  def test_path_returns_correct_elements_in_correct_order
+    list = Accessibility.path(APP.main_window.close_button)
+    assert_equal 3, list.size
+    assert_instance_of AX::CloseButton,    list.first
+    assert_instance_of AX::StandardWindow, list.second
+    assert_instance_of AX::Application,    list.third
+  end
+
+  def test_graph
+    skip 'ZOMG, yeah right'
+  end
+
+  def test_dump_works_for_nested_tab_groups
+    element = APP.main_window.children.find { |item| item.role == KAXTabGroupRole }
+    output  = Accessibility.dump(element)
+
+    refute_empty output
+
+    expected = [
+                ['AX::TabGroup',    0],
+                ['AX::RadioButton', 1], ['AX::RadioButton', 1], ['AX::TabGroup', 1],
+                ['AX::RadioButton', 2], ['AX::RadioButton', 2], ['AX::TabGroup', 2],
+                ['AX::RadioButton', 3], ['AX::RadioButton', 3], ['AX::TabGroup', 3],
+                ['AX::RadioButton', 4], ['AX::RadioButton', 4],
+                ['AX::Group', 4],
+                ['AX::TextField',   5], ['AX::StaticText',  6],
+                ['AX::TextField' ,  5], ['AX::StaticText',  6]
+               ]
+
+    output = output.split("\n")
+
+    until output.empty?
+      actual_line             = output.shift
+      expected_klass, indents = expected.shift
+      assert_equal indents, actual_line.match(/^\t*/).to_a.first.length, actual_line
+      actual_line.strip!
+      assert_match /^\#<#{expected_klass}/, actual_line
+    end
+  end
+
+  def test_returns_some_kind_of_ax_element
+    assert_kind_of AX::Element, Accessibility.element_under_mouse
+  end
+
+  def test_returns_element_under_the_mouse
+    button = APP.main_window.close_button
+    Mouse.move_to button.to_point, 0
+    # sleep 0.05 # how often will this fail without waiting?
+    assert_equal button, Accessibility.element_under_mouse
+  end
+
+  def test_element_at_point_returns_button_when_given_buttons_coordinates
+    point = close_button.position
+    assert_equal close_button, Accessibility.element_at_point(*point.to_a)
+    assert_equal close_button, Accessibility.element_at_point(point.to_a)
+    assert_equal close_button, Accessibility.element_at_point(point)
+  end
+
+  def test_elemnent_at_point_is_element_at_position
+    assert_equal Accessibility.method(:element_at_point), Accessibility.method(:element_at_position)
+  end
+
+  def test_application_with_name_gets_app_if_running
+    ret = Accessibility.application_with_name 'Dock'
+    assert_instance_of AX::Application, ret
+    assert_equal       'Dock', ret.title
+  end
+
+  def test_application_with_name_gets_nil_if_not_found
+    assert_nil Accessibility.application_with_name('App That Does Not Exist')
+  end
+
+  def test_application_with_name_called_before_and_after_app_is_running
+    skip 'This is a bug that was fixed but should have a test'
+  end
+
+  def test_app_with_bundle_id_returns_the_correct_app
+    ret = Accessibility.application_with_bundle_identifier(APP_BUNDLE_IDENTIFIER)
+    assert_instance_of AX::Application, ret
+    assert_equal APP, ret
+  end
+
+  def test_app_with_bundle_id_return_app_if_app_is_running
+    app = Accessibility.application_with_bundle_identifier 'com.apple.dock'
+    assert_equal 'Dock', app.attribute(:title)
+  end
+
+  # @todo how do we test when app is not already running?
+
+  def test_launches_app_if_it_is_not_running
+    def grabbers
+      NSRunningApplication.runningApplicationsWithBundleIdentifier( 'com.apple.Grab' )
+    end
+    grabbers.each do |dude| dude.terminate end
+    assert_empty grabbers
+    Accessibility.application_with_bundle_identifier( 'com.apple.Grab' )
+    refute_empty grabbers
+  ensure
+    grabbers.each do |dude| dude.terminate end
+  end
+
+  def test_app_with_bundle_id_times_out_if_app_cannot_be_launched
+    skip 'This is difficult to do...'
+  end
+
+  def test_app_with_bundle_id_allows_override_of_the_sleep_time
+    skip 'This is difficult to test...'
+  end
+
+  # @note a bad pid will crash MacRuby
+  def test_application_with_pid_gives_me_the_application
+    pid = APP.pid
+    app = Accessibility.application_with_pid(pid)
+    assert_equal APP, app
+  end
+
+end

data/test/test_blankness.rb

@@ -0,0 +1,26 @@
+class TestBlankPredicate < TestAX
+
+  def test_nil_returns_true
+    assert_equal true, nil.blank?
+  end
+
+  def test_nsarray_responds
+    assert_respond_to NSArray.array, :blank?
+  end
+
+  def test_nsarray_uses_alias_to_empty?
+    ary = NSArray.array
+    assert_equal ary.method(:empty?), ary.method(:blank?)
+  end
+
+  def test_element_always_returns_false
+    app    = AX::Element.new REF, AX.attrs_of_element(REF)
+    window = app.attribute(:main_window)
+    assert_equal false, window.blank?
+    assert_equal false, app.blank?
+  end
+
+  # other objects do not implement the method because it is not
+  # useful for them to
+
+end