Mobile Testing with Kane CLI
Kane CLI can run tests against mobile virtual devices: Apple's iOS Simulator and Google's Android Emulator. You author and run mobile tests the same way you already do for the browser. The differences are that a mobile test runs against an app you provide, and that the target device is a simulator or emulator instead of a browser.
There are two places that device can live:
| Where the device runs | What the machine needs | How to run | |
|---|---|---|---|
| Local | A simulator or emulator on your machine | macOS on Apple Silicon (arm64) with Xcode, Android Studio, or both | 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, or an Intel or Apple Silicon Mac, with no mobile tooling. Your TestMu AI plan must include HyperExecute with macOS runners | kane-cli testrun run … --remote, see Remote Runs |
Local mobile runs require macOS on Apple Silicon (arm64). Intel Macs, Linux, and Windows cannot boot the simulator or emulator locally. On those machines, run mobile suites on the cloud grid with --remote. The setup steps below cover the local path.
What Mobile Means Here
Native app testing. A mobile test drives an installed app. You pass a build, or an app id from a previous upload, with --app. Kane CLI installs it on the device and runs your objective against it. WebViews inside the app under test are handled.
Pointing a mobile run at a website is not supported yet. Mobile runs target a native app, not a mobile web page.
Two targets. emulator is a virtual Android device and simulator is a virtual iOS device. The default target stays desktop, the browser, so nothing changes for your existing web runs.
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.
Standardising on one host architecture keeps local setup predictable and runs fast, with no cross-architecture translation in the path. Other machines reach the same devices through the cloud grid, where the grid's macOS runners do the booting.
How Setup Works
There are two halves, and Kane CLI owns the second.
1. You provide the virtual device. Apple's and Google's own tooling, Xcode or Android Studio, supplies the simulator or emulator. These are the same tools Apple and Google already ship for building simulators and emulators. Kane CLI does not ship an iOS runtime, an Android SDK, an emulator, or a system image.
2. Kane CLI installs its own test tooling and drives the device. After a one-time kane-cli doctor --target emulator|simulator --install, covered in Setup below, Kane CLI discovers the device, boots it, installs your app, and runs the test. You do not 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 provide | App formats |
|---|---|---|---|
| iOS | iOS Simulator | Xcode, the full app, version 16 or newer. The standalone Command Line Tools are not enough | .zip build, or an uploaded app id |
| Android | Android Emulator | Android Studio or the command line Android SDK tools, 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 platform you intend to test, or both if you test on both. None of this is needed for --remote runs.
Setup
Prefer not to set up a device on your machine? 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 Remote Runs.
Step 1: Prepare the Virtual Device
Follow the tab for the platform you intend to test. Set up both if you test on both.
- iOS Simulator
- Android Emulator
The exact iOS runtime versions and simulator device models in the supported matrix are pinned by the product team. The versions shown below are current, working examples. Confirm the officially supported set before you rely on a specific one.
Point the Command Line Tools at Xcode
Kane CLI requires Xcode 16 or newer, which bundles the iOS Simulator, the simctl tool, and at least one iOS runtime. Kane CLI talks to the simulator through simctl, so 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.
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.
The exact Android API levels and device profiles in the supported matrix are pinned by the product team. The values shown below, API 35 and Pixel, are current, working examples. Confirm the officially supported set before you rely on a specific one.
Android Studio bundles the Android SDK, the emulator, the system image manager, and the Device Manager, which are the pieces the steps below use. If you prefer a headless setup, install the command line SDK tools instead and use sdkmanager and avdmanager directly.
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"
Create a Virtual Device
Kane CLI runs against an existing AVD. It does not create one for you. Create an Android Virtual Device from that image. 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
Point Kane CLI at a Non-Default SDK Location
This step is only needed if your SDK is not in the default location.
Kane CLI uses its own managed adb, so you do not need platform-tools or adb on your PATH. It only needs to find the emulator binary and your AVDs, which it looks for in the default SDK location ~/Library/Android/sdk. If your SDK lives somewhere else, point Kane CLI at it:
export ANDROID_HOME="/path/to/your/Android/sdk"
If your SDK is at the default path, skip this step.
Step 2: Install the Kane CLI Test Tooling
Sign in and let Kane CLI install the tooling it manages for the target you set up:
kane-cli login
kane-cli doctor --target simulator --install # or --target emulator
You do not need to boot a simulator, boot an emulator, or run adb yourself. Kane CLI discovers the device, boots it, installs your app, and runs the test.
Step 3: Ready Check
Confirm Kane CLI sees a ready toolchain and, optionally, the devices on your machine:
kane-cli doctor --target simulator # or --target emulator
kane-cli devices list --target simulator # the devices Kane CLI can run against
When the checks for your platform pass, setup is complete. On Android, confirm your AVD is listed by kane-cli devices list --target emulator. Address a device on a run with --device-name "<name>" --os-version <v>, as the list prints them.
Running a Mobile Test
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 folder of them
kane-cli testmd run tests/checkout_test.md
kane-cli testrun run tests/app/ --device-name "Pixel 7 API 35" --os-version 15
--app is required for every mobile run. The simulator target accepts a .zip build, the emulator target accepts an .apk build, and 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.
You also need a device. Pick it with --device-name and --os-version, as kane-cli devices list --target emulator|simulator prints them: a name needs a version, and a version on its own matches any device running it. In the TUI or an interactive terminal, leaving the device flags off opens a one-time picker and saves your choice. A non-interactive run, such as one in CI, needs a device already set with the flags or with kane-cli config set-device-name and kane-cli config set-os-version, or the run exits and prints the fix. On the desktop target, the device flags and --app are ignored.
In the interactive TUI, switch targets with /mobile and /desktop, and run /doctor to check mobile tooling and devices.
For the full flag list and the app formats each target accepts, see the CLI Reference. To save a default target, device, and app instead of passing flags every time, see Configuration. To run a mobile test from a file, see Test.md, and to run a folder of them, see Batch Runs.
Running a Mobile Suite on the Cloud Grid
kane-cli testrun run --remote sends your mobile _test.md files to TestMu AI HyperExecute, which 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 author and run mobile tests this way, from any operating system, with none of the local setup above.
kane-cli plugin install remote-execution # once
kane-cli devices list --target emulator --remote # what the grid can provision
kane-cli testrun run tests/app/ --remote --device-name "Pixel 7" --os-version 14 --dry-run
kane-cli testrun run tests/app/ --remote --device-name "Pixel 7" --os-version 14
Three things differ from a run on your own machine:
- The device comes from the grid catalog. List it with
kane-cli devices list --target emulator|simulator --remote, not from the AVDs or simulators on your machine. - 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 dispatch and handed to the grid as an
APP…id.
The prerequisites, the app rules, and what one job can hold are in Remote Runs.
Evidence for a Mobile Run
The result summary records the device in the run environment, for example the device model and OS version, and the per-step logs include device logs from the emulator or simulator alongside 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 to run mobile suites from any machine
- Batch Runs to run a folder of mobile tests as one execution
- CLI Reference for the full flag and command list
- Configuration to save a default target, device, and app
- Troubleshooting for wider setup and run problems
Chat with Us