FAQ

Frequently asked questions about Maestro installation and usage.

Find answers to common Maestro questions: parameters, assertions, YAML gotchas, cloud behavior, and how to organize your tests.

How can I use the same flow when my apps have different app IDs?

Use an external parameter for appId and pass it when you run Maestro. For example, pass APP_ID when testing with the Maestro CLI:

maestro test -e APP_ID=your.app.id file.yaml

In your Flow, refer to it with ${APP_ID}:

appId: ${APP_ID}
---
- launchApp

How do I assert on a string that contains a dollar sign?

Maestro treats $ as the start of a variable. Escape the dollar so it is treated as literal text:

- assertVisible: \$150 in Cash

How do I compare two values?

To assert on values that appear on different screens, store each value in a variable with copyTextFrom and evalScript, then compare in a runFlow with a when condition:

# Navigate to first value, then:
- copyTextFrom:
    id: 'listView1'
- evalScript: ${output.firstPrice = maestro.copiedText}

# Navigate to second value, then:
- copyTextFrom:
    id: 'detailView'
- evalScript: ${output.secondPrice = maestro.copiedText}

# Compare:
- runFlow:
    when:
      true: ${output.firstPrice === output.secondPrice}
    commands:
      - evalScript: ${console.log('Prices match! Both are ' + output.secondPrice)}

How do I generate a random number?

Maestro offers built-in support for random numbers, so you don't need to write external scripts.

You can use the inputRandomNumber command if you need to type the number directly into a field:

- inputRandomNumber:
    length: 8

Another option is to use Faker. Use this option if you need to store the number in a variable or use it within a specific range, use the built-in faker library via evalScript:

- evalScript: ${output.thisNumber = faker.expression("#{number.numberBetween '1' '10'}")}

Why does YES get translated to true, and NO to false?

If you use tapOn: YES or tapOn: NO, Maestro may interpret them as booleans and attempt to find the text "true" or "false" instead:

appId: com.example
---
- launchApp
- tapOn: YES

You may see an error like:

 ║  > Flow: flow                         
 ║                                       
 ║    ❌   Tap on "true"                 
 ║                                       
                                         
Element not found: Text matching regex: true

Element with Text matching regex: true not found. Check the UI hierarchy in debug artifacts to verify if the element exists.

This behavior comes from YAML itself. The YAML specification allows booleans to be written as true/false, yes/no, on/off, or Y/N (in various casings). As a result, unquoted YES and NO are parsed as booleans.

To work around this, force the value to be treated as literal text by quoting it, or use a regular expression:

- tapOn: "YES"
- tapOn: ^No    # Text that begins with "No"

Why are my tests slower in Maestro's cloud environment?

The cloud environment prioritizes reliability and repeatability: each device is wiped and recreated between tests so one run cannot affect another. While this adds about 45 seconds between tests compared with running locally, it ensures a clean state for every execution.

To reduce total run time:

• Add more parallel runners.

• Restructure tests into fewer, longer flows, without sacrificing reliability or useful failure information.

How do I connect WSL2 to the Android Simulator running on Windows?

When attempting to bridge the connection between WSL2 and Windows using adb -a -P 5037 nodaemon server, you may encounter smart_sockets errors. This typically indicates that port 5037 is already in use or a background ADB process is conflicting with your setup.

Host environment cleanup (Windows)

Before re-initializing the connection, you must isolate the environment on your Windows host.

1. Open Task Manager and end all adb.exe processes, or run the following in PowerShell:

   stop-process -name adb -force

2. Close Android Studio to prevent it from automatically restarting the ADB server with default settings. Keep the Android Emulator active.

3. If adb devices shows the emulator as offline at this stage, proceed anyway; the status usually resolves once the bridge is established.

Network and firewall configuration

WSL2 runs on a virtualized network. Your Windows firewall must be configured to allow this external traffic.

• Inbound Rule: Create a rule in Windows Defender Firewall to allow TCP traffic on port 5037.

• Corporate Policies: If using a managed work machine, ensure your administrator has not blocked local network socket binding.

Initialize the global ADB daemon

Open a PowerShell terminal and run the following command. Keep this window open, as closing it will terminate the connection bridge:

adb -a -P 5037 nodaemon server

WSL2 client configuration

Configure your WSL2 instance to look for the ADB server on your Windows host rather than its own local environment.

1. Kill the local server:

   adb kill-server

2. Find your Windows IPv4 address and export it to the environment:

   export ADB_SERVER_SOCKET=tcp:<WINDOWS_IPV4_ADDR>:5037

3. Verify the link:

   adb devices

The output should now list the emulator instance running on the Windows host.

Maestro integration note

Maestro requires a stable ADB connection to orchestrate tests. If the Windows ADB daemon does not recognize the emulator before you start a Maestro Flow, the test will fail.

Always verify that adb devices returns a valid device ID in your WSL2 terminal before running Maestro commands.

Still having issues?

If you are not using WSL2 and are seeing different errors, join the #maestro-questions channel in the Maestro Slack community.