How to Test Mobile Apps with Kane CLI

Kane CLI can run tests against local 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 on your machine.

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. 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 hosts get the same devices through the cloud grid instead, 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. Install Apple’s or Google’s tooling, Xcode or Android Studio, and for Android, create one virtual device. These are the same tools Apple and Google already ship for building 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 Kane CLI manages for you. From then on, 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 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. You only need to set up the platform you intend to test. Set up both if you test on both. None of this is needed for --remote runs.

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

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 do not need to boot a simulator yourself. Kane CLI discovers 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, your simulator setup is complete. Address a simulator on a run with --device-name "<name>" --os-version <v> as the list prints them.

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.

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 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

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

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"   # 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 do not need to boot the emulator or run adb yourself. Kane CLI discovers 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 is listed, your emulator setup is complete. Address it on a run with --device-name "<name>" --os-version <v> 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 tests/app/ --device-name "Pixel 7 API 35" --os-version 15

Pick a device with --device-name and --os-version as kane-cli devices list --target emulator|simulator prints them, or save defaults with kane-cli config set-device-name and kane-cli config set-os-version. A device name needs an OS version. An OS version alone matches any device on 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 the two config commands above, or the run exits with the fix spelled out. --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. On the desktop target, the device flags and --app are ignored. In the interactive TUI, a first run offers a Desktop, Emulator, or Simulator chooser. Switch targets at any time with /mobile and /desktop, and run /doctor to check 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

Skip the local setup entirely. kane-cli testrun run --remote sends your mobile _test.md files to 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.

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 local run:

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 covered in Remote Runs on the Cloud Grid.

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 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