ISSUE-576: Allow complex ADB server commands execution

adb-server/adb-server-command-types/src/main/java/com/kaspersky/adbserver/commandtypes/AdbCommand.kt

@@ -2,4 +2,7 @@ package com.kaspersky.adbserver.commandtypes
 
 import com.kaspersky.adbserver.common.api.Command
 
-data class AdbCommand(override val body: String) : Command(body)
+data class AdbCommand(
+    override val command: String,
+    override val arguments: List<String> = emptyList()
+) : Command(command, arguments)

adb-server/adb-server-command-types/src/main/java/com/kaspersky/adbserver/commandtypes/CmdCommand.kt

@@ -2,4 +2,7 @@ package com.kaspersky.adbserver.commandtypes
 
 import com.kaspersky.adbserver.common.api.Command
 
-data class CmdCommand(override val body: String) : Command(body)
+data class CmdCommand(
+    override val command: String,
+    override val arguments: List<String> = emptyList()
+) : Command(command, arguments)

adb-server/adb-server-common/src/main/java/com/kaspersky/adbserver/common/api/Command.kt

@@ -5,4 +5,4 @@ import java.io.Serializable
 /**
  * Command to execute by AdbServer
  */
-abstract class Command(open val body: String) : Serializable
+abstract class Command(open val command: String, open val arguments: List<String> = emptyList()) : Serializable

adb-server/adb-server-device/src/main/java/com/kaspersky/adbserver/device/AdbTerminal.kt

@@ -1,8 +1,8 @@
 package com.kaspersky.adbserver.device
 
-import com.kaspersky.adbserver.common.api.CommandResult
 import com.kaspersky.adbserver.commandtypes.AdbCommand
 import com.kaspersky.adbserver.commandtypes.CmdCommand
+import com.kaspersky.adbserver.common.api.CommandResult
 import com.kaspersky.adbserver.common.log.LoggerFactory
 import com.kaspersky.adbserver.common.log.logger.LogLevel
 import com.kaspersky.adbserver.common.log.logger.Logger
@@ -27,10 +27,32 @@ object AdbTerminal {
         AdbCommand(command)
     ) ?: throw IllegalStateException("Please first of all call [connect] method to establish a connection")
 
+    /**
+     * Allows more control over how arguments are parsed. Each element in the [arguments] list
+     * is used as is without tokenizing.
+     * Refer to the https://docs.oracle.com/javase/7/docs/api/java/lang/Runtime.html#exec(java.lang.String[])
+     *
+     * Please first of all call [connect] method to establish a connection
+     */
+    fun executeAdb(command: String, arguments: List<String>): CommandResult = device?.fulfill(
+        AdbCommand(command, arguments)
+    ) ?: throw IllegalStateException("Please first of all call [connect] method to establish a connection")
+
     /**
      * Please first of all call [connect] method to establish a connection
      */
     fun executeCmd(command: String): CommandResult = device?.fulfill(
         CmdCommand(command)
     ) ?: throw IllegalStateException("Please first of all call [connect] method to establish a connection")
+
+    /**
+     * Allows more control over how arguments are parsed. Each element in the [arguments] list
+     * is used as is without tokenizing.
+     * Refer to the https://docs.oracle.com/javase/7/docs/api/java/lang/Runtime.html#exec(java.lang.String[])
+     *
+     * Please first of all call [connect] method to establish a connection
+     */
+    fun executeCmd(command: String, arguments: List<String>): CommandResult = device?.fulfill(
+        CmdCommand(command, arguments)
+    ) ?: throw IllegalStateException("Please first of all call [connect] method to establish a connection")
 }

adb-server/adbserver-desktop/src/main/java/com/kaspersky/adbserver/desktop/CmdCommandPerformer.kt

@@ -2,10 +2,13 @@ package com.kaspersky.adbserver.desktop
 
 import com.kaspersky.adbserver.common.api.CommandResult
 import com.kaspersky.adbserver.common.api.ExecutorResultStatus
+import com.kaspersky.adbserver.common.log.logger.Logger
+import java.util.Arrays
 import java.util.concurrent.TimeUnit
 
 internal class CmdCommandPerformer(
-    private val desktopName: String
+    private val desktopName: String,
+    private val logger: Logger,
 ) {
 
     companion object {
@@ -15,9 +18,24 @@ internal class CmdCommandPerformer(
     /**
      * Be aware it's a synchronous method
      */
-    fun perform(command: String): CommandResult {
+    fun perform(command: String, arguments: List<String> = emptyList()): CommandResult {
         val serviceInfo = "The command was executed on desktop=$desktopName"
-        val process = Runtime.getRuntime().exec(command)
+
+        val process = try {
+            if (arguments.isEmpty()) {
+                Runtime.getRuntime().exec(command)
+            } else {
+                val fullCommand = buildList {
+                    add(command)
+                    addAll(arguments)
+                }.toTypedArray()
+                Runtime.getRuntime().exec(fullCommand)
+            }
+        } catch (ex: Throwable) {
+            logger.e(ex.stackTraceToString())
+            return CommandResult(ExecutorResultStatus.FAILURE, "failed to start process. See exception in AdbServer logs")
+        }
+
         try {
             if (process.waitFor(EXECUTION_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
                 val exitCode = process.exitValue()
@@ -43,7 +61,7 @@ internal class CmdCommandPerformer(
                 serviceInfo = serviceInfo
             )
         } finally {
-            process.destroy()
+            process?.destroy()
         }
     }
 }

adb-server/adbserver-desktop/src/main/java/com/kaspersky/adbserver/desktop/CommandExecutorImpl.kt

@@ -18,12 +18,32 @@ internal class CommandExecutorImpl(
 
     override fun execute(command: Command): CommandResult {
         return when (command) {
-            is CmdCommand -> cmdCommandPerformer.perform(command.body)
+            is CmdCommand -> cmdCommandPerformer.perform(command.command, command.arguments)
+
             is AdbCommand -> {
-                val adbCommand = "$adbPath ${ adbServerPort?.let { "-P $adbServerPort " } ?: "" }-s $deviceName ${command.body}"
-                logger.d("The created adbCommand=$adbCommand")
-                cmdCommandPerformer.perform(adbCommand)
+                val adbCommand: String
+                val adbArguments: List<String>
+
+                if (command.arguments.isEmpty()) {
+                    adbCommand = "$adbPath ${adbServerPort?.let { "-P $adbServerPort " } ?: ""}-s $deviceName ${command.command}"
+                    adbArguments = emptyList()
+                } else {
+                    adbCommand = adbPath
+                    adbArguments = buildList {
+                        adbServerPort?.let {
+                            add("-P")
+                            add(adbServerPort)
+                        }
+                        add("-s")
+                        add(deviceName)
+                        add(command.command)
+                        addAll(command.arguments)
+                    }
+                }
+                logger.d("The created adbCommand=$adbCommand, arguments=$adbArguments")
+                cmdCommandPerformer.perform(adbCommand, adbArguments)
             }
+
             else -> throw UnsupportedOperationException("The command=$command is unsupported command")
         }
     }

adb-server/adbserver-desktop/src/main/java/com/kaspersky/adbserver/desktop/Main.kt

@@ -50,7 +50,7 @@ internal fun main(args: Array<String>) {
 
     desktopLogger.i("Desktop started with arguments: emulators=$emulators, adbServerPort=$port, adbPath=$adbPath")
 
-    val cmdCommandPerformer = CmdCommandPerformer(desktopName)
+    val cmdCommandPerformer = CmdCommandPerformer(desktopName, desktopLogger)
     val desktop = Desktop(
         cmdCommandPerformer = cmdCommandPerformer,
         presetEmulators = emulators,

docs/Wiki/Executing_adb_commands.en.md

@@ -32,6 +32,10 @@ You can notice that the app uses `AdbTerminal` class to execute ADB commands.
 ## Usage in Kaspresso
 In Kaspresso, we wrap `AdbTerminal` into a special interface `AdbServer`.
 `AdbServer`'s instance is available in `BaseTestContext` scope and `BaseTestCase` with `adbServer` property: <br>
+There're two types of AbdServer methods signatures: 
+
+`fun perform(vararg commands: String): List<String>` and `perform(command: String, arguments: List<String>): String` with an important difference.
+First signature accept one or more commands and execute them one by one. Example below:
 ```kotlin
 @Test
 fun test() =
@@ -50,6 +54,23 @@ fun test() =
         // ....
 }
 ```
+This method passes each command to the java runtime which tokenizes it by whitespaces. It could be not ideal. It can't be used for the commands with
+the whitespaces in their arguments (e.g. `adb pull "/sdcard/Documents/path_with whitespace to/file.txt"`) and it doesn't allow piping (e.g. `cat $BUILD_DIR/report.txt | grep filte > filtered.txt`).
+That's why there's a second AdbServer methods signature type.
+
+It executes a single command and allows you to pass a list of arguments. It doesn't tokenize your command or arguments, they are used "as is".
+This allows you to use piping and complex arguments
+See example below (yes, a command could be an argument for another command):
+```kotlin
+@Test
+fun test() = before{
+      adbServer.performCmd("bash", listOf("-c", "adb shell dumpsys deviceidle | grep mForceIdle"))
+   }.after {
+   }.run {
+       // ...
+   }
+```
+
 Also, don't forget to grant necessary permission:
 ```
 <uses-permission android:name="android.permission.INTERNET" />

docs/Wiki/Executing_adb_commands.ru.md

@@ -32,6 +32,10 @@
 ## Использование в Kaspresso
 В Kaspresso мы оборачиваем AdbTerminal в специальный интерфейс AdbServer.
 Экземпляр `AdbServer` доступен в области `BaseTestContext` и `BaseTestCase` со свойством `adbServer`: <br>
+У AdbServer два типа сигнатур методов:
+
+`fun perform(vararg commands: String): List<String>` и `perform(command: String, arguments: List<String>): String` с важными различиями между ними.
+Первая сигнатура принимает одну или более комманду и исполняет их одну за одной. Пример далее:
 ```kotlin
 @Test
 fun test() =
@@ -50,6 +54,23 @@ fun test() =
         // ....
 }
 ```
+Этот метод передает каждую команду среде выполнения java, которая разбивает ее по пробелам. Это может быть не самым лучшим вариантом. Он не может использоваться для команд с
+пробелами в их аргументах (например, `adb pull "/sdcard/Documents/path_with whitespace to/file.txt"`) и не допускает пайпинга комманд (например, `cat $BUILD_DIR/report.txt | grep filte > filtered.txt`).
+Вот почему существует второй тип сигнатур методов AdbServer.
+
+Он выполняет одну команду и позволяет вам передавать список аргументов. Он не разбивает вашу команду или аргументы, они используются в том виде, в 
+котором вы их передали. Это позволяет вам использовать пайпинг и сложные аргументы.
+Смотрите пример ниже (да, команда может быть аргументом для другой команды):
+```kotlin
+@Test
+fun test() = before{
+      adbServer.performCmd("bash", listOf("-c", "adb shell dumpsys deviceidle | grep mForceIdle"))
+   }.after {
+   }.run {
+       // ...
+   }
+```
+
 Также не забудьте предоставить необходимое разрешение:
 ```
 <uses-permission android:name="android.permission.INTERNET" />

kaspresso/src/main/kotlin/com/kaspersky/kaspresso/device/server/AdbServer.kt

@@ -1,5 +1,7 @@
 package com.kaspersky.kaspresso.device.server
 
+import android.annotation.SuppressLint
+
 /**
  * This is a comfortable wrapper to work with AdbServer repository.
  *
@@ -20,36 +22,108 @@ interface AdbServer {
      *
      * Required Permissions: INTERNET.
      *
+     * @see <a href="https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md">AdbServer documentation</a>
      * @param commands commands to execute.
      * @throws AdbServerException if a result status of any command in @param commands is Failed
      * @return list of answers of commands' execution
      */
+    @SuppressLint("SdCardPath")
+    @Deprecated("This method doesn't work for the commands with the complex arguments containing " +
+            "whitespaces (e.g. 'adb pull \"/sdcard/Documents/path_with whitespace to/file.txt\") and doesn't allow commands piping like" +
+            "adbServer.performCmd(\"bash\", listOf(\"-c\", \"adb shell dumpsys deviceidle | grep mForceIdle\"))" +
+            "which the AdbServer.performCmd(String, List<String>) does. " +
+            "For more details, please check out https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md",
+        ReplaceWith("adbServer.performCmd(*commands, emptyList())")
+    )
     fun performCmd(vararg commands: String): List<String>
 
+    /**
+     * Performs shell commands blocking current thread. Allows more control over how arguments are parsed.
+     * Each list element is used as is. Refer to the https://docs.oracle.com/javase/8/docs/api/java/lang/ProcessBuilder.html.
+     *
+     * Please be aware! If any command that is in @param commands failed then AdbServerException will be thrown
+     *
+     * Required Permissions: INTERNET.
+     *
+     * @see <a href="https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md">AdbServer documentation</a>
+     * @param commands commands to execute.
+     * @throws AdbServerException if a result status of any command in @param commands is Failed
+     * @return list of answers of commands' execution
+     */
+    fun performCmd(command: String, arguments: List<String>): String
+
     /**
      * Performs adb commands blocking current thread.
      * Please be aware! If any command that is in @param commands failed then AdbServerException will be thrown
      *
      * Required Permissions: INTERNET.
      *
+     * @see <a href="https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md">AdbServer documentation</a>
      * @param commands commands to execute.
      * @throws AdbServerException if a result status of any command in @param commands is Failed
      * @return list of answers of commands' execution
      */
+    @SuppressLint("SdCardPath")
+    @Deprecated("This method doesn't work for the commands with the complex arguments containing " +
+            "whitespaces (e.g. 'adb pull \"/sdcard/Documents/path_with whitespace to/file.txt\") and doesn't allow commands piping like" +
+            "adbServer.performCmd(\"bash\", listOf(\"-c\", \"adb shell dumpsys deviceidle | grep mForceIdle\"))" +
+            "which the AdbServer.performAdb(String, List<String>) does " +
+            "For more details, please check out https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md",
+        ReplaceWith("adbServer.performAdb(*commands, emptyList())")
+    )
     fun performAdb(vararg commands: String): List<String>
 
+    /**
+     * Performs adb commands blocking current thread. Allows more control over how arguments are parsed.
+     * Each list element is used as is. Refer to the https://docs.oracle.com/javase/8/docs/api/java/lang/ProcessBuilder.html.
+     *
+     * Please be aware! If any command that is in @param commands failed then AdbServerException will be thrown
+     *
+     * Required Permissions: INTERNET.
+     *
+     * @see <a href="https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md">AdbServer documentation</a>
+     * @param commands commands to execute.
+     * @throws AdbServerException if a result status of any command in @param commands is Failed
+     * @return list of answers of commands' execution
+     */
+    fun performAdb(command: String, arguments: List<String>): String
+
     /**
      * Performs shell commands blocking current thread.
      * Please be aware! If any command that is in @param commands failed then AdbServerException will be thrown
      *
      * Required Permissions: INTERNET.
      *
+     * @see <a href="https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md">AdbServer documentation</a>
      * @param commands commands to execute.
      * @throws AdbServerException if a result status of any command in @param commands is Failed
      * @return list of answers of commands' execution
      */
+    @SuppressLint("SdCardPath")
+    @Deprecated("This method doesn't work for the commands with the complex arguments containing " +
+            "whitespaces (e.g. 'adb pull \"/sdcard/Documents/path_with whitespace to/file.txt\") and doesn't allow commands piping like" +
+            "adbServer.performCmd(\"bash\", listOf(\"-c\", \"adb shell dumpsys deviceidle | grep mForceIdle\"))" +
+            "which the AdbServer.performShell(String, List<String>) does " +
+            "For more details, please check out https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md",
+        ReplaceWith("adbServer.performShell(*commands, emptyList())")
+    )
     fun performShell(vararg commands: String): List<String>
 
+    /**
+     * Performs shell commands blocking current thread. Allows more control over how arguments are parsed.
+     * Each list element is used as is. Refer to the https://docs.oracle.com/javase/8/docs/api/java/lang/ProcessBuilder.html.
+     *
+     * Please be aware! If any command that is in @param commands failed then AdbServerException will be thrown
+     *
+     * Required Permissions: INTERNET.
+     *
+     * @see <a href="https://github.com/KasperskyLab/Kaspresso/blob/master/docs/Wiki/Executing_adb_commands.en.md">AdbServer documentation</a>
+     * @param commands commands to execute.
+     * @throws AdbServerException if a result status of any command in @param commands is Failed
+     * @return list of answers of commands' execution
+     */
+    fun performShell(command: String, arguments: List<String>): String
+
     /**
      * Disconnect from AdbServer.
      * The method is called by Kaspresso after each test.