Skip to content

WritingVerifying agent-written iOS code with XcodeBuildMCP and simulator drives

Writing

7 min read

Verifying agent-written iOS code with XcodeBuildMCP and simulator drives

How to verify agent-written iOS changes with real builds, simulator interaction, accessibility checks, and explicit evidence instead of trusting a green compile.

An agent finishes an iOS change and reports success: the build passed, the tests pass, the feature works. Two of those claims are usually true. The third one ships broken screens.

A green compile proves the code parses and type-checks. It says nothing about what a user sees after tapping a row, whether the new screen renders at all, or whether the request behind it returned 403 and quietly filled the list with an empty state.

The fix is cheap. Ask for the same evidence you would ask from a junior engineer, and make the simulator produce it.

1. Decide what counts as evidence before the agent starts

Write the evidence into the brief, not the review. For a normal feature branch I ask for five things:

  • the exact command that was run, with the simulator UDID
  • the path to the build log or .xcresult from that run
  • the accessibility selector the agent asserted and the value it observed
  • a screenshot when the claim is visual
  • an explicit list of what was not verified

That last item is the useful one. An agent that says "I did not check VoiceOver order or Dynamic Type" is telling you where to look, and it is far more trustworthy than one that reports everything green.

2. Build and launch, not just build

XcodeBuildMCP bundles the whole loop: simulator build, simulator build-and-run, simulator test, UI automation, screenshots, and log capture. Use the run variant for anything that touches app startup.

xcodebuildmcp simulator build-and-run \
  --workspace-path Packerly.xcworkspace \
  --scheme Packerly \
  --simulator-id "$UDID" \
  --derived-data-path .agent/DerivedData

build-and-run installs and launches, boots the simulator when needed, and captures runtime logs automatically. The response includes the log file path. Ask the agent to paste that path with its report. It is the first artifact where a confident "succeeded" can be contradicted.

Compile-only build has its uses: quick type checks, CI verification, a package boundary change. It is a weaker claim, and the agent should say so. A migration that compiles and then traps on launch is a routine outcome, and a build-only report cannot see it.

Pass the UDID explicitly, every time. Tools that default to "the booted simulator" pick whichever device is running, which is how an agent ends up testing its build against another session's install.

3. Tests: count them, and know which target ran

xcodebuildmcp simulator test \
  --scheme Packerly \
  --simulator-id "$UDID" \
  --derived-data-path .agent/DerivedData

"I ran the tests" is not a test report. Ask for the scheme, the simulator, and the executed test count. If the count is three tests on a target that had forty, the agent either ran the wrong target or deleted tests, and both matter.

The tool also exposes coverage through get-coverage-report and get-file-coverage on the result bundle. Coverage tells you which new lines nobody executed. It does not tell you the feature works, and an agent that reports 82 percent coverage as proof of correctness has misunderstood the task.

4. Drive the UI through snapshots, not coordinates

Coordinates break the first time a layout changes, and the agent cannot tell you whether the tap landed on the button or the padding beside it.

ui-automation snapshot-ui returns a semantic tree of the current screen with element references:

xcodebuildmcp ui-automation snapshot-ui --simulator-id "$UDID"
xcodebuildmcp ui-automation tap --element-ref "<ref from snapshot>" --simulator-id "$UDID"

Snapshots go stale. Anything that navigates, presents a sheet, scrolls, or reloads a list invalidates the references you just read. Take a new snapshot after every transition, or use wait-for-ui to poll until the target state appears:

xcodebuildmcp ui-automation wait-for-ui \
  --identifier "draft.savedBadge" \
  --predicate exists \
  --timeout-ms 5000 \
  --simulator-id "$UDID"

wait-for-ui supports exists, gone, enabled, focused, textContains, and settled. Prefer those predicates to a sleep. settled is the right one after an animation, because it waits for the tree to stop changing instead of guessing how long a spring takes.

5. Make the assertion match the user-visible outcome

This is where most verification quietly fails. The agent taps a save button, sees no error, and reports that saving works.

Require the assertion in the same sentence as the claim. For a draft save, that means the badge exists and the row count changed:

  • predicate: exists on identifier draft.savedBadge
  • observed: badge present, list row count 3, label reads "Saved just now"

An agent that can only produce "it worked" has not verified anything. The wording you want in the report is short and checkable, and it takes ten seconds to demand.

When the claim is visual, take the screenshot as part of the run. ui-automation screenshot gives you a file path you can open, and record-video is worth it for anything involving transitions or scrolling. A screenshot is the cheapest way to catch the case where the tree is correct and the layout is not.

6. Read the logs for the failures that do not crash

The interesting iOS failures are silent. A 403 renders an empty list. A missing entitlement breaks Sign in with Apple without a visible error. A Core Data migration warning appears only in the console while the app keeps running on stale data.

Because build-and-run and launch-app capture runtime logs automatically, the log path is already in the agent's hands. Make reading it a required step:

Report the log path. If the log contains any error-level line, quote it.
If it contains none, say that explicitly.

That sentence catches more real bugs than the rest of the checklist combined, since agents tend to poll the UI and never look at stdout.

7. Use a separate process when you want an independent check

An MCP session is stateful. If the agent drives the simulator through its own session, its snapshot, its cache, and its report all come from the same place. That is fine for routine work. When the claim matters, run the check yourself from the shell against the same device.

The AXe CLI is a thin simulator automation tool, and it is not the agent's session:

axe describe-ui --udid "$UDID"
axe tap --id "onboarding.continueButton" --udid "$UDID"
axe screenshot --udid "$UDID" --output after-onboarding.png

axe describe-ui prints the accessibility tree with identifiers and labels, which is also the fastest way to find the selector you should have asked the agent to assert. Note that AXe's touch commands are fire-and-forget: the tool confirms the event was dispatched, not that the app handled it. Verify with describe-ui or a screenshot afterwards, and use axe batch with --wait-timeout for multi-screen flows so it polls for elements instead of sleeping.

8. Name what this still does not cover

Build, tests, snapshot, and logs cover a lot of ground and leave real gaps:

  • frame timing, hangs, and scroll smoothness
  • VoiceOver reading order and rotor behavior
  • Dynamic Type at accessibility sizes, and long localized strings
  • push notifications, background refresh, camera, and anything else that needs a real device
  • handoff, widgets, and extensions in their own processes

Do not let a green pass imply those were checked. Either put them in the review or put them in the "not verified" list. Performance claims need Instruments or record-video; reading order needs a VoiceOver pass with the screen reader on.

9. Keep the gate short

The version that survives contact with a real week is five bullets, and I run it on every agent branch before I read the diff:

  • the command, the scheme, and the simulator UDID
  • the log path or .xcresult path from that run
  • the selector asserted and the value observed
  • a screenshot for anything visual
  • the list of what was not verified

Anything longer gets skipped exactly on the day it would have caught something. The goal is to make "done" mean the same thing to the agent and to you, and to spend the time on the screens that matter rather than the ones that merely compile.