AXElements 0.7.8 → 0.8.0

data/lib/minitest/ax_elements.rb

@@ -1,5 +1,6 @@
 require 'ax/element'
 require 'accessibility/qualifier'
+require 'accessibility/dsl'
 
 ##
 # AXElements assertions for MiniTest.
@@ -53,6 +54,34 @@ class MiniTest::Assertions
   end
   alias_method :assert_has_descendant, :assert_has_descendent
 
+  ##
+  # Test that an element will have a child/descendent soon. This method
+  # will block until the element is found or a timeout occurs.
+  #
+  # This is a minitest front end to using {DSL#wait_for}, so any
+  # parameters you would normally pass to that method will work here.
+  # This also means that you must include either a `parent` key or an
+  # `ancestor` key as one of the filters.
+  #
+  # @param [#to_s]
+  # @param [Hash]
+  # @yield An optional block to be used in the search qualifier
+  def assert_shortly_has kind, filters = {}, &block
+    # need to know if parent/ancestor now because wait_for eats some keys
+    (ancest = filters[:ancestor]) || (parent = filters[:parent])
+    msg = message {
+      descend = ax_search_id kind, filters, block
+      if ancest
+        "Expected #{ancest.inspect} to have descendent #{descend} before a timeout occurred"
+      else
+        "Expected #{parent.inspect} to have child #{descend} before a timeout occurred"
+      end
+    }
+    result = wait_for kind, filters, &block
+    refute result.blank?, msg
+    result
+  end
+
   ##
   # 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
@@ -69,7 +98,7 @@ class MiniTest::Assertions
   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"
+      "Expected #{parent.inspect} NOT to have #{result} as a child"
     }
     assert result.blank?, msg
     result
@@ -91,13 +120,42 @@ class MiniTest::Assertions
   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"
+      "Expected #{ancestor.inspect} NOT to have #{result} as a descendent"
     }
     assert result.blank?, msg
     result
   end
   alias_method :refute_has_descendant, :refute_has_descendent
 
+  ##
+  # @todo Does having this assertion make sense? I've only added it
+  #       for the time being because OCD demands it.
+  #
+  # Test that an element will NOT have a child/descendent soon. This
+  # method will block until the element is found or a timeout occurs.
+  #
+  # This is a minitest front end to using {DSL#wait_for}, so any
+  # parameters you would normally pass to that method will work here.
+  # This also means that you must include either a `parent` key or an
+  # `ancestor` key as one of the filters.
+  #
+  # @param [#to_s]
+  # @param [Hash]
+  # @yield An optional block to be used in the search qualifier
+  def refute_shortly_has kind, filters = {}, &block
+    result = wait_for kind, filters, &block
+    msg = message {
+      if ancest = filters[:ancestor]
+        "Expected #{ancest.inspect} NOT to have #{result.inspect} as a descendent"
+      else
+        parent = filters[:parent]
+        "Expected #{parent.inspect} NOT to have #{result.inspect} as a child"
+      end
+    }
+    assert result.blank?, msg
+    result
+  end
+
 
   private
 
@@ -115,5 +173,3 @@ class MiniTest::Assertions
   end
 
 end
-
-# @todo assertions for minitest/spec

data/lib/mouse.rb

@@ -1,14 +1,14 @@
 framework 'ApplicationServices'
 
 ##
+# This is a first attempt at writing a wrapper around the CoreGraphics event
+# taps API provided by OS X. The module provides a simple Ruby interface to
+# performing mouse interactions such as moving and clicking.
+#
 # [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 Refactor to try and reuse the same event for a single action
-#       instead of creating new events.
-# @todo Pause between down/up clicks
+# A rewrite is in the works, but in the mean time this code base still works
+# despite its warts.
 module Mouse
   extend self
 
@@ -20,7 +20,7 @@ module Mouse
 
   ##
   # @note We keep the number as a rational to try and avoid rounding
-  #       error introduced by the way MacRuby deals with floats.
+  #       error introduced by the floats, especially MacRuby floats.
   #
   # Smallest unit of time allowed for an animation step.
   #
@@ -95,12 +95,36 @@ module Mouse
   ##
   # A standard click. Default position is the current position.
   #
+  # This `duration` parameter is used to add a minimum time between
+  # down and up click as clicking up too fast has shown to screw things up in
+  # some cases. However, the duration is arbitrary and if the system lags it
+  # could cause certain timing behaviours (consider the two behaviours of
+  # pop up buttons).
+  #
   # @param [CGPoint]
   def click point = current_position, duration = 12
+    click_down
+    sleep QUANTUM*duration
+    click_up
+  end
+
+  ##
+  # Perform a down click. You should follow this up with a call to
+  # {#click_up} to finish the click.
+  #
+  # @param [CGPoint]
+  def click_down point = current_position
     event = new_event KCGEventLeftMouseDown, point, KCGMouseButtonLeft
     post event
-    duration.times { sleep QUANTUM }
-    set event, to: KCGEventLeftMouseUp
+  end
+
+  ##
+  # Perform an up click. This should only be called after a call to
+  # {#click_down} to finish the click event.
+  #
+  # @param [CGPoint]
+  def click_up point = current_position
+    event = new_event KCGEventLeftMouseUp, point, KCGMouseButtonLeft
     post event
   end
 
@@ -111,8 +135,8 @@ module Mouse
   def secondary_click point = current_position, duration = 12
     event = new_event KCGEventRightMouseDown, point, KCGMouseButtonRight
     post event
-    duration.times { sleep QUANTUM }
-    set event, to: KCGEventRightMouseUp
+    sleep QUANTUM*duration
+    set_type event, KCGEventRightMouseUp
     post event
   end
   alias_method :right_click, :secondary_click
@@ -124,13 +148,13 @@ module Mouse
   def double_click point = current_position
     event = new_event KCGEventLeftMouseDown, point, KCGMouseButtonLeft
     post event
-    set  event, to: KCGEventLeftMouseUp
+    set_type  event, KCGEventLeftMouseUp
     post event
 
     CGEventSetIntegerValueField(event, KCGMouseEventClickState, 2)
-    set  event, to: KCGEventLeftMouseDown
+    set_type  event, KCGEventLeftMouseDown
     post event
-    set  event, to: KCGEventLeftMouseUp
+    set_type  event, KCGEventLeftMouseUp
     post event
   end
 
@@ -149,11 +173,11 @@ module Mouse
   # @param [CGPoint]
   # @param [Number]
   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)
+    event = new_event KCGEventOtherMouseDown, point, button
+    post event
+    sleep QUANTUM*duration
+    set_type event, KCGEventOtherMouseUp
+    post event
   end
   alias_method :other_click, :arbitrary_click
 
@@ -204,7 +228,10 @@ module Mouse
     CGEventPost(KCGHIDEventTap, event)
   end
 
-  def set event, to: state
+  ##
+  # Change the event type for an instance of an event. This is how you would
+  # reuse a specific event. In most cases, reusing events is a necessity.
+  def set_type event, state
     CGEventSetType(event, state)
   end
 

data/lib/rspec/expectations/ax_elements.rb

@@ -1,56 +1,161 @@
+require 'accessibility/dsl'
 require 'accessibility/qualifier'
 require 'ax/element'
 
-##
-# 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
+module Accessibility
 
-  # @param [AX::Element]
-  def matches? parent
-    !search(parent).blank?
-  end
+  ##
+  # @abstract
+  #
+  # Base class for RSpec matchers used with AXElements.
+  class AbstractMatcher
 
-  # @return [String]
-  def failure_message_for_should
-    "Expected #@parent to have child #{@qualifier.describe}"
-  end
+    # @return [#to_s]
+    attr_reader :kind
 
-  # @param [AX::Element]
-  def does_not_match? parent
-    search(parent).blank?
-  end
+    # @return [Hash{Symbol=>Object}]
+    attr_reader :filters
+
+    # @return [Proc]
+    attr_reader :block
+
+    # @param [#to_s]
+    # @param [Hash]
+    # @yield
+    def initialize kind, filters, &block
+      @kind, @filters, @block = kind, filters, block
+    end
 
-  # @return [String]
-  def failure_message_for_should_not
-    "Expected #@parent to NOT have child #@result"
+    # @param [AX::Element]
+    def does_not_match? element
+      !matches?(element)
+    end
+
+
+    private
+
+    # @return [Accessibility::Qualifier]
+    def qualifier
+      @qualifier ||= Accessibility::Qualifier.new(kind, filters, &block)
+    end
   end
 
   ##
-  # Implemented to override `NSObject#description`.
-  #
-  # @return [String]
-  def description
-    "should have a child that matches #{@qualifier.describe}"
+  # Custom matcher for RSpec to check if an element has the specified
+  # child element.
+  class HasChildMatcher < AbstractMatcher
+    # @param [AX::Element]
+    def matches? parent
+      @parent = parent
+      @result = parent.children.find { |x| qualifier.qualifies? x }
+      !@result.blank?
+    end
+
+    # @return [String]
+    def failure_message_for_should
+      "Expected #@parent to have child #{qualifier.describe}"
+    end
+
+    # @return [String]
+    def failure_message_for_should_not
+      "Expected #@parent to NOT have child #@result"
+    end
+
+    # @return [String]
+    def description
+    "should have a child that matches #{qualifier.describe}"
+    end
   end
 
+  ##
+  # Custom matcher for RSpec to check if an element has the specified
+  # descendent element.
+  class HasDescendentMatcher < AbstractMatcher
+    # @param [AX::Element]
+    def matches? ancestor
+      @ancestor = ancestor
+      @result   = ancestor.search(kind, filters, &block)
+      !@result.blank?
+    end
+
+    # @return [String]
+    def failure_message_for_should
+      "Expected #@ancestor to have descendent #{qualifier.describe}"
+    end
+
+    # @return [String]
+    def failure_message_for_should_not
+      "Expected #@ancestor to NOT have descendent #@result"
+    end
+
+    # @return [String]
+    def description
+      "should have a descendent matching #{qualifier.describe}"
+    end
+  end
 
-  private
-
-  def search parent
-    @parent = parent
-    @result = parent.children.find { |x| @qualifier.qualifies? x }
+  ##
+  # Custom matcher for RSpec to check if an element has the specified
+  # child element within a grace period. Used for testing things
+  # after an asynchronous action is performed.
+  class HasChildShortlyMatcher < AbstractMatcher
+    include DSL
+
+    # @param [AX::Element]
+    def matches? parent
+      @filters[:parent] = @parent = parent
+      @result = wait_for kind, filters, &block
+      !@result.blank?
+    end
+
+    # @return [String]
+    def failure_message_for_should
+      "Expected #@parent to have child #{qualifier.describe} before a timeout occurred"
+    end
+
+    # @return [String]
+    def failure_message_for_should_not
+      "Expected #@parent to NOT have child #@result before a timeout occurred"
+    end
+
+    # @return [String]
+    def description
+      "should have a child that matches #{qualifier.describe} before a timeout occurs"
+    end
   end
 
+  ##
+  # Custom matcher for RSpec to check if an element has the specified
+  # descendent element within a grace period. Used for testing things
+  # after an asynchronous action is performed.
+  class HasDescendentShortlyMatcher < AbstractMatcher
+    include DSL
+
+    # @param [AX::Element]
+    def matches? ancestor
+      @filters[:ancestor] = @ancestor = ancestor
+      @result = wait_for kind, filters, &block
+      !@result.blank?
+    end
+
+    # @return [String]
+    def failure_message_for_should
+      "Expected #@ancestor to have descendent #{qualifier.describe} before a timeout occurred"
+    end
+
+    # @return [String]
+    def failure_message_for_should_not
+      "Expected #@ancestor to NOT have descendent #@result before a timeout occurred"
+    end
+
+    # @return [String]
+    def description
+      "should have a descendent matching #{qualifier.describe} before a timeout occurs"
+    end
+  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
@@ -70,58 +175,6 @@ 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
-
-  ##
-  # Implemented to override `NSObject#description`.
-  #
-  # @return [String]
-  def description
-    "should have a descendent matching #{@qualifier.describe}"
-  end
-
-
-  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,
@@ -140,3 +193,42 @@ def have_descendent kind, filters = {}, &block
   Accessibility::HasDescendentMatcher.new kind, filters, &block
 end
 alias :have_descendant :have_descendent
+
+##
+# Assert that the given element has the specified child soon. This
+# method will block until the child is found or a timeout occurs. You
+# can pass any parameters you normally would use during a search,
+# including a block.
+#
+# @example
+#
+#   app.main_window.should shortly_have_child(:row, static_text: { value: 'Cake' })
+#
+#   row.should_not shortly_have_child(:check_box)
+#
+# @param [#to_s]
+# @param [Hash]
+# @yield An optional block to be used as part of the search qualifier
+def shortly_have_child kind, filters = {}, &block
+  Accessibility::HasChildShortlyMatcher.new(kind, filters, &block)
+end
+
+##
+# Assert that the given element has the specified descendent soon. This
+# method will block until the descendent is found or a timeout occurs.
+# You can pass any parameters you normally would use during a search,
+# including a block.
+#
+# @example
+#
+#   app.main_window.should shortly_have_child(:row, static_text: { value: 'Cake' })
+#
+#   row.should_not shortly_have_child(:check_box)
+#
+# @param [#to_s]
+# @param [Hash]
+# @yield An optional block to be used as part of the search qualifier
+def shortly_have_descendent kind, filters = {}, &block
+  Accessibility::HasDescendentShortlyMatcher.new kind, filters, &block
+end
+alias :shortly_have_descendant :shortly_have_descendent

data/rakelib/doc.rake

@@ -11,3 +11,10 @@
 # task :garden => :yard do
 #   sh 'yard graph --full --dependencies --dot="-Tpng:quartz" -f docs/images/AX.dot'
 # end
+
+desc 'Remove files generated by YARD'
+task :clobber_yard do
+  rm_rf '.yardoc/'
+end
+task :clobber => :clobber_yard
+

data/test/helper.rb

@@ -1,7 +1,8 @@
 framework 'Cocoa'
 
 # We want to launch the test app and make sure it responds to
-# accessibility queries, but that is difficult, so we just sleep
+# accessibility queries, but that is difficult to know at what
+# point it will start to respond, so we just sleep
 APP_BUNDLE_URL = NSURL.fileURLWithPath File.expand_path './test/fixture/Release/AXElementsTester.app'
 APP_BUNDLE_IDENTIFIER = 'com.marketcircle.AXElementsTester'