feat: add ability to switch themes on iOS and Android: setDarkMode & toggleDarkMode #2507

markrickert · 2025-05-29T19:14:22Z

Proposed changes

This is a new feature that adds the ability to set the light/dark mode on iOS and Android platforms.

It adds the following new functionality:

setDarkMode - possible values: enabled / disabled
toggleDarkMode - swaps between light/dark mode

It achieves this by running commands for iOS/Android:

	iOS	Android
`setDarkMode: enabled`	`xcrun simctl ui booted appearance dark`	`adb shell 'cmd uimode night yes'`
`setDarkMode: disabled`	`xcrun simctl ui booted appearance light`	`adb shell 'cmd uimode night no'`

Possible enhancements

There's a way to change the macOS theme and toggle between light/dark mode from the terminal but it requires you use applescript on the commandline. This would be for the web implementation to toggle back and forth since there's no current web implementation of this feature.

Testing

./gradlew :maestro-test:test && ./gradlew test passes 🟢

I then "ignited" an app that has a default maestro test in it called FavoritePodcast.yaml and replaced the contents with the following, adding calls to setDarkMode and toggleDarkMode

# flow: run the login flow and then navigate to the demo podcast list screen, favorite a podcast, and then switch the list to only be favorites.

appId: ${MAESTRO_APP_ID}
env:
  FAVORITES_TEXT: "Switch on to only show favorites" # en.demoPodcastListScreen.accessibility.switch
onFlowStart:
  - runFlow: ../shared/_OnFlowStart.yaml
---
- runFlow: ../shared/_Login.yaml
- setDarkMode: disabled
- toggleDarkMode
- toggleDarkMode
- tapOn: "Podcast"
- assertVisible: "React Native Radio episodes"
- tapOn:
    text: ${FAVORITES_TEXT}
- setDarkMode: disabled
- assertVisible: "This looks a bit empty"
- tapOn:
    text: ${FAVORITES_TEXT}
    # https://maestro.mobile.dev/troubleshooting/known-issues#android-accidental-double-tap
    retryTapIfNoChange: false
- toggleDarkMode
- repeat:
    times: 2
    commands:
      - scroll
- copyTextFrom:
    text: "RNR .*" # assumes all podcast titles start with RNR
    index: 2 # grab the third one, others might not be fully visible
- toggleDarkMode
- longPressOn: ${maestro.copiedText}
- scrollUntilVisible:
    element:
      text: ${FAVORITES_TEXT}
    direction: UP
    timeout: 50000
    speed: 90
    visibilityPercentage: 100
- tapOn:
    text: ${FAVORITES_TEXT}
- assertVisible: ${maestro.copiedText}

Then to test this, i ran the associated application on the iOS simulator and from this projects' directory i ran:

./maestro record -e MAESTRO_APP_ID=com.foo ../Foo/.maestro/flows/FavoritePodcast.yaml

Here is the resulting video showing the interface swapping back and forth from light to dark:

maestro-record.mp4

Issues fixed

n/a

markrickert · 2025-05-29T19:16:48Z

Adde docs PR to document new feature - mobile-dev-inc/maestro-docs#133

morganick · 2025-05-29T19:20:24Z

@markrickert does this handle specifying the device?

markrickert · 2025-05-29T19:29:45Z

@markrickert does this handle specifying the device?

@morganick On iOS, it should pass through the device id and if you don't pass one, it'll use "booted" as a default. I'm unsure how android handles this.

https://github.com/mobile-dev-inc/Maestro/pull/2507/files#diff-25ebfb9b3069b37481b09445ea8c4458fdebdc760b55ef6e9af537f0fc1e9221R518-R527

morganick · 2025-05-29T19:32:59Z

@markrickert does this handle specifying the device?

@morganick On iOS, it should pass through the device id and if you don't pass one, it'll use "booted" as a default. I'm unsure how android handles this.

https://github.com/mobile-dev-inc/Maestro/pull/2507/files#diff-25ebfb9b3069b37481b09445ea8c4458fdebdc760b55ef6e9af537f0fc1e9221R518-R527

@markrickert Yeah, I saw the deviceId portion on iOS, but trying to run your commands when I have more than one android device results in adb: more than one device/emulator. It needs the -s <serial-number> for the specified device. I didn't see how this was handled on the android side either.

…ulator is open

markrickert · 2025-05-29T21:18:06Z

@morganick I believe i've addressed the problem. I was using the regular shell command when i should have been using dadb.shell to reference the currently active emulator instance.

fd264a5

Leland-Takamine · 2025-05-29T23:40:20Z

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

+            "setDarkMode command takes either: \n" +
+                    "\t1. enabled: To enable dark mode\n" +
+                    "\t2. disabled: To disable dark mode\n" +
+                    "\t3. value: To set dark mode to a specific value (enabled or disabled) \n" +


I was a bit confused about this line

I was copying the airplane mode function as it allows this syntax:

- setDarkMode enabled

or

- setDarkMode value: enabled label: "Something"

I'm definitely open to suggestions on how to improve this!

Oh yeah I think the syntax makes sense. The 3rd line of the error message is what was confusing me - seems redundant?

1. enabled: To enable dark mode 2. disabled: To disable dark mode 3. value: To set dark mode to a specific value (enabled or disabled)

Oh ok I think I understand now. Maybe it would be clearer to show those two styles of syntax as examples in the error message

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

Leland-Takamine · 2025-05-29T23:46:37Z

@morganick I believe i've addressed the problem. I was using the regular shell command when i should have been using dadb.shell to reference the currently active emulator instance.

fd264a5

shell method was actually correct - it's just a helper that checks the exit code as well. You'd just pass in the adb shell command without the adb shell part since it's using Dadb.

    private fun shell(command: String): String {
        val response: AdbShellResponse = try {
            dadb.shell(command)
        } catch (e: IOException) {
            throw IOException(command, e)
        }

        if (response.exitCode != 0) {
            throw IOException("$command: ${response.allOutput}")
        }
        return response.output
    }

Leland-Takamine · 2025-05-29T23:49:25Z

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

@@ -515,6 +515,16 @@ class IOSDriver(
        LOGGER.warn("Airplane mode is not available on iOS simulators")
    }

+    override fun isDarkModeEnabled(): Boolean {
+        val deviceId = iosDevice.deviceId ?: "booted"
+        return XCRunnerCLIUtils.isDarkModeEnabled(deviceId)


Is there a way to do this via xcuitest? We're trying to move away from simctl commands since they won't work for physical devices

I'll look into this tomorrow to see if there's a way to do it. Not sure at the moment.

@Leland-Takamine I found this reference already inside the repo's source code, but i have no idea how i would go about using it 🤷 https://github.com/mobile-dev-inc/Maestro/blob/main/maestro-ios-xctest-runner/maestro-driver-iosUITests/PrivateHeaders/XCTest/XCUIDevice.h#L18-L22

Edit: Also found this SO answer that indicates we might be able to just do:

if #available(iOS 15.0, *) { XCUIDevice.shared.appearance = .dark }

But this is my first time ever looking at XCUIDevice so i have no idea how i'd implement that 😬

Hey @markrickert thanks for contribution, I think this is would be a new endpoint in our XCUITest driver here:

https://github.com/mobile-dev-inc/Maestro/tree/main/maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/Handlers

You can check any one handler there for example. On implementation we would receive the appearence and then as you shared:

switch requestBody.appearance.lowercased() { case "dark": XCUIDevice.shared.appearance = .dark case "light": XCUIDevice.shared.appearance = .light default: return AppError(type: .precondition, message: "Invalid appearance value. Use 'dark' or 'light'").httpResponse }

And this endpoint would be reached from XCTest client here in maestro: https://github.com/mobile-dev-inc/Maestro/blob/main/maestro-ios/src/main/java/ios/xctest/XCTestIOSDevice.kt

amanjeetsingh150 · 2025-06-03T11:34:18Z

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

@@ -478,6 +482,25 @@ data class YamlFluentCommand(
                )
            )

+            setDarkMode != null -> listOf(


I wonder are there cases where it is useful to set appearance mid flow execution?

Is this more useful as a command or flow based or upload level config?

amanjeetsingh150 · 2025-06-03T11:36:42Z

maestro-orchestra/src/test/resources/YamlCommandReaderTest/023_labels.yaml

+      value: enabled
+      label: "Turn on dark mode for testing"
+- toggleDarkMode:
+      label: "Toggle dark mode for testing"


What is the difference between these two commands?

Can't I toggle with reverting the value passed in setDarkMode command? 🤔

amanjeetsingh150 · 2025-06-03T11:38:26Z

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

+
+        // Then
+        // No test failures
+        driver.assertNoInteraction()


This feels like incomplete we do want to assert the appearance event here though right?

amanjeetsingh150 · 2025-06-03T11:42:44Z

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

+        }
+
+    override fun evaluateScripts(jsEngine: JsEngine): Command {
+        return this


Should we be allowing setting this variable with js? Not sure. Like runtime through JS. If yes then we might want to handle this.

markrickert added 2 commits May 29, 2025 12:25

feat: add ability to switch themes on iOS and Android

4671e32

chore: rename DarkValue to DarkModeValue

b1a7628

markrickert mentioned this pull request May 29, 2025

Add docs for setDarkMode and toggleDarkMode mobile-dev-inc/maestro-docs#133

Open

fix: fixes issue with setting dark mode when more than one android em…

fd264a5

…ulator is open

Leland-Takamine reviewed May 29, 2025

View reviewed changes

maestro-test/src/test/kotlin/maestro/test/IntegrationTest.kt Show resolved Hide resolved

Leland-Takamine reviewed May 29, 2025

View reviewed changes

markrickert added 2 commits May 29, 2025 18:21

tests: add missing assertions to tests

13410de

revert back to using the shell command instead of dadb.shell

408fd6d

amanjeetsingh150 reviewed Jun 3, 2025

View reviewed changes

feat: add ability to switch themes on iOS and Android: setDarkMode & toggleDarkMode #2507

Are you sure you want to change the base?

feat: add ability to switch themes on iOS and Android: setDarkMode & toggleDarkMode #2507

Uh oh!

Conversation

markrickert commented May 29, 2025

Proposed changes

Possible enhancements

Testing

Issues fixed

Uh oh!

markrickert commented May 29, 2025

Uh oh!

morganick commented May 29, 2025

Uh oh!

markrickert commented May 29, 2025

Uh oh!

morganick commented May 29, 2025

Uh oh!

markrickert commented May 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Leland-Takamine May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Leland-Takamine commented May 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markrickert May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Leland-Takamine May 30, 2025 •

edited

Loading

markrickert May 30, 2025 •

edited

Loading