Test an iOS app on a real iPhone from your Mac

A simulator runs your app on your Mac’s CPU, with your Mac’s memory and a keyboard that always works. A phone doesn’t. The bugs that ship are often the ones a simulator can’t show you: a screen that hitches on an A15, a sheet that sits under the keyboard, a build whose signing or entitlements are wrong, a paywall that loads real sandbox prices. This guide takes you from a cable to a passing test on a real iPhone, first with Apple’s tools and then with Mobster’s.

Prepare the iPhone

1. Plug the iPhone into your Mac, unlock it and tap Trust when it asks.
2. Turn on Developer Mode: Settings › Privacy & Security › Developer Mode. Turn it on, tap Restart, and confirm after the restart. The switch appears only once Xcode has seen the phone.
3. In Xcode, open Settings › Accounts and sign in with your Apple Account. A free account works.
4. Open your project, select the app target, and under Signing & Capabilities choose your team. Give the bundle ID a name only you use, such as com.yourname.yourapp.dev.

With a free account the signature lasts 7 days. After that the app won’t open until you build and install it again. Apple’s guide covers the same steps in Xcode’s own screens.

Build and install from the terminal

Run these from your project’s folder. xcrun devicectl and xcrun xctrace ship with Xcode.

$ xcrun xctrace list devices

Your phone’s line ends with its UDID: Test iPhone (26.0.1) (<UDID>). Use it for both xcodebuild and devicectl. xcrun devicectl list devices shows a different ID, CoreDevice’s, which xcodebuild rejects. Then build for the phone, install and launch:

$ xcodebuild -scheme YourApp \  -destination 'platform=iOS,id=<UDID>' \  -derivedDataPath build -allowProvisioningUpdates build$ xcrun devicectl device install app --device <UDID> \  build/Build/Products/Debug-iphoneos/YourApp.app$ xcrun devicectl device process launch --device <UDID> \  --console com.yourname.yourapp.dev

--console streams the app’s output into your terminal until you press ctrl+c. That is the quickest way to see a crash message from a phone you can’t attach a debugger to.

Run XCUITest on the phone

The same destination runs your UI tests:

$ xcodebuild test -scheme YourApp -only-testing:YourAppUITests \  -destination 'platform=iOS,id=<UDID>' -allowProvisioningUpdates

XCUITest runs inside a test runner app that Xcode signs and installs next to yours, so the phone must stay unlocked for the whole run. If a system alert appears, such as a notification permission, register an addUIInterruptionMonitor handler or the test stalls on it.

Run saved checks on the phone with Mobster

A Mobster check is a YAML file that says what must be true of a screen. Mobster runs the flow, then decides the verdict from the app’s accessibility tree, never from a model. The same file runs on a simulator and on your iPhone.

# .mobster/checks/lesson-complete.yamlversion: 1name: Lesson complete awards XP and the streak goes upapp:  bundle: com.yourname.yourapp.devsteps:  - Pick the word that fills the blank, then tap Check.  - Tap Continue until the lesson ends.expect:  - text: Lesson complete  - value: { id: xp_earned }    equals: 10  - value: { id: streak_days }    equals: 4

Mobster for Mac sets the phone up for you: it builds and signs WebDriverAgent, the open-source XCTest runner that reads the screen, and walks you through Developer Mode with a picture of each step.

Mobster for Mac sets up the phone.

Then list what Mobster can drive and run the checks on the phone. mobster devices prints one row per device, simulators included (the name here is a stand-in for yours):

$ mobster devices  Name                          Kind       State        Details  Test iPhone                   iPhone     Ready        iPhone 15 Pro, iOS 26.0.1

$ mobster test --device "Test iPhone"

Mobster installs the check’s app.path when it’s an .ipa or a device build, or uses the build already on the phone when devicectl lists it as built by a developer. It prints a line per check, the totals and where the reports are. Example output:

✓ passed  Lesson complete awards XP and the streak goes up  on iPhone 15 Pro, iOS 26.0.1✗ failed  The daily reminder stays on after a relaunch  on iPhone 15 Pro, iOS 26.0.1    1 of 1 expectations failed1 passed, 1 failed in 1 min 12 s, $0.04Report  .mobster/test-results/20261007-142233-9c1e/index.htmlJUnit   .mobster/test-results/20261007-142233-9c1e/junit.xml

A failed check in the report, from a simulator run. The streak is outlined, and the expectation says what it found: was "3 days".

The exit code is the verdict: 0 passed, 1 failed, 2 needs review, 3 couldn’t run. A check with steps runs Smart on your Claude or OpenAI key until it passes once. After that it replays the recorded steps with no model call. On 17 October 2026, on an iPhone 15 Pro (iOS 26.0.1, USB), a two-step check that opens a paywall from Settings in a test app took 17.7 s median fresh and 10.3 s replayed over 5 runs each, at $0.017 and $0 a run. A launch-only check, with no steps, never calls a model.

What Mobster does and doesn’t do on your phone

• It drives only your own app, and only a build you put there. An App Store app is refused: “Mobster tests your own apps on your iPhone. Instagram is from the App Store.”
• Smart steps stay in your app. If one opens another app, the check stops.
• It never clears the app’s data on a phone. Smart steps never send, buy, post or delete there: every commit is refused.
• A phone is reached only with --device on the command line. A check file can’t name one.
• One check runs at a time on a phone. --device all uses every ready phone, and --spread gives each check to whichever is free.
• It can’t pass Face ID or your passcode. Keep the phone unlocked.
• Real iPhones need a Mobster plan. Simulators don’t.

Which one to use

XCUITest is the right tool when your tests live in your repository, run in Xcode and need to reach inside your app’s process. Mobster is the right tool when you want checks as files that a person or an agent can write in plain English, the same check on simulators and phones, and a report with the frame that proves each verdict. Maestro vs XCUITest vs Mobster sets the three side by side.

Device setup has the same steps for the mobster command on its own.