Maestro on Real iOS Devices: Working Guide

Source: Dev.to

TL;DR
Maestro doesn’t officially support physical iOS devices. We built maestro-ios-device to fix that. Your existing YAML flows work unchanged on real iPhones.

The problem

• Your Maestro tests pass on the iOS Simulator, but not on a real iPhone.
• Official support for physical iOS devices is not expected until sometime next year.
• Cloud providers (e.g., BrowserStack) can run Maestro on their infrastructure, but they require a subscription and send your app/data off‑site.

Current platform support (December 2025)

Our solution: a bridge to physical iOS devices

What it does

• Runs your existing Maestro YAML flows on real iPhones
• Requires no changes to your test files
• Supports parallel testing on multiple devices
• Works with iOS 16.x – 18.x

What it doesn’t do

• Require a cloud subscription
• Send your app or test data anywhere
• Change how you write Maestro tests

Installation

curl -fsSL https://raw.githubusercontent.com/devicelab-dev/maestro-ios-device/main/setup.sh | bash

Starting the device bridge

maestro-ios-device --team-id YOUR_TEAM_ID --device DEVICE_UDID

Running your tests

maestro --driver-host-port 6001 \
       --device DEVICE_UDID \
       --app-file /path/to/app.ipa \
       test flow.yaml

Example YAML flow (unchanged)

appId: com.example.app
---
- launchApp
- tapOn: "Login"
- inputText: "user@example.com"
- tapOn: "Submit"
- assertVisible: "Welcome"

Parallel testing on multiple real iOS devices

The original Maestro codebase had hard‑coded port limitations; we removed them.

Terminal 1

maestro-ios-device --team-id ABC123 --device IPHONE_12_UDID --driver-host-port 6001

Terminal 2

maestro-ios-device --team-id ABC123 --device IPHONE_14_UDID --driver-host-port 6002

Now run your test suite split across devices, cutting CI time in half (or more).

How it works under the hood

1. Device Detection – Recognizes physical devices with Developer Mode enabled.
2. XCTest Runner – Builds and deploys the test driver to actual hardware (requires an Apple Developer certificate).
3. Port Forwarding – Bridges localhost to the device’s HTTP server.
4. Session Management – Handles real‑device constraints gracefully (e.g., clearState via app reinstall).

Supported commands and status

Background

• DeviceLab needed a way for teams to test on their own physical devices.
• The Maestro codebase already contained the foundation for iOS device support; only the final integration was missing.
• We submitted PR #2856 to the upstream repository, but community PRs can take time to merge, so we released maestro-ios-device as a standalone tool.

Version compatibility

Requirements

• macOS with Xcode (required for code signing)
• Apple Developer account (free tier works for personal devices)
• iOS device with Developer Mode enabled

FAQ

Is this an official tool?
No. It is an unofficial community tool, not supported by mobile.dev or the Maestro team. When official iOS device support ships, we recommend switching to it.

Will my existing YAML flows work?
Yes. If they run on the iOS Simulator, they will run on real devices without changes.

Is the tool free?
Yes. You only need an Apple Developer account (free tier is sufficient for personal devices).

Does any data leave my network?
No. All testing runs on your own devices in your office; nothing is sent to external services.

Links

• Tool:
• PR:
• Original issue:

Built by DeviceLab – turn your devices into a testing lab without renting someone else’s.