# iPhone, Mac and Electron apps

> Upload iPhone simulator builds and connect desktop apps built on Electron.

Source: https://rehearsal.dev/docs/cli/native-apps

Besides web apps, Rehearsal tests desktop apps built on Electron, on your own computer. iPhone apps are not available yet, although the CLI can already upload a simulator build. This page covers the upload first, then both ways to connect an Electron app.

## Which one you need

| Your app | What you do | Where it runs |
| --- | --- | --- |
| An Electron app on your Mac | Connect it with `rehearsal connect electron` | On your Mac, a fresh copy for each session and test, while the command runs |
| An Electron app that runs now, or one on Windows or Linux | Connect its window with `rehearsal connect electron --window` | In that window, while the command runs. Saved tests do not run there. |
| An iPhone app | Upload a simulator build with `rehearsal builds upload`, which Rehearsal cannot check yet | Not available yet |

## iPhone apps

> [!WARNING]
> **Not available yet**
>
> Testing iPhone apps is not available yet. You can upload a simulator build, but Rehearsal cannot check it. `rehearsal builds upload` exits `5` and says the build was not checked, and no exploration can install it.

An iPhone app starts from a build rather than a URL. An exploration installs only a build that Rehearsal has checked and accepted.

1. **Make a simulator build**

   Rehearsal takes a zipped `.app` from Xcode, Flutter or React Native, or the `.tar.gz` that an Expo simulator build makes, up to 500 MB. Xcode leaves the `.app` as a folder, so zip it first:

   ```sh
   ditto -c -k --keepParent Parcel.app Parcel.zip
   ```

2. **Upload it**

   ```sh
   rehearsal builds upload Parcel.zip
   ```

   ```text
   Uploaded Parcel.zip, 48 MB.
   Rehearsal accepted the build.
   App: Parcel
   Version 1.4, build 12
   Bundle id: com.example.parcel
   Build: <build-id>
   ```

   The command waits while Rehearsal checks the build, then says what it found. The first build of an app adds the app to your project, named from the build. A later build joins that app by its bundle id, or you can name the app with `--app Parcel`.

   The build goes to the workspace and project this repository is set to with `rehearsal init`. Outside such a repository, the CLI uses your only workspace and project, or lets you pick each with the arrow keys and prints the ones it used. A script or an agent has nobody to ask, so when you have more than one it names them with `--workspace` and `--project`.

   When Rehearsal refuses a build, it says why in one sentence. A build made for real iPhones is refused with the command that makes a simulator build in the tool you used, such as `xcodebuild -sdk iphonesimulator` for Xcode.

3. **Explore it**

   ```sh
   rehearsal explore --app Parcel --focus "Check saved cards"
   ```

   An exploration installs the newest build of the app that Rehearsal accepted. To explore another one, find it with `rehearsal builds list --app Parcel` and pass it with `--build <build-id>`.

A coding agent can read your builds with `list_builds` and `show_build` and choose one for `explore`. Only [`rehearsal builds upload`](https://rehearsal.dev/docs/reference/cli-builds.md) can send the file.

Tests do not run on a phone either, so Rehearsal cannot write a test from a bug found on one. `bugs reproduce` and `bugs verify` turn such a bug away.

## Electron apps on your Mac

An Electron app runs on your computer, so Rehearsal reaches it through a connection from there. Give `rehearsal connect electron` the app's path, and your Mac opens a fresh copy of the app for each session and each test you start.

```sh
rehearsal connect electron /Applications/Parcel.app
```

The path is the app's `.app` file, or its folder with Electron installed in it. With no path, the CLI asks which of the Electron apps in your Applications folders and in the current folder to connect. Then it asks which project in Rehearsal. Only its desktop apps are offered, and a project with none gets one named after the app.

The CLI opens the app once to read the URL its first window shows. Rehearsal keeps that URL as your own environment of the app. The terminal then shows a live panel until you press `Ctrl+C`.

Your Mac runs only what you start. A teammate's run, a schedule or a GitHub check never opens the app on your computer.

> [!WARNING]
> **Two limits for now**
>
> A fresh copy works on a Mac only. One desktop app connects from a computer at a time, so stop one before you connect another.

Connecting needs **Manage projects** in the workspace. It also needs the `tunnel` and `hosts` scopes, which `rehearsal login` gives unless you name other scopes.

### In the background

```sh
rehearsal connect electron /Applications/Parcel.app --detach
```

`--detach` keeps the connection in the background and returns once Rehearsal hears from your Mac. `rehearsal connect list` lists it, and `rehearsal connect stop` ends it.

## Connect a window instead

With `--window`, Rehearsal works in the window of an app that runs now, or of one the path or command starts. This works on any computer. Saved tests do not run in a window, so use it to explore an app while you build it. A window joins a desktop app the project already has, so connect the app by its path once first.

```sh
rehearsal connect electron --window
rehearsal connect electron --window "npm start --" --url http://localhost:5173
rehearsal connect electron --window --debug-port 9222
```

With no path, the CLI also offers apps that already run with a debugging port open. `--url` names the URL the window shows. Without it, the CLI uses the page the first window shows. `--debug-port` connects an app you started yourself with that port open.

Keep the terminal open, because a window cannot connect in the background. `Ctrl+C` closes the connection and quits an app the command started. An app you started yourself keeps running.

Connecting a window takes your environment of the app back from your Mac. Connecting the app by its path hands it to your Mac again.

## Stop and remove

Press `Ctrl+C` to disconnect. While a run uses the app, the first `Ctrl+C` says so and the second disconnects. To stop Rehearsal using a computer for good, remove it:

```sh
rehearsal connect list
rehearsal connect remove Studio
```

Run on that computer, `connect remove` also deletes the secret it saved. Connecting it again works as the first time did. With no name, it asks which of your computers to remove.

## Next steps

- [Test an app on your computer](https://rehearsal.dev/docs/cli/connect-a-local-app.md): Everything about connections, from the panel to more than one port.
- [Find and fix bugs with your coding agent](https://rehearsal.dev/docs/cli/coding-agents.md): Let your agent explore the app, fix what it finds and check the fix.
- [Build commands](https://rehearsal.dev/docs/reference/cli-builds.md): Every flag of builds upload, builds list and builds show.
- [Connect commands](https://rehearsal.dev/docs/reference/cli-connect.md): Every flag of connect electron, connect list, connect stop and connect remove.
