Add `setOrientation` command

[johntmcintosh]

Proposed changes

Introduce a setOrientation command, accepting orientation values of portrait, upsideDown, landscapeLeft, landscapeRight.

If we're onboard with the syntax of this command and argument names, we should also make an addition to the public documentation repo to merge when this is ready to ship.

Background

After starting to build some flows thanks to the recent addition of landscape support on iOS, I found that it worked locally if I manually rotated the simulator into landscape orientation, but was unable to run on CI due to the simulator always launching in portrait.

https://github.com/mobile-dev-inc/maestro/issues/1221 started some discussion about adding the capability to force rotation, but at the time was blocked pending the baseline landscape support that was recently added.

Alternatives

Without adding this capability to maestro, I think the only way to run flows in landscape orientation on CI (at least on iOS simulators) is to expect users to rotate the simulator after it launches before starting the flows. Rotating the simulator is not available through xcrun simctl, which leaves AppleScript as the alternative. AppleScript requires accessibility permissions be granted to the CI runner. While an AppleScript approach should be feasible, it add complexity to all users CI setups by requiring accessibility permissions to run.

Testing

Unit tests: added new unit tests matching conventions from similar commands

iOS: verified locally using my own flows that without this command landscape tests fail, but with the addition of a call to setOrientation: landscapeLeft after launching the app, the tests succeed. The simulator frame stays in portrait orientation, but the test runner is now able to interact with the content correctly. This is the same behavior I see when running XCUITests on the landscape orientation app directly from Xcode.

Android: I do not have an android setup available and have NOT tested this implementation on Android. Android testing support requested!

CI

I get one failure from CI related not committing the compiled iOS changes. I tried including a commit of that, but got the same error, so I could use some guidance on how to proceed there (or if that needs to be re-compiled by a maintainer for consistent provisioning or similar).

Issues fixed

https://github.com/mobile-dev-inc/maestro/issues/1221

[vbarthel-fr]

👋 Hi there :) I'm just a random guy with no prior knowledge on maestro (I have been using maestro for a while though) and I'm also highly interested in having access to such setOrientation command. So thanks a lot for your contribution 👍 🔥

Android: I do not have an android setup available and have NOT tested this implementation on Android. Android testing support requested!

I do have access to an android setup, and I have made a first test: so far, so good!

(Tested from johntmcintosh:feature/set-orientation and running ./maestro studio)

Do not hesitate to tell me if I can be of any help 💪

[Edit 2024-11-07]: I have also tested on a real device (not an emulator) and it's also working like a charm.

[vbarthel-fr]

I tried to implement an end-to-end test for Android : https://github.com/vbarthel-fr/maestro-e2e-set-orientation I tried my best to have the smallest APK as possible (8Kb in debug) that might even be added to this repo if it seems valuable.

The app observes the user_rotation system settings and display a human readable version of it in a text view, while the maestro script calls the setOrientation command and assert that the correct orientation is displayed.

 ║
 ║  > Flow: test-set-orientation-flow
 ║
 ║    ✅   Launch app "com.example.maestro.orientation"
 ║    ✅   Set orientation LANDSCAPE_LEFT
 ║    ✅   Assert that "LANDSCAPE_LEFT" is visible
 ║    ✅   Set orientation LANDSCAPE_RIGHT
 ║    ✅   Assert that "LANDSCAPE_RIGHT" is visible
 ║    ✅   Set orientation UPSIDE_DOWN
 ║    ✅   Assert that "UPSIDE_DOWN" is visible
 ║    ✅   Set orientation PORTRAIT
 ║    ✅   Assert that "PORTRAIT" is visible
 ║

hopefully it might be useful at some point :)