AXElements 0.6.0beta2 → 0.7.5

data/lib/minitest/ax_elements.rb

@@ -1,19 +1,119 @@
+require 'ax/element'
+require 'accessibility/qualifier'
+
 ##
-#
-class MiniTest::Unit::TestCase
-  # @yield
-  def assert_exists
-    begin
-      yield.blank?
-      # blank? if nothing found, kind_of Element otherwise
-    rescue AX::Element::SearchFailure => e
-      # problem somewhere in the path
-    end
-    assert_respond_to
+# AXElements assertions for MiniTest.
+# [Learn more about minitest.](https://github.com/seattlerb/minitest)
+class MiniTest::Assertions
+
+  ##
+  # Test that an element has a specific child. For example, test
+  # that a table has a row with certain contents. You can pass any
+  # filters that you normally would during a search, including a block.
+  #
+  # @example
+  #
+  #   assert_has_child table, :row, static_text: { value: 'Mark' }
+  #
+  # @param [AX::Element]
+  # @param [#to_s]
+  # @param [Hash]
+  # @return [AX::Element]
+  def assert_has_child parent, kind, filters = {}, &block
+    msg = message {
+      child = ax_search_id kind, filters, block
+      "Expected #{parent.inspect} to have #{child} as a child"
+    }
+    result = ax_check_children parent, kind, filters, block
+    refute result.blank?, msg
+    result
+  end
+
+  ##
+  # Test that an element has a specifc descendent. For example, test
+  # that a window contains a specific label. You can pass any filters
+  # that you normally would during a search, including a block.
+  #
+  # @example
+  #
+  #   assert_has_descendent window, :static_text, value: /Cake/
+  #
+  # @param [AX::Element]
+  # @param [#to_s]
+  # @param [Hash]
+  # @return [AX::Element]
+  def assert_has_descendent ancestor, kind, filters = {}, &block
+    msg = message {
+      descendent = ax_search_id kind, filters, block
+      "Expected #{ancestor.inspect} to have #{descendent} as a descendent"
+    }
+    result = ax_check_descendent ancestor, kind, filters, block
+    refute result.blank?, msg
+    result
   end
+  alias_method :assert_has_descendant, :assert_has_descendent
 
-  def refute_exists
+  ##
+  # Test that an element _does not_ have a specific child. For example,
+  # test that a row is no longer in a table. You can pass any filters
+  # that you normally would during a search, including a block.
+  #
+  # @example
+  #
+  #   refute_has_child table, :row, id: 'MyRow'
+  #
+  # @param [AX::Element]
+  # @param [#to_s]
+  # @param [Hash]
+  # @return [nil]
+  def refute_has_child parent, kind, filters = {}, &block
+    result = ax_check_children parent, kind, filters, block
+    msg    = message {
+      "Expected #{parent.inspect} not to have #{result} as a child"
+    }
+    assert result.blank?, msg
+    result
   end
+
+  ##
+  # Test that an element _does not_ have a specific descendent. For
+  # example, test that a window does not contain a spinning progress
+  # indicator anymore.
+  #
+  # @example
+  #
+  #  refute_has_descendent window, :busy_indicator
+  #
+  # @param [AX::Element]
+  # @param [#to_s]
+  # @param [Hash]
+  # @return [nil,Array()]
+  def refute_has_descendent ancestor, kind, filters = {}, &block
+    result = ax_check_descendent ancestor, kind, filters, block
+    msg    = message {
+      "Expected #{ancestor.inspect} not to have #{result} as a descendent"
+    }
+    assert result.blank?, msg
+    result
+  end
+  alias_method :refute_has_descendant, :refute_has_descendent
+
+
+  private
+
+  def ax_search_id kind, filters, block
+    Accessibility::Qualifier.new(kind, filters, &block).describe
+  end
+
+  def ax_check_children parent, kind, filters, block
+    q = Accessibility::Qualifier.new(kind, filters, &block)
+    parent.attribute(:children).find { |x| q.qualifies? x }
+  end
+
+  def ax_check_descendent ancestor, kind, filters, block
+    ancestor.search(kind, filters, &block)
+  end
+
 end
 
 # @todo assertions for minitest/spec

data/lib/mouse.rb

@@ -1,16 +1,16 @@
+framework 'ApplicationServices'
+
 ##
 # [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
+module Mouse
+  extend self
 
   ##
   # Number of animation steps per second.
@@ -60,11 +60,11 @@ class << Mouse
   # @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)
+    post new_event(KCGEventLeftMouseDown, current_position, KCGMouseButtonLeft)
+
     animate KCGEventLeftMouseDragged, KCGMouseButtonLeft, current_position, point, duration
-    event = CGEventCreateMouseEvent(nil, KCGEventLeftMouseUp, current_position, KCGMouseButtonLeft)
-    CGEventPost(KCGHIDEventTap, event)
+
+    post new_event(KCGEventLeftMouseUp, current_position, KCGMouseButtonLeft)
   end
 
   ##
@@ -78,18 +78,15 @@ class << Mouse
   # @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
+  # @param [Symbol] 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
+    steps   = (FPS * duration).round
     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)
+      post new_scroll_event(units, 1, scroll)
       sleep QUANTUM
       current += scroll.to_f / amount
     end
@@ -99,24 +96,24 @@ class << Mouse
   # 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)
+  def click point = current_position, duration = 12
+    event = new_event KCGEventLeftMouseDown, point, KCGMouseButtonLeft
+    post event
+    duration.times { sleep QUANTUM }
+    set event, to: KCGEventLeftMouseUp
+    post 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)
+  def secondary_click point = current_position, duration = 12
+    event = new_event KCGEventRightMouseDown, point, KCGMouseButtonRight
+    post event
+    duration.times { sleep QUANTUM }
+    set event, to: KCGEventRightMouseUp
+    post event
   end
   alias_method :right_click, :secondary_click
 
@@ -125,16 +122,16 @@ class << Mouse
   #
   # @param [CGPoint]
   def double_click point = current_position
-    event = CGEventCreateMouseEvent(nil, KCGEventLeftMouseDown, point, KCGMouseButtonLeft)
-    CGEventPost(KCGHIDEventTap, event)
-    CGEventSetType(event,       KCGEventLeftMouseUp)
-    CGEventPost(KCGHIDEventTap, event)
+    event = new_event KCGEventLeftMouseDown, point, KCGMouseButtonLeft
+    post event
+    set  event, to: KCGEventLeftMouseUp
+    post event
 
     CGEventSetIntegerValueField(event, KCGMouseEventClickState, 2)
-    CGEventSetType(event,       KCGEventLeftMouseDown)
-    CGEventPost(KCGHIDEventTap, event)
-    CGEventSetType(event,       KCGEventLeftMouseUp)
-    CGEventPost(KCGHIDEventTap, event)
+    set  event, to: KCGEventLeftMouseDown
+    post event
+    set  event, to: KCGEventLeftMouseUp
+    post event
   end
 
   ##
@@ -151,9 +148,10 @@ class << Mouse
   #
   # @param [CGPoint]
   # @param [Number]
-  def arbitrary_click point = current_position, button = KCGMouseButtonCenter
+  def arbitrary_click point = current_position, button = KCGMouseButtonCenter, duration = 12
     event = CGEventCreateMouseEvent(nil, KCGEventOtherMouseDown, point, button)
     CGEventPost(KCGHIDEventTap, event)
+    duration.times do sleep QUANTUM end
     CGEventSetType(event, KCGEventOtherMouseUp)
     CGEventPost(KCGHIDEventTap, event)
   end
@@ -166,20 +164,48 @@ class << Mouse
   # 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)
+    current = current_position
+    xstep   = (to.x - current.x) / (FPS * duration)
+    ystep   = (to.y - current.y) / (FPS * duration)
+    start   = NSDate.date
+
+    until close_enough?(current, to)
+      remaining  = to.x - current.x
+      current.x += xstep.abs > remaining.abs ? remaining : xstep
+
+      remaining  = to.y - current.y
+      current.y += ystep.abs > remaining.abs ? remaining : ystep
+
+      post new_event(type, current, button)
+
       sleep QUANTUM
+      break if NSDate.date.timeIntervalSinceDate(start) > 5.0
+      current = current_position
     end
-    $stderr.puts 'Not moving anywhere' if from == to
-    event = CGEventCreateMouseEvent(nil, type, to, button)
+  end
+
+  def close_enough? current, target
+    x = current.x - target.x
+    y = current.y - target.y
+    delta = Math.sqrt((x**2) + (y**2))
+    delta <= 1.0
+  end
+
+  def new_event event, position, button
+    CGEventCreateMouseEvent(nil, event, position, button)
+  end
+
+  # @param [Fixnum] wheel which scroll wheel to use (value between 1-3)
+  def new_scroll_event units, wheel, amount
+    CGEventCreateScrollWheelEvent(nil, units, wheel, amount)
+  end
+
+  def post event
     CGEventPost(KCGHIDEventTap, event)
-    sleep QUANTUM
+  end
+
+  def set event, to: state
+    CGEventSetType(event, state)
   end
 
 end

data/lib/rspec/expectations/ax_elements.rb

@@ -1,15 +1,142 @@
-require 'rspec/expectations'
+require 'accessibility/qualifier'
+require 'ax/element'
 
 ##
-# Custom RSpec matchers for AXElements.
-module RSpec::Expectations
+# Custom matcher for RSpec to check if an element has the specified
+# child element.
+class Accessibility::HasChildMatcher
+
+  # @param [#to_s]
+  # @param [Hash]
+  # @yield
+  def initialize kind, filters, &block
+    @qualifier = Accessibility::Qualifier.new(kind, filters, &block)
+  end
+
+  # @param [AX::Element]
+  def matches? parent
+    !search(parent).blank?
+  end
+
+  # @return [String]
+  def failure_message_for_should
+    "Expected #@parent to have child #{@qualifier.describe}"
+  end
+
+  # @param [AX::Element]
+  def does_not_match? parent
+    search(parent).blank?
+  end
+
+  # @return [String]
+  def failure_message_for_should_not
+    "Expected #@parent to NOT have child #@result"
+  end
+
+  ##
+  # Implemented to override `NSObject#description`.
+  #
+  # @return [String]
+  def description
+    "should have a child that matches #{@qualifier.describe}"
+  end
+
+
+  private
+
+  def search parent
+    @parent = parent
+    @result = parent.attribute(:children).find { |x| @qualifier.qualifies? x }
+  end
+
+end
+
+##
+# Assert that the receiving element has the specified child element. You
+# can use any filters you would normally use in a search, including
+# a block.
+#
+# @example
+#
+#   window.toolbar.should have_child(:search_field)
+#   table.should have_child(:row, static_text: { value: /42/ })
+#
+#   search_field.should_not have_child(:busy_indicator)
+#
+# @param [#to_s]
+# @param [Hash]
+# @yield An optional block to be used as part of the search qualifier
+def have_child kind, filters = {}, &block
+  Accessibility::HasChildMatcher.new kind, filters, &block
+end
+
+
+##
+# Custom matcher for RSpec to check if an element has the specified
+# descendent element.
+class Accessibility::HasDescendentMatcher
+
+  # @param [#to_s]
+  # @param [Hash]
+  # @yield
+  def initialize kind, filters, &block
+    @kind, @filters, @block = kind, filters, block
+    @qualifier = Accessibility::Qualifier.new(@kind, @filters, &@block)
+  end
+
+  # @param [AX::Element]
+  def matches? ancestor
+    !search(ancestor).blank?
+  end
+
+  # @return [String]
+  def failure_message_for_should
+    "Expected #@ancestor to have descendent #{@qualifier.describe}"
+  end
+
+  # @param [AX::Element]
+  def does_not_match? ancestor
+    search(ancestor).blank?
+  end
+
+  # @return [String]
+  def failure_message_for_should_not
+    "Expected #@ancestor to NOT have descendent #@result"
+  end
 
   ##
-  # app.window.button.should be_visible
-  class BeVisible
+  # Implemented to override `NSObject#description`.
+  #
+  # @return [String]
+  def description
+    "should have a descendent matching #{@qualifier.describe}"
   end
 
-  class BeInFrame
+
+  private
+
+  def search ancestor
+    @ancestor = ancestor
+    @result   = ancestor.search(@kind, @filters, &@block)
   end
 
 end
+
+##
+# Assert that the given element has the specified descendent. You can
+# pass any parameters you normally would use during a search,
+# including a block.
+#
+# @example
+#
+#   app.main_window.should have_descendent(:button, title: 'Press Me')
+#
+#   row.should_not have_descendent(:check_box)
+#
+# @param [#to_s]
+# @param [Hash]
+# @yield An optional block to be used as part of the search qualifier
+def have_descendent kind, filters = {}, &block
+  Accessibility::HasDescendentMatcher.new kind, filters, &block
+end
+alias :have_descendant :have_descendent

data/rakelib/doc.rake

@@ -0,0 +1,13 @@
+# begin
+#   require 'yard'
+#   YARD::Rake::YardocTask.new
+# rescue LoadError => e
+#   $stderr.puts 'It seems as though you do not have yard installed.'
+#   command = ENV['RUBY_VERSION'] ? 'rake' : 'sudo macrake'
+#   $stderr.puts "You can install it by running `#{command} setup_dev`"
+# end
+
+# desc 'Generate Graphviz object graph'
+# task :garden => :yard do
+#   sh 'yard graph --full --dependencies --dot="-Tpng:quartz" -f docs/images/AX.dot'
+# end

data/rakelib/ext.rake

@@ -0,0 +1,61 @@
+module ExtHelpers
+  def macruby?
+    defined? MACRUBY_REVISION
+  end
+
+  def cruby?
+    RUBY_ENGINE == 'ruby'
+  end
+
+  def needs_regeneration? source, bundle
+    return true unless File.exists? bundle
+    return true unless File.mtime(bundle) > File.mtime(source)
+    return true if macruby? && ext_platform(bundle) == :cruby
+    return true if cruby?   && ext_platform(bundle) == :macruby
+  end
+
+  def ext_platform bundle
+    return :macruby if `otool -L #{bundle}`.match /MacRuby/
+    return :cruby
+  end
+end
+
+
+namespace :ext do
+  extend ExtHelpers
+
+  desc 'Compile C extensions'
+  task :key_coder do
+    dir = 'ext/accessibility/key_coder'
+    ext = "#{dir}/key_coder"
+    if needs_regeneration? "#{ext}.c", "#{ext}.bundle"
+      Rake::Task['clobber_key_coder'].execute
+      Dir.chdir(dir) do
+        ruby 'extconf.rb'
+        sh   'make'
+      end
+      cp "#{ext}.bundle", 'lib/accessibility'
+    end
+  end
+end
+
+
+desc 'Remove files generated by compiling key_coder'
+task :clobber_key_coder do
+  Dir.glob('{lib,ext}/**/*{.bundle,.o}').each do |file|
+    $stdout.puts "rm #{file}"
+    rm_f file
+  end
+  file = 'rm ext/accessibility/key_coder/Makefile'
+  $stdout.puts file
+  rm_f file
+end
+
+desc 'Remove files generated by compiling extensions'
+task :clobber_ext => [:clobber_key_coder]
+
+
+if RUBY_ENGINE == 'macruby'
+  require 'rake/compiletask'
+  Rake::CompileTask.new
+end

data/rakelib/gem.rake

@@ -0,0 +1,28 @@
+require 'rubygems/package_task'
+
+ax_elements = Gem::Specification.load('AXElements.gemspec')
+Gem::PackageTask.new(ax_elements) { }
+
+desc 'Build and install gem (not including deps)'
+task :install => :gem do
+  require 'rubygems/installer'
+  Gem::Installer.new("pkg/#{ax_elements.file_name}").install
+end
+
+desc 'Install dependencies for development'
+task :setup_dev do
+  require 'rubygems/dependency_installer'
+  spec.development_dependencies.each do |dep|
+    puts "Installing #{dep.name} (#{dep.requirement})"
+    Gem::DependencyInstaller.new.install(dep.name, dep.requirement)
+  end
+end
+
+ax_typer = Gem::Specification.load('AXTyper.gemspec')
+Gem::PackageTask.new(ax_typer) { }
+
+desc 'Build and install AXTyper'
+task :install_typer => :gem do
+  require 'rubygems/installer'
+  Gem::Installer.new("pkg/#{ax_typer.file_name}").install
+end

data/rakelib/test.rake

@@ -0,0 +1,53 @@
+desc 'Start up irb with AXElements loaded'
+task :console => :ext do
+  irb = ENV['RUBY_VERSION'] ? 'irb' : 'macirb'
+  sh "#{irb} -Ilib -rubygems -rax_elements"
+end
+
+desc 'Open the fixture app'
+task :run_fixture => :fixture do
+  sh 'open test/fixture/Release/AXElementsTester.app'
+end
+
+desc 'Build the test fixture'
+task :fixture do
+  sh 'cd test/AXElementsTester && xcodebuild'
+end
+
+desc 'Remove the built fixture app'
+task :clobber_fixture do
+  $stdout.puts 'rm -rf test/fixture'
+  rm_rf 'test/fixture'
+end
+task :clobber => :clobber_fixture
+
+require 'rake/testtask'
+namespace :test do
+  Rake::TestTask.new(:sanity) do |t|
+    t.libs   << '.'
+    t.pattern = "test/sanity/**/test_*.rb"
+  end
+  task :sanity => [:ext, :fixture]
+
+  Rake::TestTask.new(:integration) do |t|
+    t.libs   << '.'
+    t.pattern = "test/integration/**/test_*.rb"
+  end
+  task :integration => [:ext, :fixture]
+
+  desc 'Run tests for the string parser'
+  Rake::TestTask.new(:string) do |t|
+    t.libs   << '.'
+    t.pattern = "test/sanity/accessibility/test_string.rb"
+  end
+  task :string => :ext
+
+  desc 'Run tests under CRuby (where applicable)'
+  task :cruby do
+    if ENV['RUBY_VERSION'] # using rvm
+      puts sh 'rvm 1.9.3 do rake test:string'
+    else
+      sh 'rake test:string'
+    end
+  end
+end