framework_gem 0.1.0

data/lib/lib/roi/template_roi.txt

@@ -0,0 +1,9 @@
+require './lib/rois/{PARENT_PATH}/{PARENT_LC}_{TYPE_LC}_rois'
+
+# Defines {PLATFORM}-specific {TYPE} ROIs.
+
+class {PLATFORM}{TYPE}Rois < {PARENT}{TYPE}Rois
+
+  # None yet
+
+end

data/lib/lib/roi/text/text_roi.rb

@@ -0,0 +1,187 @@
+require './lib/roi/roi'
+
+# The TextRoi class defines a text Roi and its methods
+
+class TextRoi < Roi
+
+  attr_reader(:text)
+  attr_accessor(:similarity, :only_digits, :substring, :ignore_case, :ignore_spaces, :ignore_special_chars)
+
+  # Public: Initializes a text Roi.
+  #
+  # dut                   - Platform (or subclass) instance to which this Roi belongs.
+  # x                     - Integer x coordinate (default: nil).
+  # y                     - Integer y coordinate (default: nil).
+  # width                 - Integer width (default: nil).
+  # height                - Integer height (default: nil).
+  # rectangle             - Hash defining rectangle with keys :x, :y, :width, :height (default: nil).
+  # element               - Hash same as rectangle (default: nil).
+  # text                  - String expected text (default: '').
+  # similarity            - Integer text similarity threshold 0 - 100 (default: 70).
+  # ref_img               - String path to reference image (default: nil).
+  # only_digits           - Boolean indicating whether to convert all read characters to digits (default: false).
+  # substring             - Boolean indicating whether to treat the expected text as a substring (default: false).
+  # ignore_spaces         - Boolean indicating whether spaces should be ignored when verifying text (default: false).
+  # ignore_case           - Boolean indicating whether case should be ignored when verifying text (default: false).
+  # ignore_special_chars  - Boolean indicating whether special characters should be ignored when verifying text (default: false).
+  #
+  # Returns nothing.
+  def initialize(dut, args={})
+    super(dut, args)
+    self.text = args.fetch(:text, '')
+    @preprocessing = [0]
+    @only_digits = args.fetch(:only_digits, false)
+    @substring = args.fetch(:substring, false)
+    @ignore_spaces = args.fetch(:ignore_spaces, true)
+    @ignore_case = args.fetch(:ignore_case, false)
+    @ignore_special_chars = args.fetch(:ignore_special_chars, false)
+    @similarity = args.fetch(:similarity, 70)
+  end
+
+  # Public: Sets expected text.
+  #
+  # val - String expected text.
+  #
+  # Returns nothing.
+  def text=(val)
+    @text = val.is_a?(Array) ? val : [val]
+  end
+
+  # Public: Gets expected text.
+  #
+  # Returns a String expected text.
+  def text
+    @text
+  end
+
+  # Public: Gets text Roi info.
+  #
+  # Returns a tidy String with text Roi info.
+  def info
+    "#{super} Text=#{@text} Digits=#{@only_digits} Similarity=#{@similarity}"
+  end
+
+  # Public: Checks if text is displayed as defined in the given ROI.
+  #         Corresponds to api_is_text_displayed?
+  #
+  # key                   - String name of key to press to trigger evaluation (default: nil).
+  #                         If default, no keys will be pressed.
+  # delay                 - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout               - Integer total milliseconds to allow before timing out (default: 0).
+  # verifies_for          - Integer total milliseconds for which the ROI must verify in order to succeed (default: 0).
+  #                         If default, the ROI must only verify once.
+  # only_digits           - Boolean indicating whether to convert all read characters to digits (default: false).
+  # substring             - Boolean indicating whether to treat the expected text as a substring (default: false).
+  # ignore_spaces         - Boolean indicating whether spaces should be ignored when verifying text (default: false).
+  # ignore_case           - Boolean indicating whether case should be ignored when verifying text (default: false).
+  # ignore_special_chars  - Boolean indicating whether special characters should be ignored when verifying text (default: false).
+  # priority              - Symbol representing evaluation priority used to throttle CPU usage (default: :normal):
+  #                         :critical   - Sleep 10 milliseconds between intensive tasks (should be used sparingly).
+  #                         :high       - Sleep 100 milliseconds between intensive tasks.
+  #                         :normal     - Sleep 1 second between intensive tasks (default).
+  #                         :low        - Sleep 10 seconds between intensive tasks.
+  #                         :background - Sleep 1 minute between intensive tasks (should be used sparingly).
+  # log_every             - Integer interval in milliseconds between logs (default: 1000).
+  #
+  # Returns a Boolean true if text is displayed before the timeout, otherwise false.
+  def displayed?(args={})
+    logger.info('Checking if text is displayed')
+    raise 'Text is required!' if @text.nil?
+    frame = args[:frame]
+    verify(args) do
+      # Evaluate each OCR Roi object (one for each preprocessing option)
+      text_found = false
+      roi_options = get_roi_options(args.fetch(:set_roi_options, args))
+      get_roi_objects(frame: frame).each do |roi|
+        got_text = get_value(roi, frame.nil?)
+        text_found = false
+        @text.each do |txt|
+          if args.fetch(:substring, @substring)
+            sim = test_case.get_substring_similarity(txt, got_text, roi_options)
+          else
+            sim = test_case.get_string_similarity(txt, got_text, roi_options)
+          end
+          text_found = sim >= (@similarity / 100.0)
+          logger.info("Comparing #{got_text.inspect} with #{txt.inspect}, similarity: #{(sim * 100.0).round}%")
+          break if text_found
+        end
+        break if text_found
+      end
+      logger.roi(self, args.merge(message: "Text is#{text_found ? '' : ' not'} displayed", screenshot: frame.nil?,
+                                  use_last_image: frame.nil?))
+      text_found
+    end
+  end
+  special_method(:displayed?)
+
+  # Public: Gets the text in the region defined in the Roi.
+  #         Corresponds to: api_read_text_from_screen
+  #
+  # Returns the String text found.
+  def retrieve(args={})
+    logger.info('Retrieving text')
+    frame = args[:frame]
+    value(args) do
+      # Read the text for each preprocessing value
+      found_text = get_roi_objects(frame: frame).map do |roi|
+        get_value(roi, frame.nil?)
+      end
+      # Return the text with the most matches
+      matches = found_text.map { |txt| txt.empty? ? 0 : found_text.count(txt) }
+      index_of_max_matches = matches.index(matches.max)
+      best_match = found_text[index_of_max_matches]
+      confidence = ((found_text.count(best_match).to_f / found_text.size) * 100).round
+      logger.roi(self, args.merge(message: "Retrieved text #{best_match.inspect} with confidence #{confidence}%",
+                                  screenshot: frame.nil?, use_last_image: frame.nil?))
+      best_match
+    end
+  end
+  special_method(:retrieve)
+
+  private
+
+  # Internal: Returns the ROI as a hash.
+  def to_json(ref_img: nil)
+    super(ref_img: ref_img).merge(threshold: @similarity, text: @text.first)
+  end
+
+  # Internal: Returns an array of TMC Java OcrRoi objects
+  def get_roi_objects(frame: nil)
+    @preprocessing.map {|preprocess_opt| to_json(ref_img: frame).update(preprocessing: preprocess_opt)}
+  end
+
+  # Internal: Returns OCR options from the given arguments
+  def get_roi_options(args)
+    convert_similar = args.fetch(:convert_similar_chars, false)
+    {
+        :removeSpaces => args.fetch(:ignore_spaces, @ignore_spaces),
+        :toUppercase => args.fetch(:ignore_case, @ignore_case),
+        :removeSpecials => args.fetch(:ignore_special_chars, @ignore_special_chars),
+        :replaceB3 => convert_similar,
+        :replaceB8 => convert_similar,
+        :replaceG6 => convert_similar,
+        :replaceO0 => convert_similar,
+        :replaceTL => convert_similar,
+        :replaceS5 => convert_similar
+    }
+  end
+
+  # Internal: Returns the value of the Roi in the current screen or frame.
+  # This is just a helper for `retrieve' and `displayed'
+  def get_value(roi, from_screen)
+    logger.info("Getting text from #{from_screen ? 'screen' : 'frame'}")
+    json = get_json_for_get(roi: roi)
+    if from_screen
+      found_text = test_case.send(:tmc_post, "/api/roi/text/actions/#{dut.id}", json: json)['value']
+    else
+      found_text = test_case.send(:tmc_post, '/api/roi/text/actions', json: json)['value']
+    end
+    if @only_digits
+      found_text.gsub!(/[^0-9]/, '')
+    end
+    logger.roi(self, message: "Found text #{found_text.inspect}", screenshot: from_screen, use_last_image: from_screen,
+               screen_image: from_screen ? nil : roi[:referenceImage])
+    found_text
+  end
+
+end

data/lib/lib/roi/video/video_roi.rb

@@ -0,0 +1,98 @@
+require './lib/roi/roi'
+
+# The VideoRoi class defines a video Roi and its methods
+
+class VideoRoi < Roi
+  include CanHaveSpecialMethods
+
+  attr_reader(:threshold)
+
+  # Public: Initializes a video Roi.
+  #
+  # dut       - Platform (or subclass) instance to which this Roi belongs.
+  # x         - Integer x coordinate (default: nil).
+  # y         - Integer y coordinate (default: nil).
+  # width     - Integer width (default: nil).
+  # height    - Integer height (default: nil).
+  # rectangle - Hash defining rectangle with keys :x, :y, :width, :height (default: nil).
+  # element   - Hash same as rectangle (default: nil).
+  # threshold - Float video motion threshold 0.0 - 100.0 (default: 0.1).
+  # ref_img   - String path to reference image (default: nil).
+  #
+  # Returns nothing.
+  def initialize(dut, args={})
+    super(dut, args)
+    self.threshold=(args.fetch(:threshold, 0.1)) # default threshold is 0.1% (0.001)
+  end
+
+  # Public: Sets motion threshold.
+  #
+  # val - Integer motion threshold (0 - 100).
+  #
+  # Returns nothing.
+  def threshold=(val)
+    @threshold = val
+    @similarity = val
+  end
+
+  # Public: Gets video Roi info.
+  #
+  # Returns a tidy String with video Roi info.
+  def info
+    "#{super}; Threshold=#{@threshold}"
+  end
+
+  # Public: Checks if motion is detected on the screen as defined in the Roi.
+  #         Corresponds to: api_is_video_playing?
+  #
+  # key          - String name of key to press to trigger evaluation (default: nil).
+  #                If default, no keys will be pressed.
+  # delay        - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout      - Integer total milliseconds to allow before timing out (default: 0).
+  # verifies_for - Integer total milliseconds for which the ROI must verify in order to succeed (default: 0).
+  #                If default, the ROI must only verify once.
+  # priority     - Symbol representing evaluation priority used to throttle CPU usage (default: :normal):
+  #                :critical   - Sleep 10 milliseconds between intensive tasks (should be used sparingly).
+  #                :high       - Sleep 100 milliseconds between intensive tasks.
+  #                :normal     - Sleep 1 second between intensive tasks (default).
+  #                :low        - Sleep 10 seconds between intensive tasks.
+  #                :background - Sleep 1 minute between intensive tasks (should be used sparingly).
+  # log_every    - Integer interval in milliseconds between logs (default: 1000).
+  #
+  # Returns a Boolean true if motion is detected before the timeout, otherwise false.
+  def displayed?(args={})
+    logger.info('Checking if video is playing')
+    frame = args[:frame]
+    last_frame = args[:last_frame]
+    if !frame.nil? && last_frame.nil?
+      return false
+    end
+    verify(args) do
+      if frame.nil?
+        default_timeout = 5.sec
+        video_timeout = args.fetch(:timeout, default_timeout)
+        video_timeout = default_timeout if video_timeout == 0  # video timeout can't be 0
+        post_timeout = video_timeout + 1.min
+        json = get_json_for_match(roi: to_json.merge(timeout: video_timeout))
+        result = test_case.send(:tmc_post, "/api/roi/video/actions/#{dut.id}", json: json, timeout: post_timeout)['value']
+        logger.roi(self, args.merge(message: "Video is#{result ? '' : ' not'} playing on screen", use_last_image: true))
+      else
+        last_frame = rectangle.merge(:referenceImage => last_frame)
+        this_frame = rectangle.merge(:referenceImage => frame)
+        json = get_json_for_match_2(last_frame, this_frame)
+        result = test_case.send(:tmc_post, '/api/roi/video/actions', json: json)['value']
+        logger.roi(self, args.merge(message: "Video is#{result ? '' : ' not'} playing in frame", screenshot: false))
+      end
+      result
+    end
+  end
+  special_method(:displayed?)
+
+  private
+
+  # Internal: Returns the ROI as a hash.
+  def to_json(ref_img: nil)
+    super(ref_img: ref_img).merge(threshold: @threshold)
+  end
+
+end

data/lib/lib/screen/screen.rb

@@ -0,0 +1,183 @@
+require 'delegate'
+require './lib/helpers/tmc_helpers/tmc_helpers'
+
+# The Screen class is a delegator which passes any methods it does not define--such as `fail' and `log'--through to the
+# Test Case instance.
+
+class Screen < SimpleDelegator
+
+  # Public: Initializes a Screen. NOT FOR USE IN TESTS.
+  #
+  # dut - Platform (or subclass) instance for this Screen.
+  #
+  # Returns nothing.
+  def initialize(dut)
+    super(dut.send(:test_case))
+    @keyboards = []
+    @dut = dut
+    instance_eval do
+      @navigate = method(:navigate)
+      def _navigate(args={})
+        sleep_time = args.fetch(:sleep_time, 0)
+        logger.info("Navigating to #{this_screen_symbol}")
+        unless displayed?
+          @navigate.call(args)
+        end
+        sleep(sleep_time) if sleep_time > 0
+      end
+      alias navigate _navigate
+      class << self
+        private :_navigate
+      end
+    end
+  end
+
+  # Public: This function is used to write the given text on the virtual keyboard.
+  #
+  # text       - String or Splat Array of String key(s) to write on the virtual keyboard.
+  # start_key  - String non-default start key (default: nil).
+  # verify_roi - Roi object to verify the typed text (default: nil).
+  # delay_between_keys  - Delay between key presses in ms min 3000 (default: 3000)
+  # reset      - Boolean indicating whether to reset the keyboard state before typing (default: false).
+  #
+  # Returns Boolean true if successfully able to write the given text. Else, returns false.
+  def type_keys?(*text, start_key: nil, verify_roi: nil, delay_between_keys:3000, reset: false)
+    arg = {verify: true, verify_roi: verify_roi}
+    if text.last.is_a?(Hash)
+      text.last.update(arg)
+    else
+      text << arg
+    end
+    type_keys(*text, start_key: start_key, delay_between_keys: delay_between_keys, reset: reset)
+  end
+
+  # Public: This function is used to write the given text on the virtual keyboard.
+  #
+  # text      - String or Splat Array of String key(s) to write on the virtual keyboard.
+  # start_key - String non-default start key (default: nil).
+  # delay_between_keys  - Delay between key presses in ms min 3000 (default: 3000)
+  # reset     - Boolean indicating whether to reset the keyboard state before typing (default: false).
+  #
+  # Returns nothing.
+  def type_keys(*text, start_key: nil, delay_between_keys: 3000, reset: false)
+    args = text.last.is_a?(Hash) ? text.pop : {}
+    args.update(start_key: start_key) unless start_key.nil?
+    args.update(delay_between_keys: delay_between_keys)
+    if current_keyboard(reset: reset).type?(text, args)
+      return true if args[:verify]
+    else
+      return false if args[:verify]
+      raise 'Failed to type text!'
+    end
+  end
+
+  # Public: This function is used to navigate to the given key on the virtual keyboard.
+  #
+  # key       - String key to navigate on the virtual keyboard.
+  # start_key - String non-default start key (default: nil).
+  # reset     - Boolean indicating whether to reset the keyboard state before navigating (default: false).
+  #
+  # Returns nothing.
+  def nav_to_key(key, start_key: nil, reset: false)
+    unless current_keyboard(reset: reset).type?(key, :start_key => start_key, :nav_only => true)
+      raise "Failed to navigate to key '#{key}'"
+    end
+  end
+
+  # Public: Checks if the current screen is displayed.
+  #
+  # timeout - Integer total milliseconds to check before timing out (default: 0.sec).
+  #
+  # Returns a Boolean true if the screen is displayed, otherwise false.
+  def displayed?(args={})
+    raise "#{self.class}.#{__method__} is not implemented!"
+  end
+
+  # Public: Navigates to this screen.
+  #
+  # sleep_time - Integer total milliseconds to sleep after performing the navigation (default: 0).
+  #
+  # Returns nothing.
+  def navigate(args={})
+    raise("Navigation not defined! #{this_screen_symbol}.navigate must be implemented.")
+  end
+
+  # Public: Navigates to this screen. This is a wrapper for 'navigate'.
+  #
+  # sleep_time - Integer total milliseconds to sleep after performing the navigation (default: 0).
+  #
+  # Returns nothing.
+  def nav_to(args={})
+    navigate(args)
+  end
+
+  # Public: Navigates to this screen and verifies it.
+  #
+  # timeout - Integer total milliseconds to wait for the screen to display after navigation (default: 10.sec).
+  #
+  # Returns a Boolean true if the navigation was successful, otherwise false.
+  def navigate?(args={})
+    timeout = args.fetch(:timeout, 10.sec)
+    navigate(:sleep_time => 0)
+    displayed?(:timeout => timeout)
+  end
+
+  # Public: Navigates to this screen and verifies it. This is a wrapper for 'navigate?'.
+  #
+  # timeout - Integer total milliseconds to wait for the screen to display after navigation (default: 10.sec).
+  #
+  # Returns a Boolean true if the navigation was successful, otherwise false.
+  def nav_to?(args={})
+    navigate?(args)
+  end
+
+  private
+
+  # Internal: Provides access to test case logger.
+  def logger
+    dut.send(:test_case).send(:logger_for_device, dut.id)
+  end
+
+  # Internal: Gets the currently-displayed virtual keyboard.
+  def current_keyboard(reset: false)
+    raise 'No keyboards defined!' if @keyboards.empty?
+    # determine current keyboard
+    keyboard = nil
+    @keyboards.each do |k|
+      if k.displayed?
+        keyboard = k
+        keyboard.reset if reset
+        break
+      end
+    end
+    raise 'Failed to determine current keyboard!' if keyboard.nil?
+    keyboard
+  end
+
+  # Internal: Exposes the dut object to all screens.
+  #
+  # Returns the DUT Platform (or subclass) instance.
+  def dut
+    @dut
+  end
+
+  # Internal: Gets the symbol for a screen.
+  #
+  # screen - The Screen object for which to get the symbol.
+  #
+  # Returns the Symbol for the screen.
+  def get_screen_symbol(screen)
+    dut_screens = @dut.screens.instance_variables.map { |s| s.to_s.delete('@') }
+    test_case = @dut.send(:test_case)
+    current_screen_full = test_case.to_snake_case(screen.name)
+    dut_screens.select { |s| current_screen_full.include?(s) }.max.to_sym  # longest match
+  end
+
+  # Internal: Gets the symbol for this screen.
+  #
+  # Returns the Symbol for this screen.
+  def this_screen_symbol
+    get_screen_symbol(self.class)
+  end
+
+end