appium_lib_core 1.7.1 → 1.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 186c66ad7d2bd85ada277634f906739683741bca
-  data.tar.gz: 20c05598f4aa22bdbeccfd9ba57c032383a34b53
+  metadata.gz: e4396bf8502f02909fc45492b5f205554cd367f2
+  data.tar.gz: ece56ca4022cef888da977917121a403df721b47
 SHA512:
-  metadata.gz: 81483bed8fb09ad7e9cb5177593270de7eea8593ff83beee3c94e2d69bb9ca09805d9ce312751ac95fef2cb42f07910b6add32d07af896e35d501d2d44b2675f
-  data.tar.gz: 9f26c27dcb556240802069c9728f12c07d119fee0f4e46b5332074faa6946b330412ed5071e8b65a6f0b41273ff36c5654df855c5eea3b8746ed75e5df03737c
+  metadata.gz: 261082f3a1f085f18d549ad837d0b93dac630886ddcd24e4c40420744efac7f9ef0490ab94c32d171ba58816cb2607bd476988513a558435723eb7448ed212cc
+  data.tar.gz: f46ec6897d884275faa9260ef48c550c479e5173986e9464035e03d7af50e29ea576b97d2e33560e55ef0422c27990e5cb8b61dfe9d5761674ce3fd99cfbba51

data/CHANGELOG.md

@@ -8,6 +8,16 @@ All notable changes to this project will be documented in this file.
 
 ### Deprecations
 
+## [1.7.2] - 2018-06-23
+### Enhancements
+- Add a `ImageElement` to handle images as elements by `matchTemplate`
+   - Experimental feature
+- [Internal] Define screenshot methods in appium_lib_core instead of Selenium's one
+
+### Bug fixes
+
+### Deprecations
+
 ## [1.7.1] - 2018-06-15
 ### Enhancements
 - Add a `format` argument for `device_time` [#94](https://github.com/appium/ruby_lib_core/pull/94)

data/lib/appium_lib_core/common/base/bridge/mjsonwp.rb

@@ -6,6 +6,74 @@ module Appium
           def commands(command)
             ::Appium::Core::Commands::MJSONWP::COMMANDS[command]
           end
+
+          #
+          # @return [::Appium::Core::ImageElement|nil]
+          # @raise [::Selenium::WebDriver::Error::TimeOutError|::Selenium::WebDriver::Error::WebDriverError]
+          #
+          def find_element_by_image(full_image:, partial_image:, match_threshold: nil, visualize: false)
+            options = {}
+            options[:threshold] = match_threshold unless match_threshold.nil?
+            options[:visualize] = visualize
+
+            params = {}
+            params[:mode] = :matchTemplate
+            params[:firstImage] = full_image
+            params[:secondImage] = partial_image
+            params[:options] = options if options
+
+            result = execute(:compare_images, {}, params)
+            rect = result['rect']
+
+            if rect
+              return ::Appium::Core::ImageElement.new(self,
+                                                      rect['x'],
+                                                      rect['y'],
+                                                      rect['width'],
+                                                      rect['height'],
+                                                      result['visualization'])
+            end
+            nil
+          end
+
+          #
+          # @return [[]|[::Appium::Core::ImageElement]]
+          # @raise [::Selenium::WebDriver::Error::TimeOutError|::Selenium::WebDriver::Error::WebDriverError]
+          #
+          def find_elements_by_image(full_image:, partial_images:, match_threshold: nil, visualize: false)
+            options = {}
+            options[:threshold] = match_threshold unless match_threshold.nil?
+            options[:visualize] = visualize
+
+            params = {}
+            params[:mode] = :matchTemplate
+            params[:firstImage] = full_image
+            params[:options] = options if options
+
+            partial_images.each_with_object([]) do |partial_image, acc|
+              params[:secondImage] = partial_image
+
+              begin
+                result = execute(:compare_images, {}, params)
+                rect = result['rect']
+
+                if result['rect']
+                  acc.push ::Appium::Core::ImageElement.new(self,
+                                                            rect['x'],
+                                                            rect['y'],
+                                                            rect['width'],
+                                                            rect['height'],
+                                                            result['visualization'])
+                end
+              rescue ::Selenium::WebDriver::Error::WebDriverError => e
+                acc if e.message.include?('Cannot find any occurrences')
+              end
+            end
+          end
+
+          def take_element_screenshot(element)
+            execute :take_element_screenshot, id: element.ref
+          end
         end # class MJSONWP
       end # class Bridge
     end # class Base

data/lib/appium_lib_core/common/base/bridge/w3c.rb

@@ -1,3 +1,5 @@
+require 'base64'
+
 module Appium
   module Core
     class Base
@@ -84,6 +86,70 @@ module Appium
             ids.map { |id| ::Selenium::WebDriver::Element.new self, element_id_from(id) }
           end
 
+          #
+          # @return [::Appium::Core::ImageElement|nil]
+          # @raise [::Selenium::WebDriver::Error::TimeOutError|::Selenium::WebDriver::Error::WebDriverError]
+          #
+          def find_element_by_image(full_image:, partial_image:, match_threshold: nil, visualize: false)
+            options = {}
+            options[:threshold] = match_threshold unless match_threshold.nil?
+            options[:visualize] = visualize
+
+            params = {}
+            params[:mode] = :matchTemplate
+            params[:firstImage] = full_image
+            params[:secondImage] = partial_image
+            params[:options] = options if options
+
+            result = execute(:compare_images, {}, params)
+            rect = result['rect']
+
+            if rect
+              return ::Appium::Core::ImageElement.new(self,
+                                                      rect['x'],
+                                                      rect['y'],
+                                                      rect['width'],
+                                                      rect['height'],
+                                                      result['visualization'])
+            end
+            nil
+          end
+
+          #
+          # @return [[]|[::Appium::Core::ImageElement]]
+          # @raise [::Selenium::WebDriver::Error::TimeOutError|::Selenium::WebDriver::Error::WebDriverError]
+          #
+          def find_elements_by_image(full_image:, partial_images:, match_threshold: nil, visualize: false)
+            options = {}
+            options[:threshold] = match_threshold unless match_threshold.nil?
+            options[:visualize] = visualize
+
+            params = {}
+            params[:mode] = :matchTemplate
+            params[:firstImage] = full_image
+            params[:options] = options if options
+
+            partial_images.each_with_object([]) do |partial_image, acc|
+              params[:secondImage] = partial_image
+
+              begin
+                result = execute(:compare_images, {}, params)
+                rect = result['rect']
+
+                if result['rect']
+                  acc.push ::Appium::Core::ImageElement.new(self,
+                                                            rect['x'],
+                                                            rect['y'],
+                                                            rect['width'],
+                                                            rect['height'],
+                                                            result['visualization'])
+                end
+              rescue ::Selenium::WebDriver::Error::WebDriverError => e
+                acc if e.message.include?('Cannot find any occurrences')
+              end
+            end
+          end
+
           # For Appium
           # override
           # called in `extend DriverExtensions::HasNetworkConnection`
@@ -138,6 +204,10 @@ module Appium
             end
           end
 
+          def take_element_screenshot(element)
+            execute :take_element_screenshot, id: element.ref
+          end
+
           private
 
           # Don't convert locators for Appium Client

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

@@ -1,17 +1,19 @@
+require 'base64'
 require_relative 'search_context'
+require_relative 'screenshot'
 
 module Appium
   module Core
     class Base
       class Driver < ::Selenium::WebDriver::Driver
         include ::Selenium::WebDriver::DriverExtensions::UploadsFiles
-        include ::Selenium::WebDriver::DriverExtensions::TakesScreenshot
         include ::Selenium::WebDriver::DriverExtensions::HasSessionId
         include ::Selenium::WebDriver::DriverExtensions::Rotatable
         include ::Selenium::WebDriver::DriverExtensions::HasRemoteStatus
         include ::Selenium::WebDriver::DriverExtensions::HasWebStorage
 
         include ::Appium::Core::Base::SearchContext
+        include ::Appium::Core::Base::TakeScreenshot
 
         def initialize(opts = {})
           listener = opts.delete(:listener)
@@ -183,6 +185,77 @@ module Appium
         def session_capabilities
           @bridge.session_capabilities
         end
+
+        DEFAULT_MATCH_THRESHOLD = 0.5
+
+        # Return ImageElement if current view has a partial image
+        #
+        # @param [String] png_img_path A path to a partial image you'd like to find
+        # @param [Flood] match_threshold At what normalized threshold to reject
+        # @param [Bool] visualize Makes the endpoint to return an image, which contains the visualized result of
+        #                         the corresponding picture matching operation. This option is disabled by default.
+        #
+        # @return [::Appium::Core::ImageElement]
+        # @raise [::Appium::Core::Error::NoSuchElementError|::Appium::Core::Error::CoreError] No such element
+        #
+        # @example
+        #
+        #     e = @@driver.find_element_by_image './test/functional/data/test_element_image.png'
+        #
+        def find_element_by_image(png_img_path, match_threshold: DEFAULT_MATCH_THRESHOLD, visualize: false)
+          full_image = @bridge.screenshot
+          partial_image = Base64.encode64 File.read(png_img_path)
+
+          element = begin
+            @bridge.find_element_by_image(full_image: full_image,
+                                          partial_image: partial_image,
+                                          match_threshold: match_threshold,
+                                          visualize: visualize)
+          rescue Selenium::WebDriver::Error::TimeOutError
+            raise ::Appium::Core::Error::NoSuchElementError
+          rescue ::Selenium::WebDriver::Error::WebDriverError => e
+            raise ::Appium::Core::Error::NoSuchElementError if e.message.include?('Cannot find any occurrences')
+            raise ::Appium::Core::Error::CoreError, e.message
+          end
+          raise ::Appium::Core::Error::NoSuchElementError if element.nil?
+
+          element
+        end
+
+        # Return ImageElement if current view has partial images
+        #
+        # @param [[String]] png_img_paths Paths to a partial image you'd like to find
+        # @param [Flood] match_threshold At what normalized threshold to reject
+        # @param [Bool] visualize Makes the endpoint to return an image, which contains the visualized result of
+        #                         the corresponding picture matching operation. This option is disabled by default.
+        #
+        # @return [[::Appium::Core::ImageElement]]
+        # @return [::Appium::Core::Error::CoreError]
+        #
+        # @example
+        #
+        #     e = @@driver.find_elements_by_image './test/functional/data/test_element_image.png'
+        #     e == [] # if the `e` is empty
+        #
+        def find_elements_by_image(png_img_paths, match_threshold: DEFAULT_MATCH_THRESHOLD, visualize: false)
+          full_image = @bridge.screenshot
+
+          partial_images = png_img_paths.map do |png_img_path|
+            Base64.encode64 File.read(png_img_path)
+          end
+
+          begin
+            @bridge.find_elements_by_image(full_image: full_image,
+                                           partial_images: partial_images,
+                                           match_threshold: match_threshold,
+                                           visualize: visualize)
+          rescue Selenium::WebDriver::Error::TimeOutError
+            []
+          rescue ::Selenium::WebDriver::Error::WebDriverError => e
+            return [] if e.message.include?('Cannot find any occurrences')
+            raise ::Appium::Core::Error::CoreError, e.message
+          end
+        end
       end # class Driver
     end # class Base
   end # module Core

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

@@ -0,0 +1,83 @@
+module Appium
+  module Core
+    class Base
+      module TakeScreenshot
+        #
+        # Save a PNG screenshot to the given path
+        #
+        # @api public
+        #
+        def save_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
+          File.open(png_path, 'wb') { |f| f << screenshot_as(:png) }
+        end
+
+        #
+        # Return a PNG screenshot in the given format as a string
+        #
+        # @param [:base64, :png] format
+        # @return String screenshot
+        #
+        # @example
+        #
+        #     @@driver.screenshot_as :base64 #=> "iVBORw0KGgoAAAANSUhEUgAABDgAAAB+CAIAAABOPDa6AAAAAX"
+        #
+        # @api public
+        def screenshot_as(format)
+          case format
+          when :base64
+            bridge.screenshot
+          when :png
+            bridge.screenshot.unpack('m')[0]
+          else
+            raise Core::Error::UnsupportedOperationError, "unsupported format: #{format.inspect}"
+          end
+        end
+
+        # @param [Selenium::WebDriver::Element] element A element you'd like to take screenshot.
+        # @param [String] png_path A path to save the screenshot
+        # @return [File] Path to the screenshot.
+        #
+        # @example
+        #
+        #   @driver.save_element_screenshot(element, "fine_name.png")
+        #
+        def save_element_screenshot(element, 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
+          File.open(png_path, 'wb') { |f| f << element_screenshot_as(element, :png) }
+        end
+        # backward compatibility
+        alias take_element_screenshot save_element_screenshot
+
+        #
+        # Return a PNG screenshot in the given format as a string
+        #
+        # @param [:base64, :png] format
+        # @return String screenshot
+        #
+        # @example
+        #
+        #     @@driver.element_screenshot_as element, :base64 #=> "iVBORw0KGgoAAAANSUhEUgAABDgAAAB+CAIAAABOPDa6AAAAAX"
+        #
+        def element_screenshot_as(element, format)
+          case format
+          when :base64
+            bridge.take_element_screenshot(element)
+          when :png
+            bridge.take_element_screenshot(element).unpack('m')[0]
+          else
+            raise Core::Error::UnsupportedOperationError, "unsupported format: #{format.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib_core/common/error.rb

@@ -11,6 +11,8 @@ module Appium
       class NotSupportedAppiumServer < CoreError; end
       class NoSuchElementError < CoreError; end
 
+      class UnsupportedOperationError < CoreError; end
+
       # Server side error
       class ServerError; end
     end

data/lib/appium_lib_core/device.rb

@@ -1,6 +1,8 @@
 require_relative 'common/touch_action/touch_actions'
 require_relative 'common/touch_action/multi_touch'
 
+require_relative 'element/image'
+
 require_relative 'device/screen_record'
 require_relative 'device/app_state'
 require_relative 'device/clipboard_content_type'
@@ -475,16 +477,6 @@ module Appium
       #   @driver.switch_to_default_context
       #
 
-      # @!method take_element_screenshot(element, png_path)
-      # @param [Selenium::WebDriver::Element] element A element you'd like to take screenshot.
-      # @param [String] png_path A path to save the screenshot
-      # @return [File] Path to the screenshot.
-      #
-      # @example
-      #
-      #   @driver.take_element_screenshot(element, "fine_name.png")
-      #
-
       # @!method stop_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT')
       # @param [String] remote_path: The path to the remote location, where the resulting video should be uploaded.
       #                             The following protocols are supported: http/https, ftp.
@@ -534,19 +526,6 @@ module Appium
             end
           end
 
-          add_endpoint_method(:take_element_screenshot) do
-            def take_element_screenshot(element, png_path)
-              result = execute :take_element_screenshot, id: element.ref
-
-              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
-              File.open(png_path, 'wb') { |f| f << result.unpack('m')[0] }
-            end
-          end
-
           add_endpoint_method(:save_viewport_screenshot) do
             def save_viewport_screenshot(png_path)
               extension = File.extname(png_path).downcase
@@ -572,6 +551,10 @@ module Appium
           ScreenRecord.add_methods
           ImageComparison.add_methods
           AppState.add_methods
+
+          # Compatibility for appium_lib
+          # TODO: Will remove
+          delegate_from_appium_driver :take_element_screenshot
         end
 
         # def extended

data/lib/appium_lib_core/device/image_comparison.rb

@@ -45,7 +45,7 @@ module Appium
         #     File.write 'match_images_visual.png', Base64.decode64(visual['visualization']) # if the image is PNG
         #
 
-        # @!method find_image_occurrence(full_image:, partial_image:, detector_name: 'ORB', visualize: false)
+        # @!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.
@@ -55,6 +55,7 @@ module Appium
         #                                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"
@@ -129,13 +130,14 @@ module Appium
           end
 
           ::Appium::Core::Device.add_endpoint_method(:find_image_occurrence) do
-            def find_image_occurrence(full_image:, partial_image:, visualize: false)
+            def find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil)
               unless ::Appium::Core::Device::ImageComparison::MATCH_TEMPLATE[:visualize].member?(visualize)
                 raise "visualize should be #{::Appium::Core::Device::ImageComparison::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

data/lib/appium_lib_core/element/image.rb

@@ -0,0 +1,106 @@
+module Appium
+  module Core
+    #
+    # ImageElement is an element for images by `find_element/s_by_image`
+    # Experimental feature
+    #
+    class ImageElement
+      Point     = Struct.new(:x, :y)
+      Dimension = Struct.new(:width, :height)
+      Rectangle = Struct.new(:x, :y, :width, :height)
+
+      # Base64ed format
+      # @example
+      #
+      #     File.write 'result.png', Base64.decode64(e.visual)
+      #
+      attr_reader :visual
+
+      def initialize(bridge, x, y, width, height, visual = nil) # rubocop:disable Metrics/ParameterLists
+        @bridge = bridge
+        @visual = visual
+
+        @center_x = x + width / 2
+        @center_y = y + height / 2
+        @x = x
+        @y = y
+        @width = width
+        @height = height
+      end
+
+      #
+      # Click this element.
+      #
+      # @example
+      #
+      #     e = @@driver.find_element_by_image './test/functional/data/test_element_image.png'
+      #     e.click
+      #
+      def click
+        @bridge.action.move_to_location(@center_x, @center_y).click.perform
+      end
+
+      #
+      # Get the location of this element.
+      #
+      # @return [Point]
+      #
+      # @example
+      #
+      #     e = @@driver.find_element_by_image './test/functional/data/test_element_image.png'
+      #     assert_equal [39, 1014], [e.location.x, e.location.y]
+      #
+      def location
+        Point.new @x, @y
+      end
+
+      #
+      # Get the size of this element
+      #
+      # @return [Dimension]
+      #
+      # @example
+      #
+      #     e = @@driver.find_element_by_image './test/functional/data/test_element_image.png'
+      #         assert_equal [326, 62], [e.size.width, e.size.height]
+      #
+      def size
+        Dimension.new @width, @height
+      end
+
+      #
+      # Get the dimensions and coordinates of this element.
+      #
+      # @return [Rectangle]
+      #
+      # @example
+      #
+      #     e = @@driver.find_element_by_image './test/functional/data/test_element_image.png'
+      #         assert_equal([39, 1014, 326, 62], [e.rect.x, e.rect.y, e.rect.width, e.rect.height])
+      #
+      def rect
+        Rectangle.new @x, @y, @width, @height
+      end
+
+      def displayed?
+        true
+      end
+
+      #-------------------------------- sugar  --------------------------------
+
+      def first(full_image:, partial_image:, match_threshold: nil, visualize: false)
+        @bridge.find_element_by_image(full_image: full_image,
+                                      partial_image: partial_image,
+                                      match_threshold: match_threshold,
+                                      visualize: visualize)
+      end
+
+      def all(full_image:, partial_image:, match_threshold: nil, visualize: false)
+        @bridge.find_elements_by_image(full_image: full_image,
+                                       partial_image: partial_image,
+                                       match_threshold: match_threshold,
+                                       visualize: visualize)
+      end
+    end
+  end
+end

data/lib/appium_lib_core/version.rb

@@ -1,6 +1,6 @@
 module Appium
   module Core
-    VERSION = '1.7.1'.freeze unless defined? ::Appium::Core::VERSION
-    DATE    = '2018-06-15'.freeze unless defined? ::Appium::Core::DATE
+    VERSION = '1.7.2'.freeze unless defined? ::Appium::Core::VERSION
+    DATE    = '2018-06-23'.freeze unless defined? ::Appium::Core::DATE
   end
 end

data/release_notes.md

@@ -1,3 +1,11 @@
+#### v1.7.2 2018-06-23
+
+- [72bbc01](https://github.com/appium/ruby_lib_core/commit/72bbc01dc69579c5b7dea43b6ec01fee37299ebe) Release 1.7.2
+- [5438246](https://github.com/appium/ruby_lib_core/commit/54382468e226d38f16d651b7b9f6da952d766d22) Define screenshot methods in this lib (#98)
+- [9bd9e11](https://github.com/appium/ruby_lib_core/commit/9bd9e11c20ce37a9e8e0384c09c663913aca0d15) Use bridge for imageelement(#96)
+- [7e7fba3](https://github.com/appium/ruby_lib_core/commit/7e7fba32a89ce547e81d68eb6659db464be7a60f) add image element/s (#95)
+
+
 #### v1.7.1 2018-06-15
 
 - [84febaf](https://github.com/appium/ruby_lib_core/commit/84febaf3a5b4dff0084455556d3ffe1293b64471) Release 1.7.1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appium_lib_core
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.7.2
 platform: ruby
 authors:
 - Kazuaki MATSUO
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-14 00:00:00.000000000 Z
+date: 2018-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -245,6 +245,7 @@ files:
 - lib/appium_lib_core/common/base/command.rb
 - lib/appium_lib_core/common/base/driver.rb
 - lib/appium_lib_core/common/base/http_default.rb
+- lib/appium_lib_core/common/base/screenshot.rb
 - lib/appium_lib_core/common/base/search_context.rb
 - lib/appium_lib_core/common/command.rb
 - lib/appium_lib_core/common/command/common.rb
@@ -275,6 +276,7 @@ files:
 - lib/appium_lib_core/device/touch_actions.rb
 - lib/appium_lib_core/device/value.rb
 - lib/appium_lib_core/driver.rb
+- lib/appium_lib_core/element/image.rb
 - lib/appium_lib_core/ios.rb
 - lib/appium_lib_core/ios/device.rb
 - lib/appium_lib_core/ios/device/clipboard.rb