framework_gem 0.1.0

data/lib/lib/keyboard/apple_tv/apple_tv_password_keyboard.rb

@@ -0,0 +1,102 @@
+require './lib/keyboard/keyboard'
+require './lib/keyboard/keyboard_layout'
+
+class AppleTvPasswordKeyboard < Keyboard
+
+  def initialize(*args)
+    super(*args)
+    # see Keyboard for explanation of layouts
+    keys_start = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        [:n0, :n1, :n2, :n3, :n4, :n5]
+    ]
+    keys_lower = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[a b c d e f],
+        %w[g h i j k l],
+        %w[m n o p q r],
+        %w[s t u v w x],
+        %w[y z 1 2 3 4],
+        %w[5 6 7 8 9 0],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+    keys_upper = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[A B C D E F],
+        %w[G H I J K L],
+        %w[M N O P Q R],
+        %w[S T U V W X],
+        %w[Y Z 1 2 3 4],
+        %w[5 6 7 8 9 0],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+    keys_symbols = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[! @ # $ % &],
+        %w[~ * \ / ? ^],
+        %w[_ ` ; : | =],
+        %w[é ñ [ ] { }],
+        %w[ç ü . , + -],
+        %w[< > ( ) ' "],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+
+    @layouts << KeyboardLayout.new(keys_start, [1, 0], name: 'keys_start')
+    @layouts << KeyboardLayout.new(keys_lower, [0, 1], nav_to_key: :LOWERCASE, name: 'keys_lower')
+    @layouts << KeyboardLayout.new(keys_upper, [0, 2], nav_to_key: :UPPERCASE, name: 'keys_upper')
+    @layouts << KeyboardLayout.new(keys_symbols, [0, 4], nav_to_key: :SYMBOLS, name: 'keys_symbols')
+
+    @verify_roi = dut.roi.text.search_box_text_entered rescue nil
+    # Do not traverse from any of the multi-column keys except to the key above-left of it, since they always left-justify.
+    @deny_traversals = [
+      [:LOWERCASE, "a"], [:LOWERCASE, "A"], [:LOWERCASE, "!"], [:LOWERCASE, :n0], [:LOWERCASE, :UPPERCASE],
+      ["a", :LOWERCASE], ["A", :LOWERCASE], ["!", :LOWERCASE], [:n0, :LOWERCASE],
+
+      [:UPPERCASE, "d"], [:UPPERCASE, "D"], [:UPPERCASE, "$"], [:UPPERCASE, :n3], [:UPPERCASE, :LOWERCASE], [:UPPERCASE, :SYMBOLS],
+      ["d", :UPPERCASE], ["D", :UPPERCASE], ["$", :UPPERCASE], [:n3, :UPPERCASE],
+
+      [:SYMBOLS, "f"],  [:SYMBOLS, "F"], [:SYMBOLS, "&"], [:SYMBOLS, :n5], [:SYMBOLS, :UPPERCASE],
+      ["f", :SYMBOLS],  ["F", :SYMBOLS], ["&", :SYMBOLS], [:n5, :SYMBOLS],
+
+        [:SPACE, '>'], [:SPACE, '6'], [:SPACE, :DELETE],
+        ['>', :SPACE], ['6', :SPACE],
+        [:DELETE, '9'], [:DELETE, ')'], [:DELETE, '.COM'], [:DELETE, :SPACE], [:DELETE, :CLEAR],
+        ['9', :DELETE], [')', :DELETE], ['.COM', :DELETE], 
+        [:CLEAR, "0"], [:CLEAR, "\""], [:CLEAR, :DELETE],
+        ["0", :CLEAR], ["\"", :CLEAR]
+    ]
+  end
+
+  private
+
+  def displayed_rois
+    [@dut.roi.text.password_page_displayed]
+  end
+
+  def get_layout_for_key(key)
+    res = nil
+    @layouts.each_with_index do |layout, i|
+      all_keys = layout.key_matrix(@shifted).flatten
+      if all_keys.include?(key)
+        # the key is in the layout, no case shift required
+        return [i, false, key]
+      elsif key.is_a?(String)
+        cased_val = key =~ /^[[:upper:]]+$/ ? key.downcase : key.upcase
+        if all_keys.include?(cased_val)
+          # the key is in the layout, but with a different case
+          if cur_layout.shift_key.nil?
+            # the other case is ok when there is no shift key
+            res = [i, false, cased_val]
+          else
+            # shift case when there is a shift key
+            res = [i, true, key]
+          end
+        end
+      end
+    end
+    # the key is not in any layout/case
+    raise "Key #{key.inspect} is not defined in any keyboard layout." if res.nil?
+    return res
+  end
+
+end

data/lib/lib/keyboard/apple_tv/apple_tv_search_keyboard.rb

@@ -0,0 +1,103 @@
+require './lib/keyboard/keyboard'
+require './lib/keyboard/keyboard_layout'
+
+class AppleTvSearchKeyboard < Keyboard
+
+  def initialize(*args)
+    super(*args)
+    # see Keyboard for explanation of layouts
+    keys_start = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        [:n0, :n1, :n2, :n3, :n4, :n5]
+    ]
+    keys_lower = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[a b c d e f],
+        %w[g h i j k l],
+        %w[m n o p q r],
+        %w[s t u v w x],
+        %w[y z 1 2 3 4],
+        %w[5 6 7 8 9 0],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+    keys_upper = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[A B C D E F],
+        %w[G H I J K L],
+        %w[M N O P Q R],
+        %w[S T U V W X],
+        %w[Y Z 1 2 3 4],
+        %w[5 6 7 8 9 0],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+    keys_symbols = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[! @ # $ % &],
+        %w[~ * \ / ? ^],
+        %w[_ ` ; : | =],
+        %w[é ñ [ ] { }],
+        %w[ç ü . , + -],
+        %w[< > ( ) ' "],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+
+    @layouts << KeyboardLayout.new(keys_start, [1, 0], name: 'keys_start')
+    @layouts << KeyboardLayout.new(keys_lower, [0, 1], nav_to_key: :LOWERCASE, name: 'keys_lower')
+    @layouts << KeyboardLayout.new(keys_upper, [0, 2], nav_to_key: :UPPERCASE, name: 'keys_upper')
+    @layouts << KeyboardLayout.new(keys_symbols, [0, 4], nav_to_key: :SYMBOLS, name: 'keys_symbols')
+
+    @verify_roi = dut.roi.text.search_box_text_entered rescue nil
+    # Do not traverse from any of the multi-column keys except to the key above-left of it, since they always left-justify.
+    @deny_traversals = [
+      [:LOWERCASE, "a"], [:LOWERCASE, "A"], [:LOWERCASE, "!"], [:LOWERCASE, :n0], [:LOWERCASE, :UPPERCASE],
+      ["a", :LOWERCASE], ["A", :LOWERCASE], ["!", :LOWERCASE], [:n0, :LOWERCASE],
+
+      [:UPPERCASE, "d"], [:UPPERCASE, "D"], [:UPPERCASE, "$"], [:UPPERCASE, :n3], [:UPPERCASE, :LOWERCASE], [:UPPERCASE, :SYMBOLS],
+      ["d", :UPPERCASE], ["D", :UPPERCASE], ["$", :UPPERCASE], [:n3, :UPPERCASE],
+
+      [:SYMBOLS, "f"],  [:SYMBOLS, "F"], [:SYMBOLS, "&"], [:SYMBOLS, :n5], [:SYMBOLS, :UPPERCASE],
+      ["f", :SYMBOLS],  ["F", :SYMBOLS], ["&", :SYMBOLS], [:n5, :SYMBOLS],
+
+        [:SPACE, '>'], [:SPACE, '6'], [:SPACE, :DELETE],
+        ['>', :SPACE], ['6', :SPACE],
+        [:DELETE, '9'], [:DELETE, ')'], [:DELETE, '.COM'], [:DELETE, :SPACE], [:DELETE, :CLEAR],
+        ['9', :DELETE], [')', :DELETE], ['.COM', :DELETE], 
+        [:CLEAR, "0"], [:CLEAR, "\""], [:CLEAR, :DELETE],
+        ["0", :CLEAR], ["\"", :CLEAR]
+    ]
+  end
+
+  private
+
+  def displayed_rois
+    [@dut.roi.text.search_page_displayed_text, @dut.roi.text.search_page_new]
+  end
+
+  def get_layout_for_key(key)
+    res = nil
+    @layouts.each_with_index do |layout, i|
+      all_keys = layout.key_matrix(@shifted).flatten
+      if all_keys.include?(key)
+        # the key is in the layout, no case shift required
+        return [i, false, key]
+      elsif key.is_a?(String)
+        cased_val = key =~ /^[[:upper:]]+$/ ? key.downcase : key.upcase
+        if all_keys.include?(cased_val)
+          # the key is in the layout, but with a different case
+          if cur_layout.shift_key.nil?
+            # the other case is ok when there is no shift key
+            res = [i, false, cased_val]
+          else
+            # shift case when there is a shift key
+            res = [i, true, key]
+          end
+        end
+      end
+    end
+    # the key is not in any layout/case
+    raise "Key #{key.inspect} is not defined in any keyboard layout." if res.nil?
+    return res
+  end
+
+
+end

data/lib/lib/keyboard/apple_tv/apple_tv_username_keyboard.rb

@@ -0,0 +1,105 @@
+require './lib/keyboard/keyboard'
+require './lib/keyboard/keyboard_layout'
+
+class AppleTvUsernameKeyboard < Keyboard
+
+  def initialize(*args)
+    super(*args)
+    # see Keyboard for explanation of layouts
+    keys_start = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        [:n0, :n1, :n2, :n3, :n4, :n5]
+    ]
+    keys_lower = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[a b c d e f],
+        %w[g h i j k l],
+        %w[m n o p q r],
+        %w[s t u v w x],
+        %w[y z 1 2 3 4],
+        %w[5 6 7 8 9 0],
+        ['.', '_', '@', '.com', '.net', '.edu'],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+    keys_upper = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[A B C D E F],
+        %w[G H I J K L],
+        %w[M N O P Q R],
+        %w[S T U V W X],
+        %w[Y Z 1 2 3 4],
+        %w[5 6 7 8 9 0],
+        ['.', '_', '@', '.COM', '.NET', '.EDU'],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+    keys_symbols = [
+        [:LOWERCASE, :LOWERCASE, :UPPERCASE, :UPPERCASE, :SYMBOLS, :SYMBOLS],
+        %w[! @ # $ % &],
+        %w[~ * \ / ? ^],
+        %w[_ ` ; : | =],
+        %w[é ñ [ ] { }],
+        %w[ç ü . , + -],
+        %w[< > ( ) ' "],
+        ['.', '_', '@', '.com', '.net', '.edu'],
+        [:SPACE, :SPACE, :DELETE, :DELETE, :CLEAR, :CLEAR]
+    ]
+
+    @layouts << KeyboardLayout.new(keys_start, [1, 0], name: 'keys_start')
+    @layouts << KeyboardLayout.new(keys_lower, [0, 1], nav_to_key: :LOWERCASE, name: 'keys_lower')
+    @layouts << KeyboardLayout.new(keys_upper, [0, 2], nav_to_key: :UPPERCASE, name: 'keys_upper')
+    @layouts << KeyboardLayout.new(keys_symbols, [0, 4], nav_to_key: :SYMBOLS, name: 'keys_symbols')
+
+    @verify_roi = dut.roi.text.search_box_text_entered rescue nil
+    # Do not traverse from any of the multi-column keys except to the key above-left of it, since they always left-justify.
+    @deny_traversals = [
+      [:LOWERCASE, "a"], [:LOWERCASE, "A"], [:LOWERCASE, "!"], [:LOWERCASE, :n0], [:LOWERCASE, :UPPERCASE],
+      ["a", :LOWERCASE], ["A", :LOWERCASE], ["!", :LOWERCASE], [:n0, :LOWERCASE],
+
+      [:UPPERCASE, "d"], [:UPPERCASE, "D"], [:UPPERCASE, "$"], [:UPPERCASE, :n3], [:UPPERCASE, :LOWERCASE], [:UPPERCASE, :SYMBOLS],
+      ["d", :UPPERCASE], ["D", :UPPERCASE], ["$", :UPPERCASE], [:n3, :UPPERCASE],
+
+      [:SYMBOLS, "f"],  [:SYMBOLS, "F"], [:SYMBOLS, "&"], [:SYMBOLS, :n5], [:SYMBOLS, :UPPERCASE],
+      ["f", :SYMBOLS],  ["F", :SYMBOLS], ["&", :SYMBOLS], [:n5, :SYMBOLS],
+
+        [:SPACE, '.'], [:SPACE, :DELETE],
+        ['.', :SPACE],
+        [:DELETE, '.com'], [:DELETE, '.COM'], [:DELETE, :SPACE], [:DELETE, :CLEAR],
+        ['.com', :DELETE], ['.COM', :DELETE], 
+        [:CLEAR, '.edu'], [:CLEAR, '.EDU'], [:CLEAR, :DELETE],
+        ['.edu', :CLEAR], ['.EDU', :CLEAR]
+    ]
+  end
+
+  private
+
+  def displayed_rois
+    [@dut.roi.text.username_page_displayed]
+  end
+
+  def get_layout_for_key(key)
+    res = nil
+    @layouts.each_with_index do |layout, i|
+      all_keys = layout.key_matrix(@shifted).flatten
+      if all_keys.include?(key)
+        # the key is in the layout, no case shift required
+        return [i, false, key]
+      elsif key.is_a?(String)
+        cased_val = key =~ /^[[:upper:]]+$/ ? key.downcase : key.upcase
+        if all_keys.include?(cased_val)
+          # the key is in the layout, but with a different case
+          if cur_layout.shift_key.nil?
+            # the other case is ok when there is no shift key
+            res = [i, false, cased_val]
+          else
+            # shift case when there is a shift key
+            res = [i, true, key]
+          end
+        end
+      end
+    end
+    # the key is not in any layout/case
+    raise "Key #{key.inspect} is not defined in any keyboard layout." if res.nil?
+    return res
+  end
+
+end

data/lib/lib/keyboard/keyboard.rb

@@ -0,0 +1,504 @@
+require './lib/keyboard/keyboard_layout'
+
+# The Keyboard class defines methods for navigating/typing keys on layouts that are provided by inheriting classes.
+# Keyboard layouts are defined as a matrix of keys. The key types are:
+# special keys - defined as Symbols, i.e. :SHIFT_LOCK, :SHIFT, :BACKSPACE
+# normal keys  - defined as Strings, i.e. 'a', '1', '@'
+# Splat arrays can be used to simplify rows containing mixed key types. Just don't make it confusing to read the layout!
+class Keyboard
+
+  DEBUG = false  #TODO: Use for debugging only! If pushed to master as false, key navigation will take forever.
+
+  def initialize(dut)
+    @dut = dut
+    @test_case = dut.send(:test_case)
+    @layouts = []
+    @start_layout_index = 0
+    @verify_roi = nil
+    @key_delay = 3.sec
+    @shifted = false
+    @shift_persists = false
+    @wrap_rows = false
+    @wrap_cols = false
+    @deny_traversals = []
+    reset
+  end
+
+  # Public: This function is used to write the given text on the virtual keyboard.
+  #
+  # text       - String or Array of String keys to type.
+  # start_key  - String non-default start key (default: nil).
+  # verify_roi - Roi object to verify the typed text (default: nil).
+  # delay_between_keys  - Delay used between key presses in miliseconds min value of 3000 (default: 3000).
+  # nav_only   - Boolean whether to navigate without selecting (default: false).
+  #              Used to navigate to a single key without selecting it.
+  #
+  # Returns Boolean true if successfully able to write the given text. Else, returns false.
+  def type?(text, args={})
+    @key_delay = args[:delay_between_keys].to_i if args[:delay_between_keys].to_i > 3000
+    nav_only = args.fetch(:nav_only, false)
+    logger.info("#{nav_only ? 'Navigating to' : 'Typing'} #{text.inspect} on the #{cur_layout.name} keyboard.")
+    start_key = args[:start_key]
+    # only verify if verify==true (from `type_keys?')
+    verify_roi = args[:verify] ? args[:verify_roi] || @verify_roi : nil
+    unless start_key.nil?
+      @cur_coords = get_key_coords(start_key).first
+    end
+    unless text.is_a?(Array)
+      text = [text]
+    end
+    first_char = true
+    text.each do |val|
+      if val.is_a?(String) && val.length > 1
+        # type the string
+        val.split('').each do |key|
+          return false unless type?(key, nav_only: nav_only)
+        end
+      else
+        val = :SPACE if val == ' '
+        layout_index, shift, key = get_layout_for_key(val)
+        # this is a defined key
+        if layout_index != cur_layout_index
+          # change to the specified layout
+          return false unless type_key?(@layouts[layout_index].nav_to_key)
+          last_row_count = cur_key_matrix.count
+          last_row_width = cur_key_matrix[cur_coords[0]].count
+          @cur_layout_index = layout_index
+          last_nav_to_key = cur_layout.nav_to_key
+          # check if we need to reset the coords due to difference in dimensions between last and new keyboard
+          if cur_key_matrix.count != last_row_count || cur_key_matrix[cur_coords[0]].count != last_row_width
+            @cur_coords = get_key_coords(last_nav_to_key).first
+          end
+          # check if we need to downshift to restore the default case of the new layout
+          shift ||= (@shift_persists && @shifted)
+        end
+        # todo: implement shift lock for efficiency
+        # if this layout auto-cases, this is the first character, and the key is uppercase, then shift is not req'd
+        no_shift_reqd = cur_layout.auto_case && first_char && (key == key.upcase)
+        if shift && !no_shift_reqd
+          # press the shift key
+          return false unless type_key?(cur_layout.shift_key)
+        end
+        if nav_only
+          return false unless nav_to_key?(key)
+        else
+          return false unless type_key?(key)
+        end
+        first_char = false if first_char
+        first_char = true if cur_layout.auto_case && key == :SPACE
+      end
+    end
+    # all text typed successfully
+    if verify_roi.nil?
+      true
+    else
+      typed = verify_roi.retrieve.sub(/_$/, '')
+      if typed == text
+        true
+      else
+        logger.info(%Q(Tried to type "#{text}" but typed "#{typed}" instead!))
+        false
+      end
+    end
+  end
+
+  # Public: Checks if the current keyboard is displayed.
+  #
+  # Returns a Boolean true if the
+  def displayed?
+    return false if displayed_rois.empty?
+    displayed_rois.each {|roi| return true if roi.displayed?}
+    false
+  end
+
+  # Public: Resets all keyboard attributes.
+  #
+  # Returns nothing.
+  def reset
+    @shifted = false
+    @cur_coords = nil        # set automatically on first access
+    @cur_layout_index = nil  # set automatically on first access
+  end
+
+  private
+
+  # Internal: Get ROIs to check whether this keyboard is displayed.
+  def displayed_rois
+    []
+  end
+
+  # Internal: Get a handle to the logger.
+  def logger
+    @test_case.send(:logger_for_device, @dut.id)
+  end
+
+  # Internal: Get the key matrix for the layout given by name.
+  def key_matrix(index)
+    @layouts[index].key_matrix(@shifted)
+  end
+
+  # Internal: Get the key matrix for the current layout.
+  def cur_key_matrix
+    key_matrix(cur_layout_index)
+  end
+
+  # Internal: Get the current layout object.
+  def cur_layout
+    @layouts[cur_layout_index]
+  end
+
+  # Internal: Get the number of rows in the current key matrix.
+  def num_rows
+    cur_key_matrix.size
+  end
+
+  # Internal: Get the number of columns in the current key matrix.
+  def num_cols
+    cur_key_matrix.map {|row| row.size}.max
+  end
+
+  # Internal: Locate the layout for the specified key.
+  #
+  # Returns an Array of [INDEX, SHIFT, KEY] where INDEX is the index of the layout, SHIFT is a Boolean indicating
+  # whether shifting is required, and KEY is the verified key to type. Returns [nil, nil, nil] if the key is not found
+  # in any case in any layout.
+  def get_layout_for_key(key)
+    @layouts.each_with_index do |layout, i|
+      all_keys = layout.key_matrix(@shifted).flatten
+      if all_keys.include?(key)
+        # the key is in the layout, no case shift required
+        return [i, false, key]
+      elsif key.is_a?(String)
+        cased_val = key =~ /^[[:upper:]]+$/ ? key.downcase : key.upcase
+        if all_keys.include?(cased_val)
+          # the key is in the layout, but with a different case
+          if cur_layout.shift_key.nil?
+            # the other case is ok when there is no shift key
+            return [i, false, cased_val]
+          else
+            # shift case when there is a shift key
+            return [i, true, key]
+          end
+        end
+      end
+    end
+    # the key is not in any layout/case
+    raise "Key #{key.inspect} is not defined in any keyboard layout."
+  end
+
+  # Internal: Get the current key.
+  def cur_key
+    cur_key_matrix[cur_coords[0]][cur_coords[1]]
+  end
+
+  # Internal: Get the current coordinates.
+  def cur_coords
+    if @cur_coords.nil?
+      @cur_coords = cur_layout.start_coords.dup
+    end
+    @cur_coords
+  end
+
+  # Internal: Get the current layout index.
+  def cur_layout_index
+    if @cur_layout_index.nil?
+      @cur_layout_index = @start_layout_index
+    end
+    @cur_layout_index
+  end
+
+  # Internal: This function is used to get coordinates for a given key.
+  #
+  # key - String key on the virtual keyboard.
+  #
+  # Returns an Array of Integer Arrays, [[row, col], ...], of the possible coordinates for the given key if it is on
+  #   the keyboard. Else, returns nil.
+  def get_key_coords(key)
+    key_coords = []
+    num_rows.times do |row|
+      num_cols.times do |col|
+        if key == cur_key_matrix[row][col]
+          key_coords << [row, col]
+        end
+      end
+    end
+    key_coords
+  end
+
+  # Internal: Navigate to and type the specified key.
+  def type_key?(key)
+    # TODO create ROI to verify highlighted text? (belongs in KeyboardLayout instance).
+    if nav_to_key?(key)
+      @dut.press_key.SELECT(sleep_time: @key_delay)
+      if key == cur_layout.shift_key
+        @shifted = !@shifted
+      end
+      return true
+    end
+    logger.info("Failed to type key '#{key}'.")
+    false
+  end
+
+  # Internal: Gets the value closest to zero from the given array.
+  def get_closest_to_zero(*arr)
+    ret = nil
+    arr.flatten.each {|v| ret = v if ret.nil? || v.abs < ret.abs}
+    #puts "closest to zero of #{arr.flatten.inspect} >>> #{ret}" if DEBUG
+    ret
+  end
+
+  # Internal: Gets neighboring key for the specified coordinates and direction.
+  def get_neighboring_key(coords, direction)
+    row, col = coords
+    if direction == :down
+      next_coords = @wrap_rows && row + 1 == num_rows ? [0, col] : [row + 1, col]
+    elsif direction == :up
+      next_coords = @wrap_rows || row != 0 ? [row - 1, col] : nil
+    elsif direction == :right
+      next_coords = @wrap_cols && col + 1 == num_cols ? [row, 0] : [row, col + 1]
+    else
+      next_coords = @wrap_cols || col != 0 ? [row, col - 1] : nil
+    end
+    row = next_coords.nil? ? nil : cur_key_matrix[next_coords[0]]
+    key = row.nil? ? nil : row[next_coords[1]]
+    if key == :BLANK
+      return get_neighboring_key(next_coords, direction)
+    end
+    [key, next_coords]
+  end
+
+  # Internal: Gets neighboring keys for the specified coordinates.
+  def get_neighboring_keys(coords)
+    keys = {}
+    [:down, :up, :left, :right].each do |dir|
+      keys[dir] = get_neighboring_key(coords, dir)
+    end
+    keys
+  end
+
+  # Internal: Gets all paths to the specified key from the given coordinates.
+  def get_paths_to_key(key, start_coords, coords: nil, path: [], paths: [], shortest: false)
+    coords ||= start_coords
+    this_key = cur_key_matrix[coords[0]][coords[1]]
+    opts = get_neighboring_keys(coords)
+    opts.each do |dir, opt|
+      next_key, next_coord = opt
+      if next_key.nil? || @deny_traversals.include?([this_key, next_key])
+        # key does not exist or is not allowed; no-op
+        puts "key does not exist or traversal from (#{this_key} #{coords.inspect}) is not allowed >>> #{next_key} #{next_coord.inspect}" if DEBUG
+      else
+        new_path = path + [{key: next_key, coords: next_coord, dir: dir}]
+        #puts 'new path=' + new_path.map {|n| n[:key]}.inspect
+        path_len = new_path.uniq {|nav| nav[:key]}.count
+        if next_key == key
+          paths << new_path
+          if @shortest.nil? || path_len < @shortest
+            @shortest = path_len
+          end
+        elsif shortest && !@shortest.nil? && path_len > @shortest
+          # path is longer than shortest; no-op
+          puts "path is longer than shortest (#{@shortest}) >>> #{new_path.inspect}" if DEBUG
+        elsif path.any? {|nav| nav[:key] == next_key} && path[-1][:key] != next_key #next_key == cur_key_matrix[start_coords[0]][start_coords[1]]
+          # key is repeated; no-op
+          puts "path repeats key (#{next_key}) >>> #{new_path.inspect}" if DEBUG
+        else
+          if [:up, :down].include?(dir)
+            reverse_dir = dir == :up ? :down : :up
+          else
+            reverse_dir = dir == :left ? :right : :left
+          end
+          navs = new_path.map {|nav| nav[:dir]}.select {|d| [dir, reverse_dir].include?(d)}
+          if navs.count > 2 && navs[-2] == reverse_dir && navs[0..-3].include?(dir)
+            # changed direction more than once; no-op
+            puts "path changed direction more than once >>> #{new_path.inspect}" if DEBUG
+          else
+            get_paths_to_key(key, start_coords, coords: next_coord, path: new_path, paths: paths, shortest: shortest)
+          end
+        end
+      end
+    end
+    paths
+  end
+
+  # Internal: This function is used to navigate to a given key.
+  #
+  # key - String key on the virtual keyboard.
+  #
+  # Returns Boolean true if successfully able to navigate to the given key. Else, returns false.
+  def nav_to_key?(key)
+    coords = get_key_coords(key)
+    if coords.empty?
+      logger.info("Key '#{key}' is not located on the #{cur_layout.name} keyboard.") # TODO indicate keyboard subclass being used.
+      return false
+    end
+    if cur_key == key  # Already on correct key.
+      return true
+    end
+    # Get all valid paths to key from current coordinates.
+    @shortest = nil
+    paths = get_paths_to_key(key, cur_coords, shortest: true)
+    puts "paths count >>> #{paths.count}" if DEBUG
+=begin
+
+    # Map reasonable routes to key. This may generate up to eight possible paths:
+    #   down/right, down/left, up/right, up/left, right/down, right/up, left/down, left/up
+    # Yields max of 4 paths if keys do not wrap; 6 paths if either rows/cols wrap; or 8 paths if both rows/cols wrap.
+    dirs = [:down, :up, :right, :left]
+    paths = []
+    dirs.each do |dir_a|
+      secondary_dirs = [:down, :up].include?(dir_a) ? [:right, :left] : [:down, :up]
+      secondary_dirs.each do |dir_b|
+        puts "traversing #{dir_a} then #{dir_b} to coords >>> #{coords}" if DEBUG
+        navs = []
+        path_coords = cur_coords.dup
+        disallow_navs = []
+        until coords.include?(path_coords)
+          puts "current coords >>> #{path_coords.inspect}" if DEBUG
+          # Map neighboring keys.
+          map = get_neighboring_keys(path_coords)
+          puts "neighboring keys >>> #{map.inspect}" if DEBUG
+          # Determine navigation direction.
+          same_row = coords.any? {|c| c[0] - path_coords[0] == 0}
+          same_col = coords.any? {|c| c[1] - path_coords[1] == 0}
+          if ([:down, :up].include?(dir_a) && !same_row) || ([:right, :left].include?(dir_a) && !same_col)
+            nav = dir_a  # travel in the primary direction
+          else
+            nav = dir_b  # otherwise, travel in the secondary direction
+          end
+          if disallow_navs.include?(nav)
+            allow_navs = dirs.reject {|d| disallow_navs.include?(d)}
+            if allow_navs.empty?
+              puts 'path failed' if DEBUG
+              navs = nil
+              break
+            end
+            # try to navigate around something by changing to the other direction
+            if allow_navs.include?(dir_a)
+              nav = dir_a
+            elsif allow_navs.include?(dir_b)
+              nav = dir_b
+            else
+              nav = allow_navs.first
+            end
+          end
+          # Validate navigation constraints.
+          redirect = false
+          if map[nav].nil?
+            # we have dead-ended into a non-wrapping edge of the keyboard
+            puts 'redirecting due to non-wrapping edge of keyboard' if DEBUG
+            redirect = true
+          elsif map[nav] == :BLANK
+            # we need to navigate around a gap
+            puts 'redirecting for to navigate around gap' if DEBUG
+            redirect = true
+          else
+            last_nav = navs[-1]
+            last_key = last_nav.nil? ? curr_key : last_nav[0]
+            if map[nav] != last_key && navs.any? {|n| n[0] == map[nav]}
+              # this nav traverses to a key we were already on
+              puts 'redirecting for repeated key' if DEBUG
+              redirect = true
+            else
+              prior_key = navs[-2].nil? ? nil : navs[-2][0]
+              unless last_nav.nil?
+                if @avoid_traversals.include?([last_key, map[nav]])
+                  # this traversal is not allowed; change direction
+                  puts 'redirecting for disallowed traversal' if DEBUG
+                  redirect = true
+                elsif nav != last_nav[1] && last_key == prior_key
+                  # this nav changes direction and last two navs were same key; strip last and change direction
+                  puts 'redirecting for multi-row/col key' if DEBUG
+                  navs.pop
+                  path_coords = navs[-1].nil? ? cur_coords : navs[-1][2]
+                  redirect = true
+                end
+              end
+            end
+          end
+          # Redirect if necessary.
+          if redirect
+            disallow_navs << nav
+            next
+          end
+          disallow_navs.clear
+          # Update path coordinates.
+          case nav
+            when :down
+              path_coords[0] += 1
+            when :up
+              path_coords[0] -= 1
+            when :right
+              path_coords[1] += 1
+            when :left
+              path_coords[1] -= 1
+            else
+              raise 'Invalid directional key!'
+          end
+          if @wrap_rows
+            # Correct coords if we wrapped rows
+            if path_coords[0] == num_rows
+              path_coords[0] = 0
+            elsif path_coords[0] == -1
+              path_coords[0] = num_rows - 1
+            end
+          end
+          if @wrap_cols
+            # Correct coords if we wrapped cols
+            if path_coords[1] == num_cols
+              path_coords[1] = 0
+            elsif path_coords[1] == -1
+              path_coords[1] = num_cols - 1
+            end
+          end
+          navs << [map[nav], nav, path_coords.dup]
+        end
+        paths << navs unless navs.nil?
+      end
+    end
+=end
+    # Scrub multi-row/col keys from paths
+    paths.each do |path|
+      path.reject!.each_with_index do |nav, i|
+        if i == 0
+          nav[:key] == cur_key            # reject first key if same as current
+        else
+          nav[:key] == path[i - 1][:key]  # reject key + n if same as last
+        end
+      end
+    end
+    # Choose the shortest path and navigate.
+    #puts "final paths >>>\n#{paths.map {|p| "\t#{p.inspect}"}.join("\n")}" if DEBUG
+    puts "final paths count >>> #{paths.count}" if DEBUG
+    path = paths.sort_by {|p| p.count}.first
+    puts "shortest path >>> #{path}" if DEBUG
+    path.each do |nav|
+      @dut.press_key("#{nav[:dir]}_arrow", sleep_time: @key_delay)
+      @cur_coords = nav[:coords]
+    end
+    # Verify cursor is on key.
+    # TODO add verification check. Should be in subclass since dependant on keyboard layout
+    # if verify_focus_on_key(key)
+    true
+  end
+
+  # TODO write method to verify you are on correct key (belongs in subclass).
+  # def verify_focus_on_key(key)
+  # # Create a 'base ROI for each keyboard subclass'
+  # # Use the vertical & horizontal spacing between keys
+  # # to calculate and update the ROI and check if color displayed
+  # end
+
+  # TODO write method to clear & reset keyboard (belongs in subclass).
+  # def reset_keyboard()
+  #   if keyboard type has clear
+  #     write_text('CLEAR')
+  #   elsif # keyboard clears when you go back a screen...
+  #     dut.press_key('exit', :sleep_time => 1.sec)
+  #     dut.screen._blah_.nav_to?
+  #     reset_attributes() if # if keyboard navigation resets back to starting point
+  #   else
+  #     nav_to_key(:BACKSPACE)
+  #     text_roi.retrieve.to_s.length.times{dut.press_key('select', :sleep_time => 1.sec)}
+  #   end
+
+end