> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Testing

> Run Autosana flows on your local simulator, emulator, device, or browser

Have Autosana verify that your code actually works — on your local simulator, emulator, physical phone, or web browser, against your dev environment with hot reload, no build uploads needed.

## Prerequisites

* [Autosana MCP server](/mcp-setup) added to your coding agent
* One local target:
  * **iOS Simulator**: macOS with the Simulator booted
  * **Android Emulator**: macOS, Linux, or Windows with the emulator booted
  * **Physical Android device**: a connected device with USB debugging allowed
  * **Physical iPhone**: macOS with Xcode and a trusted, unlocked iPhone in Developer Mode — connected over **USB or Wi-Fi** (see [Wireless (Wi-Fi) iPhone](#wireless-wi-fi-iphone) for the one-time wireless setup)
  * **Web**: a local dev server running on any OS (e.g. `localhost:3000`). HTTP and HTTPS dev servers are both supported — the scheme is auto-detected. Frameworks like `next dev --experimental-https`, `vite --https`, and mkcert-based setups work out of the box.

## Usage

Tell your coding agent (Cursor, Claude Code, etc.):

```
Test this new feature locally using Autosana
```

Everything else — CLI setup, dependencies, tunnel — is handled automatically.

## Run code-managed flows from the CLI

If you keep your tests as code ([code-managed flows](/code-managed-flows) — YAML under `.autosana/`), you can run the flow you're **currently editing** directly on a local simulator, without a coding agent and without pushing:

```bash theme={null}
# Boot a local session once
autosana up --platform ios

# Run your working-copy flow on it — no commit, no push, no cloud device
autosana run login --local

# ...or a whole suite (its setup_flow runs on the device first)
autosana run --suite checkout --local
```

`autosana run` is shorthand for `autosana flows run`, and it runs your **uncommitted** `.autosana/` YAML — so the loop is: edit `.autosana/login.flow.yaml`, run `autosana run login --local`, and watch it execute on your simulator.

Targeting uses sensible defaults, so the everyday command is just `autosana run <flow> --local`:

* **App** — `--bundle-id`, else the `AUTOSANA_BUNDLE_ID` environment variable, else your organization's single app for the platform.
* **Platform** — taken from your `up` session; pass `--platform` only when you have sessions for both iOS and Android.
* **[Environment](/environments)** — `--environment <name>` selects the [variable set](/variables) your flows resolve `${env:…}` references against (required when one app spans multiple environments).

<Note>
  Local runs execute your flow's **instructions**. [Hooks](/hooks) are not run locally — they manipulate the environment, not the device — so use a suite's `setup_flow` for any on-device setup. Mobile only (iOS/Android) for now.
</Note>

## Physical Device Local Testing

Use this when you need Autosana to control a real phone connected to your computer. Android devices use the same local testing path as Android Emulators. Physical iPhones need the stricter iPhone readiness checks below.

Tell your coding agent:

```text theme={null}
Test this on my physical device using Autosana local testing
```

Your agent should handle the setup, device detection, readiness checks, recovery, and flow execution. You should not need to copy internal connection details by hand.

Keep the device ready while the flow runs:

* Keep it awake, unlocked, and on the app being tested (Android over USB stays plugged in; a Wi-Fi iPhone stays on the same network as your Mac)
* For Android, allow USB debugging when prompted
* For iPhone, keep Developer Mode enabled and leave the Mac trusted
* For iPhone, use a longer Auto-Lock interval, or temporarily set Auto-Lock to Never while testing
* Do not lock an iPhone from iPhone Mirroring during a run

Autosana only runs on real screenshots from the device. If an iPhone display turns off or screenshots go black, the run stops with an actionable error instead of letting the agent continue blind.

### Wireless (Wi-Fi) iPhone

A physical iPhone connected only over Wi-Fi works the same way — your agent auto-detects the wireless connection and handles WebDriverAgent setup for you. There's a one-time setup, done in Apple's tools:

1. Plug the iPhone into your Mac once over USB and pair/trust it.
2. In Xcode → **Window → Devices and Simulators**, enable **"Connect via network"** for the device. After that you can unplug the cable.
3. Trust the developer certificate on the device when prompted: **Settings → General → VPN & Device Management** → tap your "Apple Development" entry → **Trust**.
4. Make sure **Developer Mode** is on (Settings → Privacy & Security → Developer Mode).

After that, just ask your agent to test on the device — no cable needed.

Wireless tips:

* Keep the iPhone on the **same Wi-Fi network** as your Mac, unlocked, with the screen on. Setting **Auto-Lock to Never** matters more here: the first WebDriverAgent build can take \~30-60 seconds, and a screen that locks mid-setup will interrupt it (your agent will tell you to unlock and retry).
* The first session builds and installs WebDriverAgent (slower); later sessions reuse the cached build and start quickly.
* Wireless is slower than USB and a bit more sensitive to network hiccups; for long unattended runs a cable is still the most reliable.

If something fails, ask your agent to check the local Autosana status and recover the session:

```text theme={null}
Check my physical device Autosana local status and recover it if needed
```

The agent uses Autosana's local status checks before running. A physical iPhone session is ready only when Autosana has proven both device control and non-black screenshots.

Physical iPhones are not part of multi-device auto-detection yet. Android devices are detected with the other Android targets. If more than one device is connected, your agent may ask you which one to use.

## Multi-Device Parallel Testing

Run the same flow across multiple devices at the same time — different screen sizes, OS versions, or just faster coverage.

### How it works

1. **Boot your devices** — open multiple iOS Simulators, Android Emulators, or both
2. **Tell your agent** what to test:

```
Test my app on all my simulators in parallel
```

3. The Autosana CLI **auto-detects all booted devices**, starts a separate session for each (with its own tunnel and Appium server), and runs your flows simultaneously across all of them
4. **Results come back per-device** — you see pass/fail for each device independently, with links to the run details on the dashboard

### What gets auto-detected

* **iOS**: All booted Simulators (via `xcrun simctl`)
* **Android**: All connected emulators and devices (via `adb`)

Physical iPhones are not part of multi-device auto-detection yet. Connected Android devices are included with Android targets.

No manual device configuration needed — boot the simulators you want, and the agent handles the rest.

### Example use cases

* **Screen size coverage**: Run the same flow on iPhone SE, iPhone 16 Pro, and iPad to verify layouts across screen sizes
* **OS version testing**: Boot simulators on iOS 17 and iOS 18 to catch version-specific bugs
* **Cross-platform**: Test on both an iOS Simulator and Android Emulator in a single run

## Close the Loop

The real power of local testing: your coding agent can build, test, and fix in a single loop.

Give your coding agent a task — a feature, a bug fix, a ticket:

```
Build <feature>. Test it locally using Autosana and fix anything that fails.
```

It writes the code, Autosana verifies it actually works on your simulator, and the agent fixes whatever breaks — looping until everything passes. With hot reload, the whole cycle takes seconds.

```
Task
  ↓
Agent writes code
  ↓
Autosana verifies it on simulator/emulator/browser
  ↓
Pass → next task
Fail → agent reads results, fixes bug → ↑ retest
```