How to Test Mobile Apps with Kane CLI

Kane CLI runs tests on mobile virtual devices: Apple’s iOS Simulator and Google’s Android Emulator. You write and run mobile tests the same way as browser tests. Two things differ: a mobile test runs against an app you provide, and it targets a simulator or emulator instead of a browser. The virtual device can run in one of two places:

	Where the device runs	Host requirement	How
Local	A simulator or emulator on your machine	macOS on Apple Silicon (arm64) with Xcode and/or Android Studio	`kane-cli run … --target emulator\|simulator`, `kane-cli testmd run`, `kane-cli testrun run`
Cloud grid	A virtual device on a HyperExecute macOS host	Any machine: Linux, Windows, Intel or Apple Silicon Mac, no mobile tooling needed. Your TestMu AI plan must include HyperExecute with macOS runners	`kane-cli testrun run … --remote`. See Remote Runs

Local mobile runs need macOS on Apple Silicon (arm64). Intel Macs, Linux, and Windows cannot boot the simulator or emulator locally. On those hosts, run mobile suites on the cloud grid with --remote. The setup sections below are for the local path.

What Mobile Means Here

Native app testing. A mobile test drives an installed app. Pass a build, or the app id of an earlier upload, with --app. Kane CLI installs the app on the device and runs your objective against it. WebViews inside the app are supported.

Mobile runs target a native app. Pointing a mobile run at a website or mobile web page is not supported.

Two targets. emulator is a virtual Android device and simulator is a virtual iOS device. The default target is desktop, the browser, so your existing web runs are unaffected.

Why a Single Architecture for Local Runs

Apple Silicon runs both mobile stacks natively. The iOS Simulator is a first-class Apple target, and Android ships arm64-v8a emulator images that run on the Mac’s built-in hypervisor with hardware acceleration. Using one host architecture keeps local setup predictable and runs fast, because nothing has to be translated between CPU architectures. Other hosts reach the same devices through the cloud grid, where the grid’s macOS runners boot them.

How Setup Works

Setup has two parts. You handle the first, and Kane CLI handles the second. 1. You provide the virtual device. Install Xcode (Apple) or Android Studio (Google). For Android, also create one virtual device. These are the standard tools Apple and Google ship for simulators and emulators. 2. Kane CLI installs its own test tooling and drives the device. Sign in and run one command:

kane-cli login
kane-cli doctor --target simulator --install    # or --target emulator

This downloads the test tooling that Kane CLI manages for you. After that, Kane CLI finds the device, boots it, installs your app, and runs the test. You never boot the simulator or emulator by hand. Run kane-cli doctor --target emulator|simulator at any time to check what is ready and what is missing. It prints one line per required check, each with a fix. kane-cli devices list --target emulator|simulator lists the devices Kane CLI can run against.

Prerequisites

Target	Virtual device	You install	App formats
iOS	iOS Simulator	Xcode, the full app, version 16 or newer	`.zip` build, or an uploaded app id
Android	Android Emulator	Android Studio or the Android SDK, plus one `arm64-v8a` AVD	`.apk` build, or an uploaded app id

An uploaded app id is APP followed by six or more digits. Both targets require macOS on Apple Silicon and a one-time kane-cli doctor --target emulator|simulator --install. Set up only the platforms you plan to test. --remote runs need none of this.

Setup

Prefer not to set up a local device? kane-cli testrun run … --remote runs the same mobile tests on a virtual device on a HyperExecute macOS host, from any machine and with none of the steps below. See Running a Mobile Suite on the Cloud Grid.

Follow the tab for each platform you plan to test.

iOS Simulator
Android Emulator

The iOS runtime versions and simulator models on this page are working examples, not the full list of supported versions. Confirm that a specific version is officially supported before you depend on it.

Step 1: Install Xcode 16 or Newer

Install the full Xcode app from the Mac App Store. The standalone Command Line Tools are not enough. Kane CLI requires Xcode 16 or newer, which bundles the iOS Simulator, the simctl tool, and at least one iOS runtime. The download is large, several GB, so allow time on the first install.Launch Xcode once after installing so it can finish installing its additional components.

Step 2: Point the Command Line Tools at Xcode

Kane CLI talks to the simulator through Apple’s simctl, which ships inside Xcode. Make sure the developer directory resolves to the full Xcode install, not the standalone Command Line Tools:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept   # accept the license non-interactively

Confirm Xcode and simctl are reachable:

xcodebuild -version                # should report 16.x or newer
xcrun simctl list devices available

You should see one or more iOS devices grouped under an iOS runtime. Xcode ships with default simulators. If none are listed, add one from Xcode → Settings → Platforms, or Xcode → Window → Devices and Simulators.

Step 3: Install the Kane CLI Test Tooling

kane-cli login
kane-cli doctor --target simulator --install

You never boot a simulator yourself. Kane CLI finds the simulator, boots it, installs your app, and runs the test.

Ready Check

Confirm Kane CLI sees a ready iOS toolchain and, optionally, the simulators on your machine:

kane-cli doctor --target simulator          # required checks, each with a fix if it fails
kane-cli devices list --target simulator    # the simulators Kane CLI can run against

When the iOS checks pass, setup is complete. To use a simulator in a run, pass --device-name "<name>" --os-version <v> with the values exactly as the list prints them.

The values on this page, API 35 and the Pixel device profile, are working examples, not the full list of supported Android API levels and device profiles. Confirm that a specific one is officially supported before you depend on it.

On Apple Silicon, always use an arm64-v8a system image. The x86 and x86_64 images do not run natively and are effectively unusable. This is the single most common setup mistake.

Step 1: Install Android Studio

Kane CLI does not ship an Android SDK, emulator, or system image. Install Android Studio, which bundles the Android SDK, the emulator, the system image manager, and the Device Manager. Download it from the Android developer site and run the first-launch setup wizard, which installs the SDK and platform-tools.If you prefer a headless setup, install the command line SDK tools and use sdkmanager and avdmanager directly.

Step 2: Install an arm64 System Image

Install a system image with the arm64-v8a ABI. In the Android Studio SDK Manager, tick an API level image whose ABI is arm64-v8a. From the command line:

sdkmanager "system-images;android-35;google_apis;arm64-v8a"

Step 3: Create a Virtual Device (AVD)

Kane CLI runs against an Android Virtual Device (AVD) that already exists. It does not create one for you, so create an AVD from the image you installed. In Android Studio, use Device Manager → Create Device and pick the arm64 image. From the command line:

avdmanager create avd -n kane_pixel \
  -k "system-images;android-35;google_apis;arm64-v8a" \
  -d pixel

Step 4: Point Kane CLI at a Non-Default SDK Location (Only If Needed)

Kane CLI brings its own managed adb, so platform-tools and adb do not need to be on your PATH. Kane CLI only has to find the emulator binary and your AVDs. It looks for them in the default SDK location, ~/Library/Android/sdk. If your SDK is somewhere else, point Kane CLI to it:

export ANDROID_HOME="/path/to/your/Android/sdk"   # only if not the default location

If your SDK is at the default path, skip this step.

Step 5: Install the Kane CLI Test Tooling

kane-cli login
kane-cli doctor --target emulator --install

You never boot the emulator or run adb yourself. Kane CLI finds the AVD, boots it, installs your app, and runs the test.

Ready Check

Confirm Kane CLI sees a ready Android toolchain and, optionally, the AVDs on your machine:

kane-cli doctor --target emulator          # required checks, each with a fix if it fails
kane-cli devices list --target emulator    # the emulators Kane CLI can run against

When the Android checks pass and your AVD appears in the list, setup is complete. To use the AVD in a run, pass --device-name "<name>" --os-version <v> with the values exactly as the list prints them.

Running a Mobile Test Locally

Once a target is set up, point a run at it:

# one-off, from the command line
kane-cli run "Sign in and open the account tab" --target simulator --app ./builds/MyApp.zip

# or set a default target once, then just run
kane-cli config set-target emulator
kane-cli run "Add the first item to the cart" --app ./builds/app-debug.apk

# a saved test, or a whole suite of them
kane-cli testmd run tests/checkout_test.md
kane-cli testrun run --match '^tests/app/' --device-name "Pixel 7 API 35" --os-version 15

Choose a device with --device-name and --os-version, using the values exactly as kane-cli devices list --target emulator|simulator prints them. To save defaults, use kane-cli config set-device-name and kane-cli config set-os-version. A device name must be paired with an OS version. An OS version on its own matches any device running that version. In the TUI or an interactive terminal, if you leave out the device flags, Kane CLI opens a one-time picker and saves your choice. A non-interactive run, such as one in CI, needs the device set in advance with the flags or the two config commands above. Otherwise the run exits and prints the fix. Every mobile run requires --app:

The simulator target accepts a .zip build.
The emulator target accepts an .apk build.
Both accept an uploaded app id: APP followed by six or more digits. kane-cli apps list --target emulator|simulator lists the uploaded builds your account can use.

On the desktop target, Kane CLI ignores the device flags and --app. In the interactive TUI, the first run offers a choice of Desktop, Emulator, or Simulator. You can switch targets with /mobile and /desktop until you send the first objective. After that, run /new before you switch. Run /doctor to check your mobile tooling and devices. For the full flag list, see the CLI Reference and Mobile Runs. To save a default target, device, and app instead of passing flags every time, see Configuration. To set the target, app, and device inside a test file, see Test.md. To run a folder of mobile tests, see Batch Runs.

Running a Mobile Suite on the Cloud Grid

You can skip the local setup entirely. kane-cli testrun run --remote sends your mobile _test.md files to HyperExecute. HyperExecute boots a virtual device on a macOS host, installs the app, runs the suite, and returns the recordings and evidence pack to your project. Anyone on the team can write and run mobile tests this way, from any operating system.

kane-cli plugin install remote-execution                              # once
kane-cli devices list --target emulator --remote                      # what the grid can provision
kane-cli testrun run --match '^tests/app/' --remote --device-name "Pixel 7" --os-version 14 --dry-run
kane-cli testrun run --match '^tests/app/' --remote --device-name "Pixel 7" --os-version 14

Three things differ from a local run:

The device comes from the grid catalog, not from the AVDs or simulators on your machine. List the catalog with kane-cli devices list --target emulator|simulator --remote.
One job runs one platform. Emulator members run on one Android version, and simulator members run on one HyperExecute pool.
A local build is uploaded from your machine before the job is sent, and the grid receives it as an APP… id.

The prerequisites, the app rules, and what one job can hold are covered in Remote Runs on the Cloud Grid.

Evidence for a Mobile Run

The result summary records the device in the run environment, such as the device model and OS version. The per-step logs include device logs from the emulator or simulator, next to the usual browser logs.

Common Failures

Platform	Symptom	Cause	Fix
iOS	`doctor` reports Xcode is too old	Xcode older than 16	Update Xcode to 16 or newer from the App Store
iOS	`xcrun: error: unable to find utility "simctl"`	Developer directory points at the standalone Command Line Tools, not Xcode	Run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`
iOS	`doctor` reports no developer directory	Full Xcode not installed, or never launched	Install Xcode from the App Store, launch it once, then run `xcode-select --install`
iOS	“No iOS simulator found” when picking a device	No simulator device exists yet	Add one in Xcode → Window → Devices and Simulators, then reopen the list
Android	Emulator boots extremely slowly or hangs	An x86 or x86_64 image on Apple Silicon	Recreate the AVD from an `arm64-v8a` system image
Android	`doctor` cannot find the emulator, or “No Android emulator found” when picking a device	SDK in a non-default location, or no AVD created yet	Set `ANDROID_HOME`, and create an AVD in Android Studio → Device Manager
Android	Prompts to install Intel HAXM	Following an Intel Mac guide	Not needed on Apple Silicon. It uses the built-in Hypervisor.framework, so skip HAXM

Next Steps

Remote Runs on the Cloud Grid to run mobile suites from any machine
CLI Reference for the full flag and command list
Configuration to save a default target, device, and app
Batch Runs to run a suite of mobile tests
Troubleshooting for wider setup and run problems

​What Mobile Means Here

​Why a Single Architecture for Local Runs

​How Setup Works

​Prerequisites

​Setup

​Step 1: Install Xcode 16 or Newer

​Step 2: Point the Command Line Tools at Xcode

​Step 3: Install the Kane CLI Test Tooling

​Ready Check

​Step 1: Install Android Studio

​Step 2: Install an arm64 System Image

​Step 3: Create a Virtual Device (AVD)

​Step 4: Point Kane CLI at a Non-Default SDK Location (Only If Needed)

​Step 5: Install the Kane CLI Test Tooling

​Ready Check

​Running a Mobile Test Locally

​Running a Mobile Suite on the Cloud Grid

​Evidence for a Mobile Run

​Common Failures

​Next Steps

What Mobile Means Here

Why a Single Architecture for Local Runs

How Setup Works

Prerequisites

Setup

Step 1: Install Xcode 16 or Newer

Step 2: Point the Command Line Tools at Xcode

Step 3: Install the Kane CLI Test Tooling

Ready Check

Step 1: Install Android Studio

Step 2: Install an arm64 System Image

Step 3: Create a Virtual Device (AVD)

Step 4: Point Kane CLI at a Non-Default SDK Location (Only If Needed)

Step 5: Install the Kane CLI Test Tooling

Ready Check

Running a Mobile Test Locally

Running a Mobile Suite on the Cloud Grid

Evidence for a Mobile Run

Common Failures

Next Steps