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.

1Put 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 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.

2Build and launch

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.

3Run the tests

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.

In CI

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 does the same on any runner and posts the result on the pull request.