{"id":38281829,"url":"https://github.com/devicelab-dev/maestro-ios-device","last_synced_at":"2026-02-11T06:09:32.356Z","repository":{"id":327362786,"uuid":"1108950452","full_name":"devicelab-dev/maestro-ios-device","owner":"devicelab-dev","description":"Run Maestro UI tests on real iOS devices. Community tool for physical iPhone/iPad testing with XCTest driver and port forwarding.","archived":false,"fork":false,"pushed_at":"2026-01-16T09:29:25.000Z","size":65870,"stargazers_count":45,"open_issues_count":3,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-16T23:47:06.745Z","etag":null,"topics":["automation","e2e-testing","ios","ios-testing","macos","maestro","mobile-testing","real-device-testing","ui-testing","xctest"],"latest_commit_sha":null,"homepage":"https://devicelab.dev/","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devicelab-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T06:15:15.000Z","updated_at":"2026-01-16T09:28:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/devicelab-dev/maestro-ios-device","commit_stats":null,"previous_names":["devicelab-dev/maestro-ios-device"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/devicelab-dev/maestro-ios-device","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devicelab-dev%2Fmaestro-ios-device","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devicelab-dev%2Fmaestro-ios-device/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devicelab-dev%2Fmaestro-ios-device/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devicelab-dev%2Fmaestro-ios-device/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devicelab-dev","download_url":"https://codeload.github.com/devicelab-dev/maestro-ios-device/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devicelab-dev%2Fmaestro-ios-device/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29327994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T03:52:29.695Z","status":"ssl_error","status_checked_at":"2026-02-11T03:52:23.094Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","e2e-testing","ios","ios-testing","macos","maestro","mobile-testing","real-device-testing","ui-testing","xctest"],"created_at":"2026-01-17T02:00:14.252Z","updated_at":"2026-02-11T06:09:32.350Z","avatar_url":"https://github.com/devicelab-dev.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# maestro-ios-device\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)\n[![Maestro 2.x](https://img.shields.io/badge/Maestro-2.x-green.svg)](https://maestro.mobile.dev)\n\n**Run Maestro UI tests on real iOS devices** — iPhone and iPad physical device testing with XCTest driver and automatic port forwarding.\n\n🚀 **Update:** We built [maestro-runner](https://github.com/devicelab-dev/maestro-runner) from scratch — 3.6x faster, real iOS device support, runs locally or on any Appium cloud, true parallel execution, no paywall. Fixes 78% of Maestro's top issues. Same YAML.\n\n\u003e [!NOTE]\n\u003e This repo remains fully supported until Maestro adds official iOS physical device support.\n\n\u003e ⚠️ **Unofficial Community Tool**\n\u003e This is not affiliated with or endorsed by mobile.dev or the Maestro project.\n\n\u003e Built from [PR #2856](https://github.com/mobile-dev-inc/Maestro/pull/2856) — for source code, please refer to the [PR #2856](https://github.com/mobile-dev-inc/Maestro/pull/2856).\n\n*Built by [DeviceLab](https://devicelab.dev) — stop renting devices you already own.*\n\n## Table of Contents\n\n- [Features](#what-it-does)\n- [Compatibility](#compatibility)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [How It Works](#how-it-works)\n- [Limitations](#limitations)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## What It Does\n\n1. Patches your existing Maestro installation with real device support\n2. Builds and runs the XCTest driver on your iOS device\n3. Sets up port forwarding so Maestro can communicate with the device\n\n## Compatibility\n\n| Maestro Version | Status |\n|-----------------|--------|\n| 2.1.0 | ✅ Supported |\n| 2.0.10 | ✅ Supported |\n| 2.0.9 | ✅ Supported |\n| Other 2.x | ❌ Not tested |\n| 1.x | ❌ Not supported |\n\n\u003e **Note:** We build patches against specific Maestro releases. Using unsupported versions may cause issues.\n\n## Requirements\n\n- macOS\n- [Maestro 2.x](https://maestro.mobile.dev) installed\n- Xcode with command line tools\n- Apple Developer account (free or paid)\n- iOS device connected via USB\n\n## Installation\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/devicelab-dev/maestro-ios-device/main/setup.sh | bash\n```\n\nThis will:\n\n- Download the `maestro-ios-device` binary\n- Download patched JARs and iOS runner\n- Backup your current Maestro installation\n- Patch Maestro with real device support\n\n### Verify Installation\n\n```bash\nmaestro-ios-device --version\n```\n\n## Usage\n\n### 1. Start the Device Bridge\n\nKeep this running in a terminal:\n\n```bash\nmaestro-ios-device --team-id YOUR_TEAM_ID --device DEVICE_UDID\n```\n\n### 2. Run Maestro Tests\n\nIn another terminal:\n\n```bash\nmaestro --driver-host-port 6001 --device DEVICE_UDID --app-file /path/to/app.ipa test flow.yaml\n```\n\n### Finding Your Team ID\n\n```bash\n# List available teams\nsecurity find-identity -v -p codesigning | grep \"Developer\"\n```\n\nOr in Xcode: **Xcode → Settings → Accounts → Select Team → Team ID**\n\n### Finding Your Device UDID\n\n```bash\n# List connected devices\nxcrun xctrace list devices\n```\n\nOr in Finder: **Select your iPhone → Click device name to reveal UDID**\n\n## Options\n\n| Flag | Description |\n|------|-------------|\n| `--team-id` | Apple Developer Team ID (required) |\n| `--device` | Device UDID (required) |\n| `--driver-host-port` | Local port (default: auto from 6001) |\n| `--uninstall` | Restore original Maestro installation |\n| `--version` | Show version |\n| `--help` | Show help |\n\n## How It Works\n\n```\n┌─────────────┐     ┌──────────────────┐     ┌─────────────┐\n│   Maestro   │────▶│ maestro-ios-device│────▶│ iOS Device  │\n│  (patched)  │     │  (port forward)  │     │ (XCTest)    │\n└─────────────┘     └──────────────────┘     └─────────────┘\n     :6001                                        :22087\n```\n\n1. **maestro-ios-device** builds and installs the XCTest runner on your device\n2. The runner starts an HTTP server on device port 22087\n3. Port forwarding connects localhost:6001 → device:22087\n4. Patched Maestro sends commands via `--driver-host-port 6001`\n\n## Limitations\n\nSome commands have limited support on real iOS devices due to iOS restrictions:\n\n| Command | Status | Notes |\n|---------|--------|-------|\n| `clearState` | ✅ Works | Reinstalls app (requires `--app-file`) |\n| `setLocation` | ⚠️ Limited | Requires additional setup |\n| `addMedia` | ❌ Not supported | iOS restriction |\n\n\u003e **Note:** The `--app-file` flag is required for real device testing.\n\n## Uninstallation\n\nRestore your original Maestro installation:\n\n```bash\nmaestro-ios-device --uninstall\n```\n\nOr manually:\n\n```bash\ncp ~/.maestro/backup/* ~/.maestro/lib/\n```\n\n## When to Stop Using This\n\nThis tool is temporary. Once [PR #2856](https://github.com/mobile-dev-inc/Maestro/pull/2856) is merged:\n\n1. Run `maestro-ios-device --uninstall`\n2. Update Maestro: `brew upgrade maestro`\n3. Use official iOS device support\n\nWe'll update this README when official support lands.\n\n## Troubleshooting\n\n### \"Certificate not trusted\"\n\nOn your iOS device: **Settings → General → VPN \u0026 Device Management → Trust your developer certificate**\n\n### Build fails\n\n- Ensure Xcode command line tools are installed: `xcode-select --install`\n- Open Xcode at least once to accept the license\n- Check that your Apple Developer account is signed in\n\n### Device not found\n\n- Ensure device is connected via USB\n- Trust the computer on your device when prompted\n- Try `xcrun xctrace list devices` to verify connection\n\n### Port already in use\n\n```bash\n# Find process using port 6001\nlsof -i :6001\n\n# Use a different port\nmaestro-ios-device --team-id YOUR_TEAM_ID --device DEVICE_UDID --driver-host-port 6002\n```\n\n### XCTest runner crashes\n\n- Ensure your device is running iOS 15+\n- Check Xcode logs: **Window → Devices and Simulators → View Device Logs**\n\n## Contributing\n\nIssues and PRs welcome at [GitHub](https://github.com/devicelab-dev/maestro-ios-device/issues).\n\n## License\n\nApache 2.0 (same as Maestro)\n\n## Disclaimer\n\nThis project is not affiliated with, endorsed by, or connected to mobile.dev or the official Maestro project.\n\nThis tool patches your existing Maestro installation to add functionality not yet available in the official release.\n\n**Use at your own risk.** We recommend switching to official Maestro once iOS device support is released.\n\n---\n\n[Report Issues](https://github.com/devicelab-dev/maestro-ios-device/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevicelab-dev%2Fmaestro-ios-device","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevicelab-dev%2Fmaestro-ios-device","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevicelab-dev%2Fmaestro-ios-device/lists"}