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 Runtime::exec(String[] cmdarray)
+     *
+     * 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 Runtime::exec(String[] cmdarray)
+     *
+     * 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

@@ -15,9 +15,19 @@ 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 = if (arguments.isEmpty()) {
+            Runtime.getRuntime().exec(command)
+        } else {
+            val fullCommand = buildList {
+                add(command)
+                addAll(arguments)
+            }.toTypedArray()
+
+            Runtime.getRuntime().exec(fullCommand)
+        }
+
         try {
             if (process.waitFor(EXECUTION_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
                 val exitCode = process.exitValue()

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

@@ -18,12 +18,14 @@ 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 = "$adbPath ${adbServerPort?.let { "-P $adbServerPort " } ?: ""}-s $deviceName ${command.command}"
+                logger.d("The created adbCommand=$adbCommand, arguments=${command.arguments}")
+                cmdCommandPerformer.perform(adbCommand, command.arguments)
             }
+
             else -> throw UnsupportedOperationException("The command=$command is unsupported command")
         }
     }

docs/Wiki/Executing_adb_commands.en.md

@@ -190,6 +190,14 @@ Now the logs looks like:
 2020-09-10 12:24:27.427 10349-10378/com.kaspersky.kaspressample I/KASPRESSO_ADBSERVER: The result of command=AdbCommand(body=shell su 0 svc data disable) => CommandResult(status=SUCCESS, description=exitCode=0, message=, serviceInfo=The command was executed on desktop=Desktop-30548)
 ```
 
+## Complex commands
+There're two kinds of ADB server methods signatures: `preformCmd(vararg commands: String)` and `performsCmd(command: String, arguments: List<String>)`. The first executes multiple
+commands one by one. The latter allows you to gain more control over the commands parsing - ADB server would execute commands "as is" without trying to split command into tokens. This allows you to execute
+commands with whitespaces in their arguments and use piping. Example:
+```kotlin
+ adbServer.performCmd("bash", arguments = listOf("-c", "grep adb \"~/Documents/test file.txt\" > \"~/Documents/out file.txt\""))
+```
+
 ## Development
 The source code of AdbServer is available in [adb-server](https://github.com/KasperskyLab/Kaspresso/tree/master/adb-server) module. <br>
 If you want to build `adbserver-desktop.jar` manually, just execute `./gradlew :adb-server:adbserver-desktop:assemble`.

docs/Wiki/Executing_adb_commands.ru.md

@@ -189,6 +189,14 @@ class DeviceNetworkSampleTest: TestCase(
 2020-09-10 12:24:27.427 10349-10378/com.kaspersky.kaspressample I/KASPRESSO_ADBSERVER: The result of command=AdbCommand(body=shell su 0 svc data disable) => CommandResult(status=SUCCESS, description=exitCode=0, message=, serviceInfo=The command was executed on desktop=Desktop-30548)
 ```
 
+## Сложные команды
+Есть 2 типа сигнатур методов ADB server'а: `preformCmd(vararg commands: String)` и `performsCmd(command: String, arguments: List<String>)`. Первый выполняет несколько 
+команд одна за одной. Последний дает вам контроль над тем, как происходит парсинг комманды - ADB server выполнит их в таком виде, в каком вы их передали, не пытаясь разбить их на токены. Это позволяет
+выполнять команды с пробелами в аргументах и использовать пайпинг. Пример:
+```kotlin
+ adbServer.performCmd("bash", arguments = listOf("-c", "grep adb \"~/Documents/test file.txt\" > \"~/Documents/out file.txt\""))
+```
+
 ## Разработка
 Исходный код AdbServer доступен в модуле [adb-server](https://github.com/KasperskyLab/Kaspresso/ru/tree/master/adb-server). <br>
 Если вы хотите собрать `adbserver-desktop.jar` вручную, просто выполните `./gradlew :adb-server:adbserver-desktop:assemble`.

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

@@ -26,6 +26,20 @@ interface AdbServer {
      */
     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.
+     *
+     * @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
@@ -38,6 +52,20 @@ interface AdbServer {
      */
     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.
+     *
+     * @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
@@ -50,6 +78,20 @@ interface AdbServer {
      */
     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.
+     *
+     * @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.

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

@@ -30,58 +30,36 @@ class AdbServerImpl(
             return AdbTerminal
         }
 
-    /**
-     * Executes 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.
-     *
-     * @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
-     */
     override fun performCmd(vararg commands: String): List<String> {
         return perform(commands) {
             adbTerminal.executeCmd(it)
         }
     }
 
-    /**
-     * 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.
-     *
-     * @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
-     */
     override fun performAdb(vararg commands: String): List<String> {
         return perform(commands) {
             adbTerminal.executeAdb(it)
         }
     }
 
-    /**
-     * 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.
-     *
-     * @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
-     */
     override fun performShell(vararg commands: String): List<String> {
         return perform(commands) {
             adbTerminal.executeAdb("shell $it")
         }
     }
 
-    /**
-     * Disconnect from AdbServer.
-     * The method is called by Kaspresso after each test.
-     */
+    override fun performCmd(command: String, arguments: List<String>): String {
+        return performComplex(command, arguments, adbTerminal::executeCmd)
+    }
+
+    override fun performAdb(command: String, arguments: List<String>): String {
+        return performComplex(command, arguments, adbTerminal::executeAdb)
+    }
+
+    override fun performShell(command: String, arguments: List<String>): String {
+        return performComplex("shell $command", arguments, adbTerminal::executeAdb)
+    }
+
     override fun disconnectServer() {
         if (connected) {
             adbTerminal.disconnect()
@@ -95,16 +73,27 @@ class AdbServerImpl(
                 logger.i("AdbServer. The command to execute=$command")
             }
             .map { command -> command to executor.invoke(command) }
-            .onEach { (command, result) ->
-                logger.i("AdbServer. The command=$command was performed with result=$result")
-            }
-            .onEach { (command, result) ->
-                if (result.status == ExecutorResultStatus.FAILURE) {
-                    throw AdbServerException("AdbServer. The command=$command was performed with failed result=$result")
-                }
-                if (result.status == ExecutorResultStatus.TIMEOUT) {
-                    throw AdbServerException(
-                        """
+            .onEach { (command, result) -> logCommandResult(command, result) }
+            .map { (_, result) -> result.description }
+            .toList()
+    }
+
+    private fun performComplex(command: String, arguments: List<String>, executor: (String, List<String>) -> CommandResult): String {
+        logger.i("AdbServer. The complex command to execute=$command")
+        val result = executor.invoke(command, arguments)
+        logCommandResult(command, result)
+
+        return result.description
+    }
+
+    private fun logCommandResult(command: String, result: CommandResult, arguments: List<String> = emptyList()) {
+        logger.i("AdbServer. The command=$command with arguments=$arguments was performed with result=$result")
+        if (result.status == ExecutorResultStatus.FAILURE) {
+            throw AdbServerException("AdbServer. The command=$command was performed with failed result=$result")
+        }
+        if (result.status == ExecutorResultStatus.TIMEOUT) {
+            throw AdbServerException(
+                """
 
                             AdbServer. The command=$command was performed with timeout exception.
                             There are two possible reasons:
@@ -122,10 +111,7 @@ class AdbServerImpl(
                                 c. Start 'adbserver-desktop.jar' with the command in Terminal - 'java -jar /Users/yuri.gagarin/Desktop/adbserver-desktop.jar
 
                         """.trimIndent()
-                    )
-                }
-            }
-            .map { (_, result) -> result.description }
-            .toList()
+            )
+        }
     }
 }