Add rotate simulator feature for iOS

CONTRIBUTING.md

@@ -34,7 +34,7 @@ users still use Java 8.
 
 For development, you need to use Java 11 or newer.
 
-If you made changes to the CLI, rebuilt it with `./gradlew :maestro-cli:installDist`. This will generate a startup shell
+If you made changes to the CLI, rebuild it with `./gradlew :maestro-cli:installDist`. This will generate a startup shell
 script in `./maestro-cli/build/install/maestro/bin/maestro`. Use it instead of globally installed `maestro`.
 
 If you made changes to the iOS XCTest runner app, make sure they are compatible with the version of Xcode used by the GitHub Actions build step. It is currently built using the default version of Xcode listed in the macos runner image [readme][macos_builder_readme].

maestro-client/src/main/java/maestro/Driver.kt

@@ -104,4 +104,6 @@ interface Driver {
     fun setAirplaneMode(enabled: Boolean)
 
     fun setAndroidChromeDevToolsEnabled(enabled: Boolean) = Unit
+
+    fun rotateDevice(direction: String)
 }

maestro-client/src/main/java/maestro/Maestro.kt

@@ -617,6 +617,10 @@ class Maestro(
         driver.setAndroidChromeDevToolsEnabled(enabled)
     }
 
+    fun rotateDevice(direction: String) {
+        driver.rotateDevice(direction)
+    }
+
     companion object {
 
         private val LOGGER = LoggerFactory.getLogger(Maestro::class.java)

maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt

@@ -844,6 +844,11 @@ class AndroidDriver(
         }
     }
 
+    override fun rotateDevice(direction: String) {
+        // This command is only needed to rotate an iOS simulator and has no effect here
+        return
+    }
+
     override fun setAndroidChromeDevToolsEnabled(enabled: Boolean) {
         this.chromeDevToolsEnabled = enabled
     }

maestro-client/src/main/java/maestro/drivers/IOSDriver.kt

@@ -503,6 +503,14 @@ class IOSDriver(
         LOGGER.warn("Airplane mode is not available on iOS simulators")
     }
 
+    override fun rotateDevice(direction: String) {
+        metrics.measured("operation", mapOf("command" to "rotateDevice", "appId" to appId)) {
+            runDeviceCall("rotateDevice") {
+                iosDevice.rotateDevice(direction)
+            }
+        }
+    }
+
     private fun addMediaToDevice(mediaFile: File) {
         metrics.measured("operation", mapOf("command" to "addMediaToDevice")) {
             val namedSource = NamedSource(

maestro-client/src/main/java/maestro/drivers/WebDriver.kt

@@ -474,6 +474,10 @@ class WebDriver(
         // Do nothing
     }
 
+    override fun rotateDevice(direction: String) {
+        // Do nothing
+    }
+
     companion object {
         private const val SCREENSHOT_DIFF_THRESHOLD = 0.005
         private const val RETRY_FETCHING_CONTENT_DESCRIPTION = 10

maestro-ios-driver/src/main/kotlin/util/LocalSimulatorUtils.kt

@@ -693,4 +693,16 @@ object LocalSimulatorUtils {
         screenRecording.process.waitFor()
         return screenRecording.file
     }
+
+    fun rotateDevice(direction: String) {
+        runCommand(
+            listOf(
+                "osascript",
+                "-e",
+                "tell application \"Simulator\" to activate",
+                "-e",
+                "tell application \"System Events\" to click menu item \"Rotate ${direction}\" of menu 1 of menu bar item \"Device\" of menu bar 1 of application process \"Simulator\""
+            )
+        )
+    }
 }

maestro-ios/src/main/java/ios/IOSDevice.kt

@@ -150,6 +150,8 @@ interface IOSDevice : AutoCloseable {
     fun eraseText(charactersToErase: Int)
 
     fun addMedia(path: String)
+
+    fun rotateDevice(direction: String)
 }
 
 interface IOSScreenRecording : AutoCloseable

maestro-ios/src/main/java/ios/LocalIOSDevice.kt

@@ -157,4 +157,8 @@ class LocalIOSDevice(
     override fun addMedia(path: String) {
         simctlIOSDevice.addMedia(path)
     }
+
+    override fun rotateDevice(direction: String) {
+        simctlIOSDevice.rotateDevice(direction)
+    }
 }

maestro-ios/src/main/java/ios/simctl/SimctlIOSDevice.kt

@@ -189,4 +189,8 @@ class SimctlIOSDevice(
         stopScreenRecording()
     }
 
+    override fun rotateDevice(direction: String) {
+        LocalSimulatorUtils.rotateDevice(direction)
+    }
+
 }

maestro-ios/src/main/java/ios/xctest/XCTestIOSDevice.kt

@@ -11,6 +11,7 @@ import maestro.utils.network.XCUITestServerError
 import okio.Sink
 import okio.buffer
 import org.slf4j.LoggerFactory
+import util.LocalSimulatorUtils
 import xcuitest.XCTestDriverClient
 import java.io.InputStream
 import java.net.SocketTimeoutException
@@ -218,6 +219,10 @@ class XCTestIOSDevice(
         execute { client.eraseText(charactersToErase, appIds = emptySet()) }
     }
 
+    override fun rotateDevice(direction: String) {
+        LocalSimulatorUtils.rotateDevice(direction)
+    }
+
     private fun activeAppId(): String {
         return execute {
             val appIds = getInstalledApps()

maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt

@@ -869,6 +869,22 @@ data class RetryCommand(
 
 }
 
+data class RotateDeviceCommand(
+    val direction: String? = null,
+    override val label: String? = null,
+    override val optional: Boolean,
+) : Command {
+
+    override fun description(): String {
+        return label ?: "Rotate device"
+    }
+
+    override fun evaluateScripts(jsEngine: JsEngine): Command {
+        return this
+    }
+
+}
+
 data class DefineVariablesCommand(
     val env: Map<String, String>,
     override val label: String? = null,

maestro-orchestra-models/src/main/java/maestro/orchestra/MaestroCommand.kt

@@ -69,6 +69,7 @@ data class MaestroCommand(
     val setAirplaneModeCommand: SetAirplaneModeCommand? = null,
     val toggleAirplaneModeCommand: ToggleAirplaneModeCommand? = null,
     val retryCommand: RetryCommand? = null,
+    val rotateDeviceCommand: RotateDeviceCommand? = null,
 ) {
 
     constructor(command: Command) : this(
@@ -112,7 +113,8 @@ data class MaestroCommand(
         addMediaCommand = command as? AddMediaCommand,
         setAirplaneModeCommand = command as? SetAirplaneModeCommand,
         toggleAirplaneModeCommand = command as? ToggleAirplaneModeCommand,
-        retryCommand = command as? RetryCommand
+        retryCommand = command as? RetryCommand,
+        rotateDeviceCommand = command as? RotateDeviceCommand
     )
 
     fun asCommand(): Command? = when {
@@ -157,6 +159,7 @@ data class MaestroCommand(
         setAirplaneModeCommand != null -> setAirplaneModeCommand
         toggleAirplaneModeCommand != null -> toggleAirplaneModeCommand
         retryCommand != null -> retryCommand
+        rotateDeviceCommand != null -> rotateDeviceCommand
         else -> null
     }
 

maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt

@@ -320,6 +320,7 @@ class Orchestra(
             is SetAirplaneModeCommand -> setAirplaneMode(command)
             is ToggleAirplaneModeCommand -> toggleAirplaneMode()
             is RetryCommand -> retryCommand(command, config)
+            is RotateDeviceCommand -> rotateDevice(command)
             else -> true
         }.also { mutating ->
             if (mutating) {
@@ -1254,6 +1255,12 @@ class Orchestra(
         }
     }
 
+    private fun rotateDevice(command: RotateDeviceCommand): Boolean {
+        maestro.rotateDevice(command.direction ?: "Right")
+
+        return true
+    }
+
     private fun pasteText(): Boolean {
         copiedText?.let { maestro.inputText(it) }
         return true

maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt

@@ -142,6 +142,10 @@ private val stringCommands = mapOf<String, (JsonLocation) -> YamlFluentCommand>(
         _location = location,
         assertNoDefectsWithAI = YamlAssertNoDefectsWithAI()
     )},
+    "rotateDevice" to { location -> YamlFluentCommand(
+        _location = location,
+        rotateDevice = YamlRotateDevice(direction = "Right")
+    )}
 )
 
 private val allCommands = (stringCommands.keys + objectCommands).distinct()

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlFluentCommand.kt

@@ -51,6 +51,7 @@ import maestro.orchestra.PasteTextCommand
 import maestro.orchestra.PressKeyCommand
 import maestro.orchestra.RepeatCommand
 import maestro.orchestra.RetryCommand
+import maestro.orchestra.RotateDeviceCommand
 import maestro.orchestra.RunFlowCommand
 import maestro.orchestra.RunScriptCommand
 import maestro.orchestra.ScrollCommand
@@ -129,6 +130,7 @@ data class YamlFluentCommand(
     val setAirplaneMode: YamlSetAirplaneMode? = null,
     val toggleAirplaneMode: YamlToggleAirplaneMode? = null,
     val retry: YamlRetryCommand? = null,
+    val rotateDevice: YamlRotateDevice? = null,
     @JsonIgnore val _location: JsonLocation,
 ) {
 
@@ -478,6 +480,16 @@ data class YamlFluentCommand(
                 )
             )
 
+            rotateDevice != null -> listOf(
+                MaestroCommand(
+                    RotateDeviceCommand(
+                        rotateDevice.direction,
+                        rotateDevice.label,
+                        rotateDevice.optional
+                    )
+                )
+            )
+
             else -> throw SyntaxError("Invalid command: No mapping provided for $this")
         }
     }

maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlRotateDevice.kt

@@ -0,0 +1,21 @@
+package maestro.orchestra.yaml
+
+import com.fasterxml.jackson.annotation.JsonCreator
+
+data class YamlRotateDevice(
+    val direction: String? = null,
+    val label: String? = null,
+    val optional: Boolean = false,
+) {
+    companion object {
+        @JvmStatic
+        @JsonCreator(mode = JsonCreator.Mode.DELEGATING)
+        fun parse(rotateDirection: String?) = YamlRotateDevice(
+            direction = when (rotateDirection?.lowercase()) {
+                "left" -> "Left"
+                "right" -> "Right"
+                else -> "Right"
+            }
+        )
+    }
+}

maestro-test/src/main/kotlin/maestro/test/drivers/FakeDriver.kt

@@ -391,6 +391,10 @@ class FakeDriver : Driver {
         this.airplaneMode = enabled
     }
 
+    override fun rotateDevice(direction: String) {
+        events.add(Event.RotateDevice(direction))
+    }
+
     sealed class Event {
 
         data class Tap(
@@ -483,6 +487,10 @@ class FakeDriver : Driver {
         object StartRecording : Event()
 
         object StopRecording : Event()
+
+        data class RotateDevice(
+            val direction: String,
+        ) : Event()
     }
 
     interface UserInteraction

maestro-test/src/test/kotlin/maestro/test/IntegrationTest.kt

@@ -3218,6 +3218,29 @@ class IntegrationTest {
         )
     }
 
+    @Test
+    fun `Case 120 - Rotate the iOS simulator`() {
+        // Given
+        val commands = readCommands("120_rotate_device")
+
+        val driver = driver {
+        }
+
+        // When
+        Maestro(driver).use {
+            orchestra(it).runFlow(commands)
+        }
+
+        // Then
+        // No test failure
+        driver.assertEvents(
+            listOf(
+                Event.RotateDevice("Left"),
+                Event.RotateDevice("Right"),
+            )
+        )
+    }
+
     private fun orchestra(
         maestro: Maestro,
     ) = Orchestra(

maestro-test/src/test/resources/120_rotate_device.yaml

@@ -0,0 +1,6 @@
+appId: com.example.app
+---
+- rotateDevice:
+    direction: "Left"
+- rotateDevice:
+    direction: "Right"