# Build and test an iOS app

From your repository to a passing test run on a cloud Mac, with the build, the results and screenshots back on your side. The next build is incremental.

## 1 Put the project on the Mac

Clone it onto the drive, so the next session starts from it:

Terminal

```
git clone https://github.com/acme/app ~/drive/src/app
```

Or send the folder on your machine: `nomac sync .` puts it in `~/drive/src/<folder>` and sends only what changed, and `--watch` keeps sending as you edit. A private repository's token can come from your [secrets](/content/docs/session/secrets/index.html).

## 2 Build

Terminal

```
cd ~/drive/src/app
xcodebuild -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=27.0' \
  build | xcbeautify
```

Give builds time: over MCP, `wait_seconds: 40` and a `timeout_seconds` of up to 3600; with the CLI, `nomac exec --wait 600`. Each iOS runtime has devices with the same names, so name the OS version too.

Expo and Capacitor apps make their `ios` folder first: `npx expo prebuild -p ios` or `npx cap sync ios`.

## 3 Test

Terminal

```
xcodebuild test -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=27.0' | xcbeautify
```

The first Simulator boot on a new Mac takes about 90 seconds, so give the first test run a longer timeout. A crash leaves its report in `~/Library/Logs/DiagnosticReports`.

## 4 Look at the app

`simulator-use` is on every Mac. `simulator-use run` builds, installs and launches the project in the current folder, `simulator-use look` reads the screen as text, and `simulator-use act 'tap "Sign In"'` taps by label.

- `screenshot_mac` with target `simulator` returns the Simulator's screen as an image, and `xcrun simctl io booted screenshot shot.png` saves one.
- Launch arguments open a screen without tapping: `xcrun simctl launch booted com.acme.App -ShowPaywall YES`.

## 5 Get the results back

`nomac pull ./out --from build/export` copies a folder to your machine. Over MCP, `create_mac_link` with direction `download` makes a link to a file or folder of up to 2 GiB that keeps working after the Mac stops, and `read_mac_file` reads a file of up to 3 MiB.

## Your backend

Run it on the Mac with `nomac-service start api -- npm run dev`. The Simulator reaches it at `http://localhost:PORT`, and `nomac ssh --forward 8787:8787` reaches it from your machine.

Apple Intelligence is not available in a virtual Mac. Test on-device generation on a device, and give the app a stand-in model here.