Enable concurrent testing on multiple devices/simulators from same machine

[omnarayan]

Proposed changes

copilot:summary Introduces a new global --driver-host-port CLI option that allows users to specify custom driver ports for both Android and iOS, enabling parallel test execution on multiple devices/simulators without port conflicts.

Problem

Currently, running tests concurrently on different devices fails because all Maestro instances attempt to use the default port 7001, resulting in:

• Connection refused: localhost:7001
• Command failed (tcp:7001): closed

Users cannot run different tests on different devices simultaneously.

Solution

• Added --driver-host-port global CLI option to App.kt
• Modified TestCommand.kt to respect user-specified port in selectPort() method
• Updated all commands (RecordCommand, StudioCommand, QueryCommand, PrintHierarchyCommand, StartDeviceCommand) to pass custom port to session manager
• Maintains backward compatibility - defaults to 7001 if not specified
• Works for both Android devices and iOS simulators

Usage Example

# Terminal 1: Run auth tests on device 1 with port 7005
maestro --driver-host-port 7005 --device device1 test auth-suite.yaml

# Terminal 2: Run product tests on device 2 with port 7006
maestro --driver-host-port 7006 --device device2 test product-suite.yaml

Try it now (before merge)

To use this feature, you have three options:

1. Wait for PR merge - This PR needs to be reviewed and merged
2. Build from source - Clone this branch and build Maestro yourself
3. Use pre-built version - Install the updated JAR directly:

Upgrade:

curl -fsSL https://raw.githubusercontent.com/omnarayan/Maestro/feature/driver-host-port-distribution/upgrade-maestro-ports.sh | sh

This replaces your Maestro JAR with the updated version. Usage:

maestro --driver-host-port 7005 --device device1 test flow.yaml
maestro --driver-host-port 7006 --device device2 test flow.yaml

Restore Original:

bash ~/.maestro-backups/backup/restore.sh

Credit

This implementation builds upon the approach proposed by @avinash-bharti in #2339, implementing the port configuration feature without the additional session management changes.

Testing

• ✅ Verified concurrent execution on physical Android device (port 7005) + emulator (port 7006) running different test suites simultaneously
• ✅ Confirmed no session mixing between devices - each test ran on its intended device with correct app
• ✅ Backward compatibility verified: default port 7001 works without the flag
• ✅ Tested on both Android devices and iOS simulators
• ✅ All test steps completed successfully with no port conflicts

Test logs show both devices executing tests in parallel without interference.

Issues fixed

Resolves #1485, #1853, #2082, #2556, #2703 Related to #1818

[Fishbowler]

I noted that you've said this resolves #2703 - if you manually specify a port that's already in use, how does this behave?

[omnarayan]

I noted that you've said this resolves #2703 - if you manually specify a port that's already in use, how does this behave?

Good catch on the earlier gap! I've just pushed a fix for this.

Now if you specify a port that's already in use:

maestro --driver-host-port 7005 test flow.yaml

You'll get a clear error:

Port 7005 is already in use. Please specify a different port with --driver-host-port

Same for the default port - if 7001 is occupied:

Default port 7001 is already in use. Use --driver-host-port to specify a different port

The port check happens right before the driver starts, so it catches conflicts at the point of use.

We missed this earlier because our internal tooling checks port availability before passing --driver-host-port to Maestro, so we weren't hitting this scenario directly. Apologies for the oversight.