testcentricity_mobile 4.0.0

data/lib/testcentricity_mobile/app_core/screen_object.rb

@@ -0,0 +1,413 @@
+require 'test/unit'
+
+module TestCentricity
+  class ScreenObject < BaseScreenSectionObject
+    include Test::Unit::Assertions
+
+    attr_reader :locator
+
+    def initialize
+      raise "Screen object #{self.class.name} does not have a screen_name trait defined" unless defined?(screen_name)
+      @locator = screen_locator if defined?(screen_locator)
+    end
+
+    # Declare and instantiate a single generic UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of UI object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    #   The locator_strategy (a Symbol) specifies the selector strategy that Appium will use to find the UI element. Valid
+    #   selectors are accessibility_id:, id:, name:, class:, xpath:, predicate: (iOS only), class_chain: (iOS only), and
+    #   css: (WebViews in hybrid apps only).
+    # * The locator_identifier (a String) is the value or attribute that uniquely and unambiguously identifies the UI element.
+    #
+    # @example
+    #   element :video_player, { accessibility_id: 'YouTube Video Player' }
+    #
+    def self.element(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppUIElement, locator)
+    end
+
+    # Declare and instantiate a collection of generic UI Elements for this screen object.
+    #
+    # @param element_hash [Hash] names of UI objects (as a Symbol) and locator Hash
+    # @example
+    #   elements drop_down_field: { accessibility_id: 'drop_trigger' },
+    #            settings_item: { accessibility_id: 'settings' },
+    #            video_player: { accessibility_id: 'YouTube Video Player' }
+    #
+    def self.elements(element_hash)
+      element_hash.each do |element_name, locator|
+        element(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single button UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of button object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   button :video_play,  { accessibility_id: 'video icon play' }
+    #
+    def self.button(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppButton, locator)
+    end
+
+    # Declare and instantiate a collection of buttons for this screen object.
+    #
+    # @param element_hash [Hash] names of buttons (as symbol) and locator Hash
+    # @example
+    #   buttons video_back:    { accessibility_id: 'video icon backward' },
+    #           video_play:    { accessibility_id: 'video icon play' },
+    #           video_pause:   { accessibility_id: 'video icon stop' },
+    #           video_forward: { accessibility_id: 'video icon forward' }
+    #
+    def self.buttons(element_hash)
+      element_hash.each do |element_name, locator|
+        button(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single textfield UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of textfield object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   textfield :payee_name_field, { xpath: '//android.widget.EditText[@content-desc="Full Name* input field"]' }
+    #   textfield :payee_name_field, { xpath: '//XCUIElementTypeTextField[@name="Full Name* input field"]' }
+    #
+    def self.textfield(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppTextField, locator)
+    end
+
+    # Declare and instantiate a collection of textfields for this screen object.
+    #
+    # @param element_hash [Hash] names of textfields (as symbol) and locator Hash
+    # @example
+    #   textfields username_field: { accessibility_id: 'Username input field' },
+    #              password_field: { accessibility_id: 'Password input field' }
+    #
+    def self.textfields(element_hash)
+      element_hash.each do |element_name, locator|
+        textfield(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single switch UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of switch object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   switch :debug_mode_switch, { accessibility_id: 'debug mode' }
+    #
+    def self.switch(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppSwitch, locator)
+    end
+
+    # Declare and instantiate a collection of switches for this screen object.
+    #
+    # @param element_hash [Hash] names of switches (as symbol) and locator Hash
+    # @example
+    #   switches debug_mode_switch: { accessibility_id: 'debug mode' },
+    #            metrics_switch: { accessibility_id: 'metrics' }
+    #
+    def self.switches(element_hash)
+      element_hash.each do |element_name, locator|
+        switch(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single checkbox UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of checkbox object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   checkbox :bill_address_check, { xpath: '//XCUIElementTypeOther[contains(@name, "billing checkbox")]'}
+    #
+    def self.checkbox(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppCheckBox, locator)
+    end
+
+    # Declare and instantiate a collection of checkboxes for this screen object.
+    #
+    # @param element_hash [Hash] names of checkboxes (as symbol) and locator Hash
+    # @example
+    #   checkboxes bill_address_check: { xpath: '//XCUIElementTypeOther[contains(@name, "billing checkbox")]'},
+    #              is_gift_check: { accessibility_id: 'is a gift' }
+    #
+    def self.checkboxes(element_hash)
+      element_hash.each do |element_name, locator|
+        checkbox(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single label UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of label object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   label :header_label, { accessibility_id: 'container header' }
+    #
+    def self.label(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppLabel, locator)
+    end
+
+    # Declare and instantiate a collection of labels for this screen object.
+    #
+    # @param element_hash [Hash] names of labels (as symbol) and locator Hash
+    # @example
+    #   labels total_qty_value:   { accessibility_id: 'total number' },
+    #          total_price_value: { accessibility_id: 'total price' }
+    #
+    def self.labels(element_hash)
+      element_hash.each do |element_name, locator|
+        label(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single list UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of list object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   list :carousel_list, { accessibility_id: 'Carousel' }
+    #
+    def self.list(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppList, locator)
+    end
+
+    # Declare and instantiate a collection of lists for this screen object.
+    #
+    # @param element_hash [Hash] names of lists (as symbol) and locator Hash
+    # @example
+    #   lists product_grid: { xpath: '//android.widget.ScrollView/android.view.ViewGroup' },
+    #         cart_list: { xpath: '//android.widget.ScrollView[@content-desc="cart screen"]' }
+    #
+    def self.lists(element_hash)
+      element_hash.each do |element_name, locator|
+        list(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single image UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of image object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   image :product_image, { xpath: '//XCUIElementTypeImage' }
+    #
+    def self.image(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppImage, locator)
+    end
+
+    # Declare and instantiate a collection of images for this screen object.
+    #
+    # @param element_hash [Hash] names of images (as symbol) and locator Hash
+    # @example
+    #   images empty_cart_image: { accessibility_id: 'empty_cart' },
+    #          logo_image: { accessibility_id: 'WebdriverIO logo' }
+    #
+    def self.images(element_hash)
+      element_hash.each do |element_name, locator|
+        image(element_name, locator)
+      end
+    end
+
+    # Declare and instantiate a single alert UI Element for this screen object.
+    #
+    # @param element_name [Symbol] name of alert object (as a symbol)
+    # @param locator [Hash] { locator_strategy: locator_identifier }
+    # @example
+    #   alert :generic_alert_modal, { id: 'android:id/parentPanel' }
+    #   alert :generic_alert_modal, { class: 'XCUIElementTypeAlert' }
+    #
+    def self.alert(element_name, locator)
+      define_screen_element(element_name, TestCentricity::AppElements::AppAlert, locator)
+    end
+
+    # Declare and instantiate a collection of alerts for this screen object.
+    #
+    # @param element_hash [Hash] names of alerts (as symbol) and locator Hash
+    # @example
+    #   alerts grant_modal: { id: 'com.android.permissioncontroller:id/grant_dialog' },
+    #          alert_modal: { id: 'android:id/parentPanel' }
+    #
+    def self.alerts(element_hash)
+      element_hash.each do |element_name, locator|
+        alert(element_name, locator)
+      end
+    end
+
+    # Instantiate a single ScreenSection object within this ScreenObject.
+    #
+    # @param section_name [Symbol] name of ScreenSection object (as a symbol)
+    # @param class_name [Class] Class name of ScreenSection object
+    # @example
+    #   section :nav_menu, NavMenu
+    #
+    def self.section(section_name, obj, locator = 0)
+      define_screen_element(section_name, obj, locator)
+    end
+
+    # Declare and instantiate a collection of ScreenSection objects for this screen object.
+    #
+    # @param element_hash [Hash] names of ScreenSections (as symbol) and class name
+    # @example
+    #   sections nav_bar:  NavBar,
+    #            nav_menu: NavMenu
+    #
+    def self.sections(section_hash)
+      section_hash.each do |section_name, class_name|
+        section(section_name, class_name)
+      end
+    end
+
+    # Does Screen object exists?
+    #
+    # @return [Boolean]
+    # @example
+    #   home_screen.exists?
+    #
+    def exists?
+      @locator.is_a?(Array) ? tries ||= 2 : tries ||= 1
+      if @locator.is_a?(Array)
+        loc = @locator[tries - 1]
+        find_element(loc.keys[0], loc.values[0])
+      else
+        find_element(@locator.keys[0], @locator.values[0])
+      end
+      true
+    rescue
+      retry if (tries -= 1) > 0
+      false
+    end
+
+    # Wait until the Screen object exists, or until the specified wait time has expired. If the wait time is nil, then
+    # the wait time will be Environ.default_max_wait_time.
+    #
+    # @param seconds [Integer or Float] wait time in seconds
+    # @example
+    #   cart_screen.wait_until_exists(15)
+    #
+    def wait_until_exists(seconds = nil, post_exception = true)
+      timeout = seconds.nil? ? Environ.default_max_wait_time : seconds
+      wait = Selenium::WebDriver::Wait.new(timeout: timeout)
+      wait.until { exists? }
+    rescue
+      if post_exception
+        raise "Screen object #{self.class.name} not found after #{timeout} seconds" unless exists?
+      else
+        exists?
+      end
+    end
+
+    # Wait until the Screen object is gone, or until the specified wait time has expired. If the wait time is nil, then
+    # the wait time will be Environ.default_max_wait_time.
+    #
+    # @param seconds [Integer or Float] wait time in seconds
+    # @example
+    #   login_screen.wait_until_gone(15)
+    #
+    def wait_until_gone(seconds = nil, post_exception = true)
+      timeout = seconds.nil? ? Environ.default_max_wait_time : seconds
+      wait = Selenium::WebDriver::Wait.new(timeout: timeout)
+      wait.until { !exists? }
+    rescue
+      if post_exception
+        raise "Screen object #{self.class.name} remained visible after #{timeout} seconds" if exists?
+      else
+        exists?
+      end
+    end
+
+    def navigate_to; end
+
+    def verify_screen_ui; end
+
+    # Verifies that the target screen is displayed, and sets ScreenManager.current_screen to reference the target screen
+    # instance.
+    #
+    def verify_screen_exists
+      wait = Selenium::WebDriver::Wait.new(timeout: Environ.default_max_wait_time)
+      wait.until { exists? }
+      ScreenManager.current_screen = self
+    rescue
+      raise "Could not find screen_locator for screen object '#{self.class.name}' (#{@locator}) after #{Environ.default_max_wait_time} seconds"
+    end
+
+    # Load the screen using its defined deep_link trait. When testing on physical iOS devices running iOS/iPadOS versions
+    # earlier than version 16.4, deep links can only be opened by sending the deeplink URL to the mobile Safari web browser,
+    # and then accepting the confirmation modal that pops up. This method handles invoking deeplinks on Android and iOS/iPadOS
+    # simulators and physical devices.
+    #
+    # This method verifies that the target screen is loaded and displayed, and sets ScreenManager.current_screen to reference
+    # the target screen instance.
+    #
+    # @example
+    #   cart_screen.load_screen
+    #
+    def load_screen
+      # return if target screen is already loaded
+      if exists?
+        ScreenManager.current_screen = self
+        return
+      end
+
+      url = if deep_link.include?("://")
+              deep_link
+            elsif !Environ.current.deep_link_prefix.blank?
+              link_url = "#{Environ.current.deep_link_prefix}://#{deep_link}"
+              # deeplink handler for Android devices
+              if Environ.is_android?
+                Environ.appium_driver.execute_script('mobile:deepLink', { url: link_url, package: Environ.current.android_app_id })
+                verify_screen_exists
+                return
+              else
+                link_url
+              end
+            end
+      # deeplink handler for iOS devices
+      if Environ.is_ios? && Environ.is_device? && Environ.device_os_version.to_f < 16.4
+        # launch Safari browser on iOS real device if iOS version is below 16.4
+        Environ.appium_driver.execute_script('mobile: launchApp', { bundleId: 'com.apple.mobilesafari' })
+        unless Environ.appium_driver.is_keyboard_shown
+          begin
+            # attempt to find and click URL button on iOS 15 Safari browser
+            find_element(:accessibility_id, 'TabBarItemTitle').click
+          rescue
+            # fall back to URL button on iOS 14 Safari browser
+            find_element(:xpath, '//XCUIElementTypeButton[@name="URL"]').click
+          end
+        end
+        # enter deep-link URL
+        wait_for_object(:xpath, '//XCUIElementTypeTextField[@name="URL"]', 5).send_keys("#{url}\uE007")
+        # wait for and accept the popup modal
+        wait_for_object(:xpath, '//XCUIElementTypeButton[@name="Open"]', 10).click
+      else
+        # iOS version is >= 16.4 so directly load screen via Selenium WebDriver
+        Environ.appium_driver.get(url)
+      end
+      verify_screen_exists
+    end
+
+    private
+
+    def self.define_screen_element(element_name, obj, locator)
+      define_method(element_name) do
+        ivar_name = "@#{element_name}"
+        ivar = instance_variable_get(ivar_name)
+        return ivar if ivar
+        instance_variable_set(ivar_name, obj.new(element_name, self, locator, :screen))
+      end
+    end
+
+    def wait_for_object(find_method, locator, seconds)
+      wait = Selenium::WebDriver::Wait.new(timeout: seconds)
+      obj = nil
+      wait.until do
+        obj = find_element(find_method, locator)
+        obj.displayed?
+      end
+      obj
+    end
+  end
+end

data/lib/testcentricity_mobile/app_core/screen_objects_helper.rb

@@ -0,0 +1,183 @@
+require 'test/unit'
+
+module TestCentricity
+  class BaseScreenSectionObject
+    # Define a trait for this screen or section object.
+    #
+    # Refer to the `Adding Traits to your ScreenObject` and `Adding Traits to a ScreenSection` sections of the ruby docs
+    # for this gem.
+    #
+    # @param trait_name [Symbol] name of trait (as a symbol)
+    # @param block [&block] trait value
+    # @example
+    #   trait(:screen_name)     { 'Shopping Basket' }
+    #   trait(:screen_locator)  { accessibility_id: 'My Contacts View' }
+    #   trait(:deep_link)       { 'geo-locations' }
+    #   trait(:section_name)    { 'Cart List Item' }
+    #   trait(:section_locator) { xpath: '(//XCUIElementTypeOther[@name="product row"])' }
+    #
+    def self.trait(trait_name, &block)
+      define_method(trait_name.to_s, &block)
+    end
+
+    # Populate the specified UI elements on this screen or section object with the associated data from a Hash passed as
+    # an argument. Data values must be in the form of a String for textfield controls. For checkboxes and switches, data
+    # must either be a Boolean or a String that evaluates to a Boolean value (Yes, No, 1, 0, true, false). For screen section
+    # objects, data values must be a String, and the screen section object must have a set method defined.
+    #
+    # The optional wait_time parameter is used to specify the time (in seconds) to wait for each UI element to become
+    # visible before entering the associated data value. This option is useful in situations where entering data, or
+    # setting the state of a UI element might cause other UI elements to become visible or active. Specifying a wait_time
+    # value ensures that the subsequent UI elements will be ready to be interacted with as states are changed. If the wait
+    # time is nil, then the wait time will be 5 seconds.
+    #
+    # To delete all text content in a text field, pass !DELETE as the data to be entered.
+    #
+    # If any of the specified UI elements are not currently visible, an attempt will be made to scroll the object in view.
+    #
+    # Refer to the `Populating your ScreenObject or ScreenSection with data` section of the ruby docs for this gem.
+    #
+    # @param data [Hash] UI element(s) and associated data to be entered
+    # @param wait_time [Integer] wait time in seconds
+    # @example
+    #     fields = {
+    #       payee_name_field => UserData.current.cardholder_name,
+    #       card_number_field => UserData.current.card_num,
+    #       expiration_field => UserData.current.expiry,
+    #       security_code_field => UserData.current.cvv
+    #     }
+    #     populate_data_fields(fields)
+    def populate_data_fields(data, wait_time = nil)
+      timeout = wait_time.nil? ? 2 : wait_time
+      data.each do |data_field, data_param|
+        unless data_param.blank?
+          # make sure the intended UI target element is visible before trying to set its value
+          data_field.scroll_into_view unless data_field.wait_until_visible(timeout, post_exception = false)
+          if data_param == '!DELETE'
+            data_field.clear
+          else
+            case data_field.get_object_type
+            when :checkbox
+              data_field.set_checkbox_state(data_param.to_bool)
+            when :textfield
+              data_field.clear
+              data_field.set(data_param)
+            end
+          end
+        end
+      end
+    end
+
+    # Verify one or more properties of one or more UI elements on a ScreenObject or ScreenSection. This method accepts
+    # a hash containing key/hash pairs of UI elements and their properties or attributes to be verified.
+    #
+    # Refer to the `Verifying AppUIElements on your ScreenObject or ScreenSection` section of the ruby docs for this gem.
+    #
+    # @param ui_states [Hash] UI element(s) and associated properties to be validated
+    # @param auto_scroll [Boolean] automatically scroll UI elements that are expected to be visible into view (default = true)
+    #
+    def verify_ui_states(ui_states, auto_scroll = true)
+      ui_states.each do |ui_object, object_states|
+        object_states.each do |property, state|
+          actual = case property
+                   when :visible
+                    if auto_scroll && state
+                      ui_object.scroll_into_view if ui_object.hidden?
+                     end
+                     ui_object.visible?
+                   when :class
+                     ui_object.get_attribute(:class)
+                   when :exists
+                     ui_object.exists?
+                   when :enabled
+                     ui_object.enabled?
+                   when :disabled
+                     ui_object.disabled?
+                   when :hidden
+                     ui_object.hidden?
+                   when :checked
+                     ui_object.checked?
+                   when :selected
+                     ui_object.selected?
+                   when :value
+                     ui_object.get_value
+                   when :caption
+                     ui_object.get_caption
+                   when :placeholder
+                     ui_object.get_placeholder
+                   when :readonly
+                     ui_object.read_only?
+                   when :maxlength
+                     ui_object.get_max_length
+                   when :items
+                     ui_object.get_list_items
+                   when :itemcount
+                     ui_object.get_item_count
+                   when :width
+                     ui_object.width
+                   when :height
+                     ui_object.height
+                   when :x
+                     ui_object.x_loc
+                   when :y
+                     ui_object.y_loc
+                   when :count
+                     ui_object.count
+                   when :buttons
+                     ui_object.buttons
+
+                   end
+          error_msg = "Expected UI object '#{ui_object.get_name}' (#{ui_object.get_locator}) #{property} property to"
+          ExceptionQueue.enqueue_comparison(ui_object, state, actual, error_msg)
+        end
+      end
+    rescue ObjectNotFoundError => e
+      ExceptionQueue.enqueue_exception(e.message)
+    ensure
+      ExceptionQueue.post_exceptions
+    end
+
+    # Perform a swipe gesture in the specified direction. The swipe start point is the center of the screen, and the
+    # swipe end point is the distance specified. A distance of 1 specifies a swipe gesture with a distance that is the
+    # full screen height (vertical swipe), or full screen width (horizontal swipe). A distance of 0.5 specifies a swipe
+    # gesture with a distance that is half the screen width or height.
+    #
+    # @param direction [Symbol] :up, :down, :left, or :right
+    # @param distance [Float] scroll distance relative to the screen height or width
+    # @example
+    #   swipe_gesture(direction = :down, distance = 1)
+    #
+    def swipe_gesture(direction, distance = 0.5)
+      raise 'Scroll distance must be between 0 and 1' if (distance < 0 || distance > 1)
+      size = window_size
+      mid_pt = [(size.width * 0.5).to_i, (size.height * 0.5).to_i]
+      top = (mid_pt[1] - ((size.height * distance) * 0.5)).to_i
+      bottom = (mid_pt[1] + ((size.height * distance) * 0.5)).to_i
+      left = (mid_pt[0] - ((size.width * distance) * 0.5)).to_i
+      right = (mid_pt[0] + ((size.width * distance) * 0.5)).to_i
+
+      case direction
+      when :up
+        start_pt = [mid_pt[0], top]
+        end_pt = [mid_pt[0], bottom]
+      when :down
+        start_pt = [mid_pt[0], bottom]
+        end_pt = [mid_pt[0], top]
+      when :left
+        start_pt = [left, mid_pt[1]]
+        end_pt = [right, mid_pt[1]]
+      when :right
+        start_pt = [right, mid_pt[1]]
+        end_pt = [left, mid_pt[1]]
+      end
+
+      puts "Swipe start_pt = #{start_pt} / end_pt = #{end_pt}" if ENV['DEBUG']
+      driver.action
+            .move_to_location(start_pt[0], start_pt[1])
+            .pointer_down
+            .move_to_location(end_pt[0], end_pt[1], duration: 0.25)
+            .release
+            .perform
+    end
+  end
+end