appium_lib_core 1.7.2 → 1.8.0

data/lib/appium_lib_core/common/base/screenshot.rb

@@ -77,6 +77,24 @@ module Appium
             raise Core::Error::UnsupportedOperationError, "unsupported format: #{format.inspect}"
           end
         end
+
+        # @since 1.3.4
+        # @!method save_viewport_screenshot
+        # Save screenshot except for status bar while `@driver.save_screenshot` save entire screen.
+        #
+        # @example
+        #
+        #   @driver.save_viewport_screenshot 'path/to/save.png' #=> Get the File instance of viewport_screenshot
+        #
+        def save_viewport_screenshot(png_path)
+          extension = File.extname(png_path).downcase
+          if extension != '.png'
+            ::Appium::Logger.warn 'name used for saved screenshot does not match file type. '\
+                                  'It should end with .png extension'
+          end
+          viewport_screenshot_encode64 = bridge.take_viewport_screenshot
+          File.open(png_path, 'wb') { |f| f << viewport_screenshot_encode64.unpack('m')[0] }
+        end
       end
     end
   end

data/lib/appium_lib_core/common/device/app_management.rb

@@ -0,0 +1,87 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module AppManagement
+          def launch_app
+            execute :launch_app
+          end
+
+          def close_app
+            execute :close_app
+          end
+
+          def reset
+            execute :reset
+          end
+
+          def app_strings(language = nil)
+            opts = language ? { language: language } : {}
+            execute :app_strings, {}, opts
+          end
+
+          def background_app(duration = 0)
+            execute :background_app, {}, seconds: duration
+          end
+
+          def install_app(path,
+                          replace: nil,
+                          timeout: nil,
+                          allow_test_packages: nil,
+                          use_sdcard: nil,
+                          grant_permissions: nil)
+            args = { appPath: path }
+
+            args[:options] = {} unless options?(replace, timeout, allow_test_packages, use_sdcard, grant_permissions)
+
+            args[:options][:replace] = replace unless replace.nil?
+            args[:options][:timeout] = timeout unless timeout.nil?
+            args[:options][:allowTestPackages] = allow_test_packages unless allow_test_packages.nil?
+            args[:options][:useSdcard] = use_sdcard unless use_sdcard.nil?
+            args[:options][:grantPermissions] = grant_permissions unless grant_permissions.nil?
+
+            execute :install_app, {}, args
+          end
+
+          def remove_app(id, keep_data: nil, timeout: nil)
+            # required: [['appId'], ['bundleId']]
+            args = { appId: id }
+
+            args[:options] = {} unless keep_data.nil? || timeout.nil?
+            args[:options][:keepData] = keep_data unless keep_data.nil?
+            args[:options][:timeout] = timeout unless timeout.nil?
+
+            execute :remove_app, {}, args
+          end
+
+          def app_installed?(app_id)
+            # required: [['appId'], ['bundleId']]
+            execute :app_installed?, {}, bundleId: app_id
+          end
+
+          def activate_app(app_id)
+            # required: [['appId'], ['bundleId']]
+            execute :activate_app, {}, bundleId: app_id
+          end
+
+          def terminate_app(app_id, timeout: nil)
+            # required: [['appId'], ['bundleId']]
+            #
+            args = { appId: app_id }
+
+            args[:options] = {} unless timeout.nil?
+            args[:options][:timeout] = timeout unless timeout.nil?
+
+            execute :terminate_app, {}, args
+          end
+
+          private
+
+          def options?(replace, timeout, allow_test_packages, use_sdcard, grant_permissions)
+            replace.nil? || timeout.nil? || allow_test_packages.nil? || use_sdcard.nil? || grant_permissions.nil?
+          end
+        end # module AppManagement
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/app_state.rb

@@ -0,0 +1,30 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module AppState
+          STATUS = [
+            :not_installed,                   # 0
+            :not_running,                     # 1
+            :running_in_background_suspended, # 2
+            :running_in_background,           # 3
+            :running_in_foreground            # 4
+          ].freeze
+
+          def app_state(app_id)
+            # required: [['appId'], ['bundleId']]
+            response = execute :app_state, {}, appId: app_id
+
+            case response
+            when 0, 1, 2, 3, 4
+              STATUS[response]
+            else
+              ::Appium::Logger.debug("Unexpected status in app_state: #{response}")
+              response
+            end
+          end
+        end # module AppState
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/battery_status.rb

@@ -0,0 +1,25 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module BatteryStatus
+          ANDROID = [
+            :undefined,    # 0, dummy
+            :unknown,      # 1
+            :charging,     # 2
+            :discharging,  # 3
+            :not_charging, # 4
+            :full          # 5
+          ].freeze
+
+          IOS = [
+            :unknown,      # 0
+            :unplugged,    # 1
+            :charging,     # 2
+            :full          # 3
+          ].freeze
+        end # module BatteryStatus
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/clipboard_content_type.rb

@@ -0,0 +1,11 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module Clipboard
+          CONTENT_TYPE = [:plaintext, :image, :url].freeze
+        end
+      end # module Clipboard
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/context.rb

@@ -0,0 +1,38 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module Context
+          def within_context(context)
+            existing_context = current_context
+            set_context context
+            if block_given?
+              result = yield
+              set_context existing_context
+              result
+            else
+              set_context existing_context
+            end
+          end
+
+          def switch_to_default_context
+            set_context nil
+          end
+
+          def current_context
+            execute :current_context
+          end
+
+          def available_contexts
+            # return empty array instead of nil on failure
+            execute(:available_contexts, {}) || []
+          end
+
+          def set_context(context = null)
+            execute :set_context, {}, name: context
+          end
+        end # module ImeActions
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/device.rb

@@ -0,0 +1,19 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module Device
+          def shake
+            execute :shake
+          end
+
+          def device_time(format = nil)
+            arg = {}
+            arg[:format] = format unless format.nil?
+            execute :device_time, {}, arg
+          end
+        end # module Device
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/device_lock.rb

@@ -0,0 +1,22 @@
+module Appium
+  module Core
+    class Base
+      module Device
+        module DeviceLock
+          def lock(duration = nil)
+            opts = duration ? { seconds: duration } : {}
+            execute :lock, {}, opts
+          end
+
+          def device_locked?
+            execute :device_locked?
+          end
+
+          def unlock
+            execute :unlock
+          end
+        end # module DeviceLock
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/file_management.rb

@@ -0,0 +1,26 @@
+require 'base64'
+
+module Appium
+  module Core
+    class Base
+      module Device
+        module FileManagement
+          def push_file(path, filedata)
+            encoded_data = Base64.encode64 filedata
+            execute :push_file, {}, path: path, data: encoded_data
+          end
+
+          def pull_file(path)
+            data = execute :pull_file, {}, path: path
+            Base64.decode64 data
+          end
+
+          def pull_folder(path)
+            data = execute :pull_folder, {}, path: path
+            Base64.decode64 data
+          end
+        end # module FileManagement
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/common/device/image_comparison.rb

@@ -0,0 +1,168 @@
+require 'base64'
+
+module Appium
+  module Core
+    class Base
+      module Device
+        module ImageComparison
+          MODE = [:matchFeatures, :getSimilarity, :matchTemplate].freeze
+
+          MATCH_FEATURES = {
+            detector_name: %w(AKAZE AGAST BRISK FAST GFTT KAZE MSER SIFT ORB),
+            match_func: %w(FlannBased BruteForce BruteForceL1 BruteForceHamming BruteForceHammingLut BruteForceSL2),
+            goodMatchesFactor: nil, # Integer
+            visualize: [true, false]
+          }.freeze
+
+          MATCH_TEMPLATE = {
+            visualize: [true, false]
+          }.freeze
+
+          GET_SIMILARITY = {
+            visualize: [true, false]
+          }.freeze
+
+          # @!method match_images_features(first_image:, second_image:, detector_name: 'ORB',
+          #                                match_func: 'BruteForce', good_matches_factor: 100, visualize: false)
+          # Performs images matching by features with default options. Read https://docs.opencv.org/3.0-beta/doc/py_tutorials/py_feature2d/py_matcher/py_matcher.html
+          # for more details on this topic.
+          #
+          # @param [String] first_image An image data. All image formats, that OpenCV library itself accepts, are supported.
+          # @param [String] second_image An image data. All image formats, that OpenCV library itself accepts, are supported.
+          # @param [String] detector_name Sets the detector name for features matching
+          #                               algorithm. Some of these detectors (FAST, AGAST, GFTT, FAST, SIFT and MSER) are
+          #                               not available in the default OpenCV installation and have to be enabled manually
+          #                               before library compilation. The default detector name is 'ORB'.
+          # @param [String] match_func The name of the matching function. The default one is 'BruteForce'.
+          # @param [String] good_matches_factor The maximum count of "good" matches (e. g. with minimal distances).
+          #                                     The default one is nil.
+          # @param [Bool] visualise Makes the endpoint to return an image, which contains the visualized result of
+          #               the corresponding picture matching operation. This option is disabled by default.
+          #
+          # @example
+          #     @driver.match_images_features first_image: "image data 1", second_image: "image data 2"
+          #
+          #     visual = @@driver.match_images_features first_image: image1, second_image: image2, visualize: true
+          #     File.write 'match_images_visual.png', Base64.decode64(visual['visualization']) # if the image is PNG
+          #
+
+          # @!method find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil)
+          # Performs images matching by template to find possible occurrence of the partial image
+          # in the full image with default options. Read https://docs.opencv.org/2.4/doc/tutorials/imgproc/histograms/template_matching/template_matching.html
+          # for more details on this topic.
+          #
+          # @param [String] full_image: A full image data.
+          # @param [String] partial_image: A partial image data. All image formats, that OpenCV library itself accepts,
+          #                                are supported.
+          # @param [Bool] visualise: Makes the endpoint to return an image, which contains the visualized result of
+          #               the corresponding picture matching operation. This option is disabled by default.
+          # @param [Float] threshold: [0.5] At what normalized threshold to reject
+          #
+          # @example
+          #     @driver.find_image_occurrence full_image: "image data 1", partial_image: "image data 2"
+          #
+          #     visual = @@driver.find_image_occurrence full_image: image1, partial_image: image2, visualize: true
+          #     File.write 'find_result_visual.png', Base64.decode64(visual['visualization']) # if the image is PNG
+          #
+
+          # @!method get_images_similarity(first_image:, second_image:, detector_name: 'ORB', visualize: false)
+          # Performs images matching to calculate the similarity score between them
+          # with default options. The flow there is similar to the one used in `find_image_occurrence`
+          # but it is mandatory that both images are of equal size.
+          #
+          # @param [String] first_image: An image data. All image formats, that OpenCV library itself accepts, are supported.
+          # @param [String] second_image: An image data. All image formats, that OpenCV library itself accepts, are supported.
+          # @param [Bool] visualise: Makes the endpoint to return an image, which contains the visualized result of
+          #               the corresponding picture matching operation. This option is disabled by default.
+          #
+          # @example
+          #     @driver.get_images_similarity first_image: "image data 1", second_image: "image data 2"
+          #
+          #     visual = @@driver.get_images_similarity first_image: image1, second_image: image2, visualize: true
+          #     File.write 'images_similarity_visual.png', Base64.decode64(visual['visualization']) # if the image is PNG
+          #
+
+          # @!method compare_images(mode:, first_image:, second_image:, options:)
+          #
+          # Performs images comparison using OpenCV framework features.
+          # It is expected that both OpenCV framework and opencv4nodejs
+          # module are installed on the machine where Appium server is running.
+          #
+          # @param [Symbol] mode: One of possible comparison modes: `:matchFeatures`, `:getSimilarity`, `:matchTemplate`.
+          #                       `:matchFeatures is by default.
+          # @param [String] first_image: An image data. All image formats, that OpenCV library itself accepts, are supported.
+          # @param [String] second_image: An image data. All image formats, that OpenCV library itself accepts, are supported.
+          # @param [Hash] options: The content of this dictionary depends on the actual `mode` value.
+          #               See the documentation on `appium-support` module for more details.
+          # @returns [Hash] The content of the resulting dictionary depends on the actual `mode` and `options` values.
+          #                 See the documentation on `appium-support` module for more details.
+          #
+
+          ####
+          ## class << self
+          ####
+
+          def match_images_features(first_image:,
+                                    second_image:,
+                                    detector_name: 'ORB',
+                                    match_func: 'BruteForce',
+                                    good_matches_factor: nil,
+                                    visualize: false)
+            unless MATCH_FEATURES[:detector_name].member?(detector_name.to_s)
+              raise "detector_name should be #{MATCH_FEATURES[:detector_name]}"
+            end
+            unless MATCH_FEATURES[:match_func].member?(match_func.to_s)
+              raise "match_func should be #{MATCH_FEATURES[:match_func]}"
+            end
+            unless MATCH_FEATURES[:visualize].member?(visualize)
+              raise "visualize should be #{MATCH_FEATURES[:visualize]}"
+            end
+
+            options = {}
+            options[:detectorName] = detector_name.to_s.upcase
+            options[:matchFunc] = match_func.to_s
+            options[:goodMatchesFactor] = good_matches_factor.to_i unless good_matches_factor.nil?
+            options[:visualize] = visualize
+
+            compare_images(mode: :matchFeatures, first_image: first_image, second_image: second_image, options: options)
+          end
+
+          def find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil)
+            unless MATCH_TEMPLATE[:visualize].member?(visualize)
+              raise "visualize should be #{MATCH_TEMPLATE[:visualize]}"
+            end
+
+            options = {}
+            options[:visualize] = visualize
+            options[:threshold] = threshold unless threshold.nil?
+
+            compare_images(mode: :matchTemplate, first_image: full_image, second_image: partial_image, options: options)
+          end
+
+          def get_images_similarity(first_image:, second_image:, visualize: false)
+            unless GET_SIMILARITY[:visualize].member?(visualize)
+              raise "visualize should be #{GET_SIMILARITY[:visualize]}"
+            end
+
+            options = {}
+            options[:visualize] = visualize
+
+            compare_images(mode: :getSimilarity, first_image: first_image, second_image: second_image, options: options)
+          end
+
+          def compare_images(mode: :matchFeatures, first_image:, second_image:, options: nil)
+            raise "content_type should be #{MODE}" unless MODE.member?(mode)
+
+            params = {}
+            params[:mode] = mode
+            params[:firstImage] = Base64.encode64 first_image
+            params[:secondImage] = Base64.encode64 second_image
+            params[:options] = options if options
+
+            execute(:compare_images, {}, params)
+          end
+        end # module ImageComparison
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium