AXElements 0.9.0 → 1.0.0.alpha

data/lib/mouse.rb

@@ -0,0 +1,227 @@
+framework 'ApplicationServices'
+require   'ax_elements/core_graphics_workaround'
+
+
+##
+# 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).
+#
+# A rewrite is in the works, but in the mean time this code base still works
+# despite its warts.
+module Mouse
+  extend self
+
+  ##
+  # 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 floats, especially MacRuby 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 point [CGPoint]
+  # @param duration [Float] 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 point [CGPoint]
+  # @param duration [Float] animation duration, in seconds
+  def drag_to point, duration = 0.2
+    post new_event(KCGEventLeftMouseDown, current_position, KCGMouseButtonLeft)
+
+    animate KCGEventLeftMouseDragged, KCGMouseButtonLeft, current_position, point, duration
+
+    post new_event(KCGEventLeftMouseUp, current_position, KCGMouseButtonLeft)
+  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 amount [Fixnum] number of units to scroll; positive to scroll
+  #   up or negative to scroll down
+  # @param duration [Float] animation duration, in seconds
+  # @param units [Symbol] `: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).round
+    current = 0.0
+    steps.times do |step|
+      done     = (step+1).to_f / steps
+      scroll   = ((done - current)*amount).round
+      post new_scroll_event(units, 1, scroll)
+      sleep QUANTUM
+      current += scroll.to_f / amount
+    end
+  end
+
+  ##
+  # Perform a down click. You should follow this up with a call to
+  # {#click_up} to finish the click.
+  #
+  # @param point [CGPoint]
+  # @param duration [Number]
+  def click_down point = current_position, duration = 12
+    event = new_event KCGEventLeftMouseDown, point, KCGMouseButtonLeft
+    post event
+    sleep QUANTUM*duration
+  end
+
+  ##
+  # Perform an up click. This should only be called after a call to
+  # {#click_down} to finish the click event.
+  #
+  # @param point [CGPoint]
+  def click_up point = current_position
+    event = new_event KCGEventLeftMouseUp, point, KCGMouseButtonLeft
+    post event
+  end
+
+  ##
+  # Standard secondary click. Default position is the current position.
+  #
+  # @param point [CGPoint]
+  # @param duration [Number]
+  def secondary_click point = current_position, duration = 12
+    event = new_event KCGEventRightMouseDown, point, KCGMouseButtonRight
+    post event
+    sleep QUANTUM*duration
+    set_type event, KCGEventRightMouseUp
+    post event
+  end
+  alias_method :right_click, :secondary_click
+
+  ##
+  # A standard double click. Defaults to clicking at the current position.
+  #
+  # @param point [CGPoint]
+  def double_click point = current_position
+    event = new_event KCGEventLeftMouseDown, point, KCGMouseButtonLeft
+    post event
+    set_type  event, KCGEventLeftMouseUp
+    post event
+
+    CGEventSetIntegerValueField(event, KCGMouseEventClickState, 2)
+    set_type  event, KCGEventLeftMouseDown
+    post event
+    set_type  event, KCGEventLeftMouseUp
+    post 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 point [CGPoint]
+  # @param button [Number]
+  # @param duration [Number]
+  def arbitrary_click point = current_position, button = KCGMouseButtonCenter, duration = 12
+    event = new_event KCGEventOtherMouseDown, point, button
+    post event
+    sleep QUANTUM*duration
+    set_type event, KCGEventOtherMouseUp
+    post 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
+    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
+  end
+
+  def close_enough? current, target
+    x = current.x - target.x
+    y = current.y - target.y
+    ((x**2)+(y**2)) <= 1
+  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)
+  end
+
+  ##
+  # 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
+
+end

data/lib/rspec/expectations/ax_elements.rb

@@ -0,0 +1,234 @@
+require 'accessibility/dsl'
+require 'accessibility/qualifier'
+require 'ax/element'
+
+module Accessibility
+
+  ##
+  # @abstract
+  #
+  # Base class for RSpec matchers used with AXElements.
+  class AbstractMatcher
+
+    # @return [#to_s]
+    attr_reader :kind
+
+    # @return [Hash{Symbol=>Object}]
+    attr_reader :filters
+
+    # @return [Proc]
+    attr_reader :block
+
+    # @param kind [#to_s]
+    # @param filters [Hash]
+    # @yield Optional block used for search filtering
+    def initialize kind, filters, &block
+      @kind, @filters, @block = kind, filters, block
+    end
+
+    # @param element [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
+
+  ##
+  # Custom matcher for RSpec to check if an element has the specified
+  # child element.
+  class HasChildMatcher < AbstractMatcher
+    # @param parent [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 ancestor [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
+
+  ##
+  # 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 parent [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 ancestor [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
+# 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 kind [#to_s]
+# @param filters [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
+
+##
+# 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 kind [#to_s]
+# @param filters [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
+
+##
+# 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 kind [#to_s]
+# @param filters [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 kind [#to_s]
+# @param filters [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