add execuite_driver (#222)

* add execuite_driver

* add element class converter

* append docstring, fix test code style

Author: KazuCocoa

.rubocop.yml

@@ -18,6 +18,9 @@ Metrics/ParameterLists:
   Max: 6
 Lint/NestedMethodDefinition:
   Enabled: false
+# TODO: Replace <<- with <<~ after dropping Ruby 2.2
+Layout/IndentHeredoc:
+  Enabled: false
 Style/Documentation:
   Enabled: false
 Style/CommentedKeyword:

CHANGELOG.md

@@ -5,6 +5,7 @@ Read `release_notes.md` for commit level details.
 ## [Unreleased]
 
 ### Enhancements
+- Add `execute_driver` to run a batch script on Appium 1.14.0+
 
 ### Bug fixes
 

lib/appium_lib_core/common/base.rb

@@ -28,6 +28,7 @@
 require_relative 'device/clipboard_content_type'
 require_relative 'device/device'
 require_relative 'device/touch_actions'
+require_relative 'device/execute_driver'
 
 # The following files have selenium-webdriver related stuff.
 require_relative 'base/driver'

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

@@ -31,6 +31,7 @@ class MJSONWP < ::Selenium::WebDriver::Remote::OSS::Bridge
           include Device::ScreenRecord::Command
           include Device::Device
           include Device::TouchActions
+          include Device::ExecuteDriver
 
           def commands(command)
             ::Appium::Core::Commands::MJSONWP::COMMANDS[command]
@@ -53,6 +54,13 @@ def take_viewport_screenshot
           def send_actions(_data)
             raise Error::UnsupportedOperationError, '#send_actions has not been supported in MJSONWP'
           end
+
+          # For Appium
+          # @param [Hash] id The id which can get as a response from server
+          # @return [::Selenium::WebDriver::Element]
+          def convert_to_element(id)
+            ::Selenium::WebDriver::Element.new self, element_id_from(id)
+          end
         end # class MJSONWP
       end # class Bridge
     end # class Base

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

@@ -31,6 +31,7 @@ class W3C < ::Selenium::WebDriver::Remote::W3C::Bridge
           include Device::ScreenRecord::Command
           include Device::Device
           include Device::TouchActions
+          include Device::ExecuteDriver
 
           def commands(command)
             ::Appium::Core::Commands::W3C::COMMANDS[command]
@@ -133,6 +134,13 @@ def find_elements_by(how, what, parent = nil)
             ids.map { |id| ::Selenium::WebDriver::Element.new self, element_id_from(id) }
           end
 
+          # For Appium
+          # @param [Hash] id The id which can get as a response from server
+          # @return [::Selenium::WebDriver::Element]
+          def convert_to_element(id)
+            ::Selenium::WebDriver::Element.new self, element_id_from(id)
+          end
+
           # For Appium
           # override
           # called in `extend DriverExtensions::HasNetworkConnection`

lib/appium_lib_core/common/base/driver.rb

@@ -1042,6 +1042,54 @@ def find_elements_by_image(img_path)
           template = Base64.strict_encode64 File.read img_path
           find_elements :image, template
         end
+
+        # @since Appium 1.14.0
+        #
+        # Run a set of script against the current session, allowing execution of many commands in one Appium request.
+        # Supports {https://webdriver.io/docs/api.html WebdriverIO} API so far.
+        # Please read {http://appium.io/docs/en/commands/session/execute-driver command API} for more details
+        # about acceptable scripts and the output.
+        #
+        # @param [String] script The string consisting of the script itself
+        # @param [String] type The name of the script type.
+        #                      Defaults to 'webdriverio'. Depends on server implementation which type is supported.
+        # @param [Integer] timeout_ms The number of `ms` Appium should wait for the script to finish
+        #                          before killing it due to timeout.
+        #
+        # @return [Appium::Core::Base::Device::ExecuteDriver::Result] The script result parsed by
+        #                          Appium::Core::Base::Device::ExecuteDriver::Result.
+        #
+        # @raise [::Selenium::WebDriver::Error::UnknownError] If something error happens in the script.
+        #                                                     It has the original message.
+        #
+        # @example
+        #      script = <<~SCRIPT
+        #        const status = await driver.status();
+        #        console.warn('warning message');
+        #        return [status];
+        #      SCRIPT
+        #      r = @@driver.execute_driver(script: script, type: 'webdriverio', timeout: 10_000)
+        #      r        #=> An instance of Appium::Core::Base::Device::ExecuteDriver::Result
+        #      r.result #=> The `result` key part as the result of the script
+        #      r.logs   #=> The `logs` key part as `{'log' => [], 'warn' => [], 'error' => []}`
+        #
+        def execute_driver(script: '', type: 'webdriverio', timeout_ms: nil)
+          @bridge.execute_driver(script: script, type: type, timeout_ms: timeout_ms)
+        end
+
+        # Convert vanilla element response to ::Selenium::WebDriver::Element
+        #
+        # @param [Hash] id The id which can get as a response from server
+        # @return [::Selenium::WebDriver::Element]
+        #
+        # @example
+        #     response = {"element-6066-11e4-a52e-4f735466cecf"=>"xxxx", "ELEMENT"=>"xxxx"}
+        #     ele = @driver.convert_to_element(response) #=> ::Selenium::WebDriver::Element
+        #     ele.rect #=> Can get the rect of the element
+        #
+        def convert_to_element(id)
+          @bridge.convert_to_element id
+        end
       end # class Driver
     end # class Base
   end # module Core

lib/appium_lib_core/common/command/common.rb

@@ -64,7 +64,8 @@ module Commands
         stop_recording_screen:      [:post, 'session/:session_id/appium/stop_recording_screen'],
         start_recording_screen:     [:post, 'session/:session_id/appium/start_recording_screen'],
         compare_images:             [:post, 'session/:session_id/appium/compare_images'],
-        is_keyboard_shown:          [:get,  'session/:session_id/appium/device/is_keyboard_shown']
+        is_keyboard_shown:          [:get,  'session/:session_id/appium/device/is_keyboard_shown'],
+        execute_driver:             [:post, 'session/:session_id/appium/execute_driver']
       }.freeze
 
       COMMAND_ANDROID = {

lib/appium_lib_core/common/device/execute_driver.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Appium
+  module Core
+    class Base
+      module Device
+        module ExecuteDriver
+          class Result
+            attr_reader :result, :logs
+
+            def initialize(response)
+              @result = response['result']
+              @logs = response['logs']
+            end
+          end
+
+          def execute_driver(script: '', type: 'webdriverio', timeout_ms: nil)
+            option = { script: script, type: type }
+
+            option[:timeout] = timeout_ms if timeout_ms
+
+            response = execute :execute_driver, {}, option
+            Result.new(response)
+          end
+        end # module Execute
+      end # module Device
+    end # class Base
+  end # module Core
+end # module Appium

lib/appium_lib_core/device.rb

@@ -39,7 +39,8 @@ def extended(_mod)
             :app_state,
             :stop_recording_screen, :stop_and_save_recording_screen,
             :shake, :device_time,
-            :touch_actions, :multi_touch
+            :touch_actions, :multi_touch,
+            :execute_driver
           ].each(&method(:delegate_from_appium_driver))
         end
 

test/functional/ios/driver_test.rb

@@ -72,8 +72,6 @@ def test_click_back
 
     # @since Appium 1.14.0
     def test_default_keyboard_pref
-      skip 'til WDA 0.0.6 will be released'
-
       bundle_id = @@driver.session_capabilities['CFBundleIdentifier']
       begin
         @@driver.activate_app('com.apple.Preferences')
@@ -89,6 +87,47 @@ def test_default_keyboard_pref
       assert_equal '0', switches_status['Predictive']
     end
 
+    # @since Appium 1.14.0
+    def test_batch
+      script = <<-SCRIPT
+const status = await driver.status();
+console.warn('warning message');
+return [status];
+      SCRIPT
+
+      r = @@driver.execute_driver(script: script, type: 'webdriverio', timeout_ms: 10_000)
+      assert(r.result.first['build'])
+      assert('warning message', r.logs['warn'].first)
+    end
+
+    # @since Appium 1.14.0
+    def test_batch_only_return
+      script = <<-SCRIPT
+      SCRIPT
+
+      r = @@driver.execute_driver(script: script, type: 'webdriverio')
+      assert(r.result.nil?)
+      assert([], r.logs['warn'])
+    end
+
+    # @since Appium 1.14.0
+    def test_batch_combination_ruby_script
+      script = <<-SCRIPT
+console.warn('warning message');
+const element = await driver.findElement('accessibility id', 'Buttons');
+const rect = await driver.getElementRect(element.ELEMENT);
+return [element, rect];
+      SCRIPT
+
+      r = @@driver.execute_driver(script: script)
+      ele = @@driver.convert_to_element(r.result.first)
+      rect = ele.rect
+      assert_equal(rect.x, r.result[1]['x'])
+      assert_equal(rect.y, r.result[1]['y'])
+      assert_equal(rect.width, r.result[1]['width'])
+      assert_equal(rect.height, r.result[1]['height'])
+    end
+
     # TODO: call @driver.quit after tests
   end
 end