feat: add InstallApp method for Android and iOS (#974)

Dor-bl · web-flow · commit 5657846aa3b6 · 2025-11-25T20:57:03.000+01:00
* feat: add InstallApp method for Android and iOS, including tests for installation scenarios

* fix: improve error handling in Dispose method of InstallAppTest

* fix: remove unused AppiumOptions instantiation in InstallAppTest

* fix: correct typo in region name from 'Device Kesys' to 'Device Keys'

* fix: update documentation link for mobile: installApp in AndroidCommandExecutionHelper
diff --git a/src/Appium.Net/Appium/Android/AndroidCommandExecutionHelper.cs b/src/Appium.Net/Appium/Android/AndroidCommandExecutionHelper.cs
@@ -172,6 +172,50 @@ public static float GetDisplayDensity(IExecuteMethod executeMethod)
 
         #endregion
 
+        /// <summary>
+        /// Install an app on the Android device using mobile: installApp script.
+        /// For documentation, see <see href="https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#mobile-installapp">mobile: installApp</see>.
+        /// </summary>
+        /// <param name="executeMethod">The execute method</param>
+        /// <param name="appPath">Full path to the .apk on the local filesystem or a remote URL.</param>
+        /// <param name="timeout">Optional timeout in milliseconds to wait for the app installation to complete. 60000ms by default.</param>
+        /// <param name="allowTestPackages">Optional flag to allow test packages installation. false by default.</param>
+        /// <param name="useSdcard">Optional flag to install the app on sdcard instead of device memory. false by default.</param>
+        /// <param name="grantPermissions">Optional flag to grant all permissions requested in the app manifest automatically after installation. false by default.</param>
+        /// <param name="replace">Optional flag to upgrade/reinstall if app is already present. true by default.</param>
+        /// <param name="checkVersion">Optional flag to skip installation if device has equal or greater app version. false by default.</param>
+        public static void InstallApp(
+            IExecuteMethod executeMethod, 
+            string appPath, 
+            int? timeout = null, 
+            bool? allowTestPackages = null, 
+            bool? useSdcard = null, 
+            bool? grantPermissions = null, 
+            bool? replace = null, 
+            bool? checkVersion = null)
+        {
+            var args = new Dictionary<string, object> { { "appPath", appPath } };
+            
+            if (timeout.HasValue)
+                args["timeout"] = timeout.Value;
+            if (allowTestPackages.HasValue)
+                args["allowTestPackages"] = allowTestPackages.Value;
+            if (useSdcard.HasValue)
+                args["useSdcard"] = useSdcard.Value;
+            if (grantPermissions.HasValue)
+                args["grantPermissions"] = grantPermissions.Value;
+            if (replace.HasValue)
+                args["replace"] = replace.Value;
+            if (checkVersion.HasValue)
+                args["checkVersion"] = checkVersion.Value;
+
+            executeMethod.Execute(DriverCommand.ExecuteScript, new Dictionary<string, object>
+            {
+                ["script"] = "mobile: installApp",
+                ["args"] = new object[] { args }
+            });
+        }
+
         public static Dictionary<string, object> GetSettings(IExecuteMethod executeMethod) =>
             (Dictionary<string, object>) executeMethod.Execute(AppiumDriverCommand.GetSettings).Value;
 
diff --git a/src/Appium.Net/Appium/Android/AndroidDriver.cs b/src/Appium.Net/Appium/Android/AndroidDriver.cs
@@ -182,7 +182,32 @@ public AndroidDriver(AppiumLocalService service, DriverOptions driverOptions, Ti
 
         public string CurrentPackage => AndroidCommandExecutionHelper.GetCurrentPackage(this);
 
-        #region Device Kesys
+        #region App Management
+
+        /// <summary>
+        /// Install an app on the Android device using mobile: installApp script.
+        /// For documentation, see <see href="https://github.com/appium/appium-uiautomator2-driver?tab=readme-ov-file#mobile-installapp">mobile: installApp</see>.
+        /// </summary>
+        /// <param name="appPath">Full path to the .apk on the local filesystem or a remote URL.</param>
+        /// <param name="timeout">Optional timeout in milliseconds to wait for the app installation to complete. 60000ms by default.</param>
+        /// <param name="allowTestPackages">Optional flag to allow test packages installation. false by default.</param>
+        /// <param name="useSdcard">Optional flag to install the app on sdcard instead of device memory. false by default.</param>
+        /// <param name="grantPermissions">Optional flag to grant all permissions requested in the app manifest automatically after installation. false by default.</param>
+        /// <param name="replace">Optional flag to upgrade/reinstall if app is already present. true by default.</param>
+        /// <param name="checkVersion">Optional flag to skip installation if device has equal or greater app version. false by default.</param>
+        public void InstallApp(
+            string appPath, 
+            int? timeout = null, 
+            bool? allowTestPackages = null, 
+            bool? useSdcard = null, 
+            bool? grantPermissions = null, 
+            bool? replace = null, 
+            bool? checkVersion = null) =>
+            AndroidCommandExecutionHelper.InstallApp(this, appPath, timeout, allowTestPackages, useSdcard, grantPermissions, replace, checkVersion);
+
+        #endregion
+
+        #region Device Keys
 
         public void PressKeyCode(int keyCode, int metastate = -1) =>
             AppiumCommandExecutionHelper.PressKeyCode(this, keyCode, metastate);
diff --git a/src/Appium.Net/Appium/iOS/IOSCommandExecutionHelper.cs b/src/Appium.Net/Appium/iOS/IOSCommandExecutionHelper.cs
@@ -94,6 +94,30 @@ public static Image GetClipboardImage(IExecuteMethod executeMethod)
             return null;
         }
 
+        /// <summary>
+        /// Install an app on the iOS device using mobile: installApp script.
+        /// For documentation, see <see href="https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/#mobile-installapp">mobile: installApp</see>.
+        /// </summary>
+        /// <param name="executeMethod">The execute method</param>
+        /// <param name="appPath">Full path to the .ipa on the local filesystem or a remote URL.</param>
+        /// <param name="timeoutMs">Optional timeout in milliseconds to wait for the app installation to complete.</param>
+        public static void InstallApp(
+            IExecuteMethod executeMethod, 
+            string appPath, 
+            int? timeoutMs = null)
+        {
+            var args = new Dictionary<string, object> { { "appPath", appPath } };
+            
+            if (timeoutMs.HasValue)
+                args["timeoutMs"] = timeoutMs.Value;
+
+            executeMethod.Execute(DriverCommand.ExecuteScript, new Dictionary<string, object>
+            {
+                ["script"] = "mobile: installApp",
+                ["args"] = new object[] { args }
+            });
+        }
+
         public static Dictionary<string, object> GetSettings(IExecuteMethod executeMethod) =>
             (Dictionary<string, object>)executeMethod.Execute(AppiumDriverCommand.GetSettings).Value;
 
diff --git a/src/Appium.Net/Appium/iOS/IOSDriver.cs b/src/Appium.Net/Appium/iOS/IOSDriver.cs
@@ -200,6 +200,19 @@ public Dictionary<string, object> Settings
         /// <param name="match">Whether to simulate biometric match.</param>
         public void PerformTouchID(bool match) => IOSCommandExecutionHelper.PerformTouchID(this, match);
 
+        #region App Management
+
+        /// <summary>
+        /// Install an app on the iOS device using mobile: installApp script.
+        /// For documentation, see <see href="https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/#mobile-installapp">mobile: installApp</see>.
+        /// </summary>
+        /// <param name="appPath">Full path to the .ipa on the local filesystem or a remote URL.</param>
+        /// <param name="timeoutMs">Optional timeout in milliseconds to wait for the app installation to complete.</param>
+        public void InstallApp(string appPath, int? timeoutMs = null) =>
+            IOSCommandExecutionHelper.InstallApp(this, appPath, timeoutMs);
+
+        #endregion
+
         /// <summary>
         /// Check if the device is locked
         /// </summary>
diff --git a/test/integration/Android/App/InstallAppTest.cs b/test/integration/Android/App/InstallAppTest.cs
@@ -0,0 +1,81 @@
+using System;
+using Appium.Net.Integration.Tests.helpers;
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium;
+using OpenQA.Selenium.Appium.Android;
+using NUnit.Framework;
+
+namespace Appium.Net.Integration.Tests.Android.App
+{
+    public class InstallAppTest : IDisposable
+    {
+        private readonly AndroidDriver _driver;
+        private readonly string _apkPath;
+        private readonly string _packageName;
+
+        public InstallAppTest()
+        {
+            _apkPath = Apps.Get(Apps.androidApiDemos);
+            _packageName = Apps.GetId(Apps.androidApiDemos);
+            var serverUri = Env.ServerIsRemote() ? AppiumServers.RemoteServerUri : AppiumServers.LocalServiceUri;
+            AppiumOptions opts = Caps.GetAndroidUIAutomatorCaps();
+            // Do not preinstall the app via capabilities; we test explicit installation.
+            _driver = new AndroidDriver(serverUri, opts, TimeSpan.FromMinutes(2));
+        }
+
+        [Test]
+        public void MobileInstallApp_InstallsPackage()
+        {
+            _driver.InstallApp(_apkPath);
+            Assert.That(_driver.IsAppInstalled(_packageName), Is.True);
+        }
+
+        [Test]
+        public void MobileInstallApp_IsIdempotent()
+        {
+            _driver.InstallApp(_apkPath);
+            _driver.InstallApp(_apkPath); // second time should not fail
+            Assert.That(_driver.IsAppInstalled(_packageName), Is.True);
+        }
+
+
+        [Test]
+        public void MobileInstallApp_InvalidPath_Throws()
+        {
+            var badPath = "/nonexistent/path/app.apk";
+            var ex = Assert.Throws<UnknownErrorException>(() => _driver.InstallApp(badPath));
+            Assert.That(ex.Message, Does.Contain("does not exist").IgnoreCase);
+        }
+
+        [Test]
+        public void MobileInstallApp_WithTimeout_InstallsPackage()
+        {
+            _driver.InstallApp(_apkPath, timeout: 60000);
+            Assert.That(_driver.IsAppInstalled(_packageName), Is.True);
+        }
+
+        [Test]
+        public void MobileInstallApp_WithCheckVersion_InstallsPackage()
+        {
+            _driver.InstallApp(_apkPath, checkVersion: true);
+            Assert.That(_driver.IsAppInstalled(_packageName), Is.True);
+        }
+
+        public void Dispose()
+        {
+            GC.SuppressFinalize(this);
+            try
+            {
+                if (!string.IsNullOrWhiteSpace(_packageName) && _driver.IsAppInstalled(_packageName))
+                {
+                    _driver.RemoveApp(_packageName);
+                }
+            }
+            catch (Exception ex) 
+            { 
+                Console.Error.WriteLine($"Exception during Dispose: {ex}");
+            }
+            _driver?.Quit();
+        }
+    }
+}
