arrange consts names and add some options for app management (#59)

KazuCocoa · web-flow · commit 29c528e8b407 · 2018-02-10T00:24:04.000+09:00
* arrange consts names

* add options for manage apps

* fix rubocop

* update documentation

* add only for android

* arrange a bit
diff --git a/lib/appium_lib_core.rb b/lib/appium_lib_core.rb
@@ -9,7 +9,7 @@
 require_relative 'appium_lib_core/device/touch_actions'
 require_relative 'appium_lib_core/device/multi_touch'
 require_relative 'appium_lib_core/device/screen_record'
-require_relative 'appium_lib_core/device/app_management'
+require_relative 'appium_lib_core/device/app_state'
 
 require_relative 'appium_lib_core/android'
 require_relative 'appium_lib_core/android_uiautomator2'
diff --git a/lib/appium_lib_core/common/command.rb b/lib/appium_lib_core/common/command.rb
@@ -40,7 +40,7 @@ module Commands
         app_installed?:             [:post, 'session/:session_id/appium/device/app_installed'.freeze],
         activate_app:               [:post, 'session/:session_id/appium/device/activate_app'.freeze],
         terminate_app:              [:post, 'session/:session_id/appium/device/terminate_app'.freeze],
-        app_state:                  [:get,  'session/:session_id/appium/device/app_state'.freeze],
+        app_state:                  [:post, 'session/:session_id/appium/device/app_state'.freeze],
         background_app:             [:post, 'session/:session_id/appium/app/background'.freeze],
         hide_keyboard:              [:post, 'session/:session_id/appium/device/hide_keyboard'.freeze],
         press_keycode:              [:post, 'session/:session_id/appium/device/press_keycode'.freeze],
diff --git a/lib/appium_lib_core/common/device.rb b/lib/appium_lib_core/common/device.rb
@@ -49,7 +49,7 @@ module Device
 
       # @!method is_keyboard_shown
       # Get whether keyboard is displayed or not.
-      # @return [Bool] Return true if keyboard is shown. Return false if keyboard is hidden.
+      # @return [Boolean] Return true if keyboard is shown. Return false if keyboard is hidden.
       #
       # @example
       #   @driver.is_keyboard_shown # false
@@ -142,25 +142,37 @@ module Device
       ## With arguments
       ####
 
-      # @!method install_app(path)
+      # @!method install_app(path, replace: nil, timeout: nil, allow_test_packages: nil, use_sdcard: nil, grant_permissions: nil)
       # Install the given app onto the device
       #
+      # @param [String] path The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these.
+      # @param [Boolean] replace: Only for Android. Whether to reinstall/upgrade the package if it is already present on the device under test. `true` by default
+      # @param [Integer] timeout: Only for Android. How much time to wait for the installation to complete. 60000ms by default.
+      # @param [Boolean] allow_test_packages: Only for Android. Whether to allow installation of packages marked as test in the manifest. `false` by default
+      # @param [Boolean] use_sdcard: Only for Android. Whether to use the SD card to install the app. `false` by default
+      # @param [Boolean] grant_permissions:  Only for Android. whether to automatically grant application permissions on Android 6+ after the installation completes. `false` by default
+      #
       # @example
       #
       #   @driver.install_app("/path/to/test.apk")
+      #   @driver.install_app("/path/to/test.apk", replace: true, timeout: 20000, allow_test_packages: true, use_sdcard: false, grant_permissions: false)
       #
 
-      # @!method remove_app(app_id)
-      # Install the given app onto the device
+      # @!method remove_app(app_id, keep_data: nil, timeout: nil)
+      #
+      # @param [Strong] app_id BundleId for iOS or package name for Android
+      # @param [Boolean] keep_data: Only for Android. Whether to keep application data and caches after it is uninstalled. `false` by default
+      # @param [Integer] timeout: Only for Android. How much time to wait for the uninstall to complete. 20000ms by default.
       #
       # @example
       #
       #   @driver.remove_app("io.appium.bundle")
+      #   @driver.remove_app("io.appium.bundle", keep_data: false, timeout, 10000)
       #
 
       # @!method app_installed?(app_id)
       # Check whether the specified app is installed on the device
-      # @return [bool]
+      # @return [Boolean]
       #
       # @example
       #
@@ -169,11 +181,15 @@ module Device
 
       # @!method terminate_app(app_id)
       # Terminate the specified app.
-      # @return [bool]
+      #
+      # @param [Strong] app_id BundleId for iOS or package name for Android
+      # @param [Integer] timeout: Only for Android. How much time to wait for the application termination to complete. 500ms by default.
+      # @return [Boolean]
       #
       # @example
       #
       #   @driver.terminate_app("io.appium.bundle") # true
+      #   @driver.terminate_app("io.appium.bundle", timeout: 500)
       #
 
       # @!method activate_app(app_id)
@@ -187,11 +203,11 @@ module Device
 
       # Get the status of an existing application on the device.
       # State:
-      #   AppManagement::APP_STATE_NOT_INSTALLED : The current application state cannot be determined/is unknown
-      #   AppManagement::APP_STATE_NOT_RUNNING : The application is not running
-      #   AppManagement::APP_STATE_RUNNING_IN_BACKGROUND_SUSPEND : The application is running in the background and is suspended
-      #   AppManagement::APP_STATE_RUNNING_IN_BACKGROUND : The application is running in the background and is not suspended
-      #   AppManagement::APP_STATE_RUNNING_IN_FOREGROUND : The application is running in the foreground
+      #   AppState::NOT_INSTALLED : The current application state cannot be determined/is unknown
+      #   AppState::NOT_RUNNING : The application is not running
+      #   AppState::RUNNING_IN_BACKGROUND_SUSPENDED : The application is running in the background and is suspended
+      #   AppState::RUNNING_IN_BACKGROUND : The application is running in the background and is not suspended
+      #   AppState::RUNNING_IN_FOREGROUND : The application is running in the foreground
       #
       # For more details: https://developer.apple.com/documentation/xctest/xcuiapplicationstate
       #
@@ -630,17 +646,45 @@ def create_bridge_command(method)
           end
         end
 
+        # rubocop:disable Metrics/ParameterLists,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
         def add_app_management
           add_endpoint_method(:install_app) do
-            def install_app(path)
-              execute :install_app, {}, appPath: path
+            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
+
+            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
 
           add_endpoint_method(:remove_app) do
-            def remove_app(id)
+            def remove_app(id, keep_data: nil, timeout: nil)
               # required: [['appId'], ['bundleId']]
-              execute :remove_app, {}, appId: id
+              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
           end
 
@@ -659,9 +703,15 @@ def activate_app(app_id)
           end
 
           add_endpoint_method(:terminate_app) do
-            def terminate_app(app_id)
+            def terminate_app(app_id, timeout: nil)
               # required: [['appId'], ['bundleId']]
-              execute :terminate_app, {}, appId: app_id
+              #
+              args = { appId: app_id }
+
+              args[:options] = {} unless timeout.nil?
+              args[:options][:timeout] = timeout unless timeout.nil?
+
+              execute :terminate_app, {}, args
             end
           end
 
@@ -672,22 +722,23 @@ def app_state(app_id)
 
               case response
               when 0
-                Appium::Core::Device::AppManagement::APP_STATE_NOT_INSTALLED
+                Appium::Core::Device::AppState::NOT_INSTALLED
               when 1
-                Appium::Core::Device::AppManagement::APP_STATE_NOT_RUNNING
+                Appium::Core::Device::AppState::NOT_RUNNING
               when 2
-                Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_BACKGROUND_SUSPEND
+                Appium::Core::Device::AppState::RUNNING_IN_BACKGROUND_SUSPENDED
               when 3
-                Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_BACKGROUND
+                Appium::Core::Device::AppState::RUNNING_IN_BACKGROUND
               when 4
-                Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_FOREGROUND
+                Appium::Core::Device::AppState::RUNNING_IN_FOREGROUND
               else
                 Appium::Logger.debug("Unexpected status in app_state: #{response}")
                 response
               end
             end
           end
         end
+        # rubocop:enable Metrics/ParameterLists,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
 
         def add_keyevent
           # Only for Selendroid
diff --git a/lib/appium_lib_core/device/app_management.rb b/lib/appium_lib_core/device/app_management.rb
diff --git a/lib/appium_lib_core/device/app_state.rb b/lib/appium_lib_core/device/app_state.rb
@@ -0,0 +1,13 @@
+module Appium
+  module Core
+    module Device
+      class AppState
+        NOT_INSTALLED = 0
+        NOT_RUNNING = 1
+        RUNNING_IN_BACKGROUND_SUSPENDED = 2
+        RUNNING_IN_BACKGROUND = 3
+        RUNNING_IN_FOREGROUND = 4
+      end
+    end
+  end
+end
diff --git a/test/functional/android/android/device_test.rb b/test/functional/android/android/device_test.rb
@@ -110,15 +110,15 @@ def test_re_install
 
       def test_app_management
         assert @@driver.app_state('io.appium.android.apis') ==
-               Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_FOREGROUND
+               Appium::Core::Device::AppState::RUNNING_IN_FOREGROUND
 
         assert @@driver.terminate_app('io.appium.android.apis')
         assert @@driver.app_state('io.appium.android.apis') ==
-               Appium::Core::Device::AppManagement::APP_STATE_NOT_RUNNING
+               Appium::Core::Device::AppState::NOT_RUNNING
 
         assert @@driver.activate_app('io.appium.android.apis').nil?
         assert @@driver.app_state('io.appium.android.apis') ==
-               Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_FOREGROUND
+               Appium::Core::Device::AppState::RUNNING_IN_FOREGROUND
       end
 
       def test_start_activity
diff --git a/test/functional/ios/ios/device_test.rb b/test/functional/ios/ios/device_test.rb
@@ -109,15 +109,15 @@ def test_re_install
 
       def test_app_management
         assert @@driver.app_state('com.example.apple-samplecode.UICatalog') ==
-               Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_FOREGROUND
+               Appium::Core::Device::AppState::RUNNING_IN_FOREGROUND
 
         assert @@driver.terminate_app('com.example.apple-samplecode.UICatalog')
         assert @@driver.app_state('com.example.apple-samplecode.UICatalog') ==
-               Appium::Core::Device::AppManagement::APP_STATE_NOT_RUNNING
+               Appium::Core::Device::AppState::NOT_RUNNING
 
         assert @@driver.activate_app('com.example.apple-samplecode.UICatalog') == {}
         assert @@driver.app_state('com.example.apple-samplecode.UICatalog') ==
-               Appium::Core::Device::AppManagement::APP_STATE_RUNNING_IN_FOREGROUND
+               Appium::Core::Device::AppState::RUNNING_IN_FOREGROUND
       end
 
       def test_push_pull
diff --git a/test/unit/android/device_test.rb b/test/unit/android/device_test.rb
@@ -280,6 +280,28 @@ def test_install_app
         assert_requested(:post, "#{SESSION}/appium/device/install_app", times: 1)
       end
 
+      def test_install_app_with_params
+        stub_request(:post, "#{SESSION}/appium/device/install_app")
+          .with(body: { appPath: 'app_path',
+                        options: {
+                          replace: true,
+                          timeout: 20_000,
+                          allowTestPackages: true,
+                          useSdcard: false,
+                          grantPermissions: false
+                        } }.to_json)
+          .to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
+
+        @driver.install_app 'app_path',
+                            replace: true,
+                            timeout: 20_000,
+                            allow_test_packages: true,
+                            use_sdcard: false,
+                            grant_permissions: false
+
+        assert_requested(:post, "#{SESSION}/appium/device/install_app", times: 1)
+      end
+
       def test_remove_app
         stub_request(:post, "#{SESSION}/appium/device/remove_app")
           .to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
@@ -289,6 +311,16 @@ def test_remove_app
         assert_requested(:post, "#{SESSION}/appium/device/remove_app", times: 1)
       end
 
+      def test_remove_app_with_param
+        stub_request(:post, "#{SESSION}/appium/device/remove_app")
+          .with(body: { appId: 'com.app.id', options: { keepData: false, timeout: 20_000 } }.to_json)
+          .to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
+
+        @driver.remove_app 'com.app.id', keep_data: false, timeout: 20_000
+
+        assert_requested(:post, "#{SESSION}/appium/device/remove_app", times: 1)
+      end
+
       def test_terminate_app
         stub_request(:post, "#{SESSION}/appium/device/terminate_app")
           .to_return(headers: HEADER, status: 200, body: { value: true }.to_json)
@@ -298,6 +330,16 @@ def test_terminate_app
         assert_requested(:post, "#{SESSION}/appium/device/terminate_app", times: 1)
       end
 
+      def test_terminate_app_with_param
+        stub_request(:post, "#{SESSION}/appium/device/terminate_app")
+          .with(body: { appId: 'com.app.id', options: { timeout: 20_000 } }.to_json)
+          .to_return(headers: HEADER, status: 200, body: { value: true }.to_json)
+
+        @driver.terminate_app 'com.app.id', timeout: 20_000
+
+        assert_requested(:post, "#{SESSION}/appium/device/terminate_app", times: 1)
+      end
+
       def test_activate_app
         stub_request(:post, "#{SESSION}/appium/device/activate_app")
           .to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
@@ -308,12 +350,12 @@ def test_activate_app
       end
 
       def test_app_state
-        stub_request(:get, "#{SESSION}/appium/device/app_state")
+        stub_request(:post, "#{SESSION}/appium/device/app_state")
           .to_return(headers: HEADER, status: 200, body: { value: '' }.to_json)
 
         @driver.app_state 'com.app.id'
 
-        assert_requested(:get, "#{SESSION}/appium/device/app_state", times: 1)
+        assert_requested(:post, "#{SESSION}/appium/device/app_state", times: 1)
       end
 
       def test_app_installed?
diff --git a/test/unit/android/device_w3c_test.rb b/test/unit/android/device_w3c_test.rb
