# Run your app and tests

From your repository or folder to the app running on the phone, built with Xcode 27.1. Your agent gets the app's first screen and the test results, and the next build is incremental.

## 1. Put the project on the phone

The project goes into the account's workspace, shared only by phones with the same label. Only what changed is written.

From git `phone_app_run` with `git`, an https link. `path` is the project's folder in it, `ref` a branch, tag or commit.

From your folder, over NoMac's CLI MCP `local_path` sends the folder in the same call, only the files the phone lacks.

From your folder, anywhere else `phone_upload_link` answers one shell command that packs the folder and sends it. Then pass the `upload` it answered.

From a terminal After `simulator-use cloud start`, `simulator-use run` sends and runs the project in the current folder.

A private repository on github.com, gitlab.com or bitbucket.org needs a token: `secret` names one of the account's [secrets](/content/docs/session/secrets/index.html) that holds it, or `token` sends it with the call, used for that fetch and kept nowhere. Never paste a token into a chat: `request_secret` gives the person a link to enter it.

## 2. Build and launch

MCP call

```
phone_app_run  { "git": "https://github.com/acme/app", "path": "ios", "scheme": "App" }
```

It builds the project for the Simulator, installs it, launches it and answers with its first screen as text. Build errors come back as `file:line`. A build past 40 seconds answers with a job that `phone_job_status` waits for. Later runs reuse the project, so a one-line change rebuilds and runs in about 7 seconds.

- scheme The only scheme, or the one named like the project, by default.
- configuration Debug by default.
- env The app's launch variables, as `"API_URL=https://staging.example MODE=test"`, read from `ProcessInfo`. Kept for relaunches until the phone stops; `""` clears them.
- permissions iOS's permission prompts are answered by default; `ask` leaves them for the app to show.

- CocoaPods projects build too: `pod install` runs first when the pods differ from `Podfile.lock`, keeping its versions. XcodeGen projects are regenerated from `project.yml`.
- Expo, React Native, Flutter and Capacitor apps: build the Simulator `.app` with their own tools, then install it with `phone_app_control`.

## 3. Run the tests

MCP call

```
phone_tests_run  { "scheme": "App", "only": "AppTests/SignInTests" }
```

XCTest and XCUITest, read from Xcode's result bundle: the counts, and each failure as `file:line`. "0 tests ran" is an error, not a pass. `only` picks tests, separated by commas.

A build fails on the phone as it would on your Mac, so read its `file:line` errors first. `phone_app_logs` shows what the app printed, and with `crashes`, its crash reports.

## In CI

Terminal

```
simulator-use cloud run . --tests
```

One line: a phone starts, the project is built, run and tested, a screenshot and a recording are saved, and the phone stops. On GitHub, the [simulator-use Action](https://github.com/NoMac-app/simulator-use) does the same on any runner and posts the result on the pull request.