diff --git a/docs/kane-cli-cli-reference.mdx b/docs/kane-cli-cli-reference.mdx index 23d993157..1eb63b3fe 100644 --- a/docs/kane-cli-cli-reference.mdx +++ b/docs/kane-cli-cli-reference.mdx @@ -57,45 +57,24 @@ kane-cli run "" [options] | Flag | Description | Default | |------|-------------|---------| | `--target ` | Which target to run against: `desktop`, `emulator`, or `simulator` | Saved session target, otherwise `desktop` | -| `--device-name ` | Pick a device as `kane-cli devices list --target emulator\|simulator` prints it. A name needs a version | Config value. When unset, a TTY run opens a one-time picker and saves the choice. Non-interactive runs require a device | -| `--os-version ` | The device's OS version, for example `14` or `17.5`. Alone, it matches any device on that version | Config value | +| `--device ` | Pick a device by name, serial, `ip:port`, or udid | TTY opens a one-time picker and saves the choice; non-interactive runs require it | | `--app ` | The app under test. A build (emulator `.apk`, simulator `.zip`) or an uploaded app id | Config value. Required for every mobile run | -On the `desktop` target, the device flags and `--app` are ignored. See [Mobile Testing](/docs/kane-cli-mobile/) for setup. +On the `desktop` target, `--device` and `--app` are ignored. See [Mobile Testing](/docs/kane-cli-mobile/) for setup. --- ### `kane-cli doctor` -Check the mobile tooling this machine needs for one target, `emulator` or `simulator`, and install the tooling Kane CLI manages for it. `--target` is required. +Check the mobile tooling on this machine, and install the tooling Kane CLI manages. ```bash -kane-cli doctor --target emulator # required checks, each with a fix if it fails -kane-cli doctor --target simulator --install # install the test tooling Kane CLI manages +kane-cli doctor # required checks, each with a fix if it fails +kane-cli doctor --install # install the test tooling Kane CLI manages +kane-cli doctor --targets # also list the emulators and simulators available ``` -`doctor` prints one line per required check, each with a fix. Run `kane-cli login` before `--install`. See [Mobile Testing](/docs/kane-cli-mobile/). - ---- - -### `kane-cli devices list` - -List the emulators or simulators Kane CLI can run against. `--target` is required. Address a device on a run with `--device-name` and `--os-version` as the list prints them. - -```bash -kane-cli devices list --target emulator # the emulators on this machine -kane-cli devices list --target simulator --remote # the simulators the cloud grid can provision -``` - ---- - -### `kane-cli apps list` - -List the uploaded builds your account can use for a target. The **APP ID** column is what `--app` and `kane-cli config set-app` accept. - -```bash -kane-cli apps list --target emulator -``` +`doctor` prints one line per required check. Run `kane-cli login` before `--install`. See [Mobile Testing](/docs/kane-cli-mobile/). --- @@ -173,8 +152,7 @@ kane-cli config chrome-profile [path] # Set Chrome profile (interactive pic kane-cli config project [id] # Set Test Manager project (interactive picker if no id) kane-cli config folder [id] # Set Test Manager folder (interactive picker if no id) kane-cli config set-target # Set run target: desktop | emulator | simulator -kane-cli config set-device-name # Set default mobile device, as kane-cli devices list prints it -kane-cli config set-os-version # Set the default mobile device's OS version +kane-cli config set-device # Set default mobile device kane-cli config set-app # Set default app under test for mobile runs ``` diff --git a/docs/kane-cli-configuration.mdx b/docs/kane-cli-configuration.mdx index 0c1c18e21..42bf09842 100644 --- a/docs/kane-cli-configuration.mdx +++ b/docs/kane-cli-configuration.mdx @@ -63,9 +63,8 @@ Empty fields are shown as `(none)`. The `chrome` path is empty by default, in wh | `folder_id` | string \| null | `null` | Test Manager folder ID for upload | `kane-cli config folder [id]` | | `folder_name` | string \| null | `null` | Display name of the selected folder | Set by `kane-cli config folder` | | `mode` | `"action"` \| `"testing"` | `"testing"` | Agent behaviour on auth walls, blocked pages, or error pages. | `kane-cli config set-mode ` | -| `target` | `"desktop"` \| `"emulator"` \| `"simulator"` | `"desktop"` | Default run target. `desktop` runs the Chrome browser, the default. `emulator` and `simulator` run against a virtual Android or iOS device on this machine (macOS Apple Silicon only). Other hosts use [`testrun run --remote`](/docs/kane-cli-mobile/#running-a-mobile-suite-on-the-cloud-grid). See [Mobile Target](#mobile-target). | `kane-cli config set-target ` | -| `device_name` | string \| null | `null` | Default mobile device, by the name `kane-cli devices list --target ` prints. Pairs with `os_version`. When empty, a TTY run prompts once and saves the choice. A non-interactive run needs `--device-name` or this key set. Ignored on the `desktop` target. | `kane-cli config set-device-name ` | -| `os_version` | string \| null | `null` | OS version of the default mobile device (`14`, `17.5`). Required alongside `device_name`. | `kane-cli config set-os-version ` | +| `target` | `"desktop"` \| `"emulator"` \| `"simulator"` | `"desktop"` | Default run target. `desktop` runs the Chrome browser; `emulator` and `simulator` run against a virtual Android or iOS device (macOS Apple Silicon only). See [Mobile Target](#mobile-target). | `kane-cli config set-target ` | +| `device` | string \| null | `null` | Default mobile device, by name, serial, `ip:port`, or udid. When empty, a TTY run prompts once and saves the choice; a non-interactive run needs `--device` or this key set. Ignored on the `desktop` target. | `kane-cli config set-device ` | | `app` | string \| null | `null` | Default app under test for mobile runs: a build path (`.apk` or `.zip`) or an uploaded app id. Ignored on the `desktop` target. | `kane-cli config set-app ` | | `bug_detection` | `"off"` \| `"stop"` \| `"continue"` | `"off"` | Whether the agent flags suspected product bugs while authoring. See [Bug detection](#bug-detection). | `kane-cli config set-bug-detection `, or per-run `--bug-detection` | | `code_export.enabled` | boolean | `false` | Generate code export after upload completes. | TUI menu, or `--code-export` flag | @@ -164,20 +163,19 @@ You can override the saved mode for a single run with `--mode ` ### Mobile Target -On macOS Apple Silicon, Kane CLI can run against a virtual mobile device on this machine instead of the desktop browser. Four settings persist the default target and how to reach it. They are a **separate axis** from `mode` above: `mode` tunes agent behaviour, while these choose *what device* a run drives. +On macOS Apple Silicon, Kane CLI can run against a virtual mobile device instead of the desktop browser. Three settings persist the default target and how to reach it. They are a **separate axis** from `mode` above: `mode` tunes agent behaviour, while these choose *what device* a run drives. ```bash -kane-cli config set-target emulator # desktop | emulator | simulator -kane-cli config set-device-name "Pixel 7 API 35" # as `kane-cli devices list --target emulator` prints it -kane-cli config set-os-version 15 +kane-cli config set-target emulator # desktop | emulator | simulator +kane-cli config set-device pixel-7 # name, serial, ip:port, or udid kane-cli config set-app ./builds/app-debug.apk ``` - **`target`**: `desktop`, the default, runs Chrome. `emulator` runs a virtual Android device and `simulator` a virtual iOS device. Existing web runs are unaffected. -- **`device_name`** and **`os_version`**: the device a mobile run selects, in the vocabulary of `kane-cli devices list --target `. A name needs a version. A version alone matches any device on it. When unset, a TTY run prompts once and saves the choice. Non-interactive runs need them set, either here or with `--device-name` and `--os-version`. -- **`app`**: the app under test for a mobile run, a build path (emulator `.apk`, simulator `.zip`) or an uploaded app id, `APP` followed by six or more digits. Required for every mobile run. On the `desktop` target, the device keys and `app` are ignored. +- **`device`**: the device a mobile run selects, by name, serial, `ip:port`, or udid. When unset, a TTY run prompts once and saves the choice. Non-interactive runs need it set, either here or with `--device`. +- **`app`**: the app under test for a mobile run, a build path (emulator `.apk`, simulator `.zip`) or an uploaded app id, `APP` followed by six or more digits. Required for every mobile run. On the `desktop` target, `device` and `app` are ignored. -A run reads these as its defaults. Override any of them for a single run with `--target`, `--device-name`, `--os-version`, and `--app`. Setup and the full list of accepted app formats are in [Mobile Testing](/docs/kane-cli-mobile/). These defaults describe *local* devices. A [`testrun run --remote`](/docs/kane-cli-mobile/#running-a-mobile-suite-on-the-cloud-grid) run names its device from the grid catalog with the same two flags. +A run reads these as its defaults. Override any of them for a single run with `--target`, `--device`, and `--app`. Setup and the full list of accepted app formats are in [Mobile Testing](/docs/kane-cli-mobile/). ### Bug detection diff --git a/docs/kane-cli-mobile-emulator.mdx b/docs/kane-cli-mobile-emulator.mdx deleted file mode 100644 index 6394f4af1..000000000 --- a/docs/kane-cli-mobile-emulator.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "How to Set Up Android Emulator for Kane CLI" -sidebarTitle: "Android Emulator Setup" -description: "Set up Google's Android Emulator so Kane CLI can run mobile tests on a virtual Android device on macOS Apple Silicon: install Android Studio and add an AVD." -keywords: ['kane cli android emulator', 'android emulator setup', 'arm64-v8a system image', 'avdmanager', 'kane cli doctor', 'mobile app testing'] -"og:description": "Set up Google's Android Emulator so Kane CLI can run mobile tests on a virtual Android device on macOS Apple Silicon: install Android Studio and add an AVD." ---- - -Set up Google's Android Emulator once, and Kane CLI can run mobile tests against it. This guide targets **macOS on Apple Silicon (arm64)**, the only supported host for this release. See [Mobile Testing](/docs/kane-cli-mobile/) for the full picture. - - -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. - - -## 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. - -## 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: - -```bash -sdkmanager "system-images;android-35;google_apis;arm64-v8a" -``` - -## 3. 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: - -```bash -avdmanager create avd -n kane_pixel \ - -k "system-images;android-35;google_apis;arm64-v8a" \ - -d pixel -``` - -## 4. 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: - -```bash -export ANDROID_HOME="/path/to/your/Android/sdk" - -``` - -If your SDK is at the default path, skip this step. - -## 5. Install the Kane CLI Test Tooling - -Sign in and let Kane CLI install the tooling it manages for the emulator: - -```bash -kane-cli login -kane-cli doctor --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: - -```bash -kane-cli doctor # required checks, each with a fix if it fails -kane-cli doctor --targets # also list the emulators Kane CLI can run against -``` - -When the Android checks pass and your AVD is listed, your emulator setup is complete. - -## Run a Test - -```bash -kane-cli run "Add the first item to the cart" --target emulator --app ./builds/app-debug.apk -``` - -The emulator target accepts an `.apk` build or an uploaded app id, `APP` followed by six or more digits. - -## Common Failures - -| Symptom | Cause | Fix | -|---------|-------|-----| -| Emulator boots extremely slowly or hangs | An x86 or x86_64 image on Apple Silicon | Recreate the AVD from an `arm64-v8a` system image | -| `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** | -| 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 - -- [iOS Simulator setup](/docs/kane-cli-mobile-simulator/) -- [Mobile Testing overview](/docs/kane-cli-mobile/) diff --git a/docs/kane-cli-mobile-simulator.mdx b/docs/kane-cli-mobile-simulator.mdx deleted file mode 100644 index 4dd21f104..000000000 --- a/docs/kane-cli-mobile-simulator.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "How to Set Up iOS Simulator for Kane CLI" -sidebarTitle: "iOS Simulator Setup" -description: "Set up Apple's iOS Simulator so Kane CLI can run mobile tests on a virtual iOS device on macOS Apple Silicon: install Xcode 16+ and point the CLI tools at it." -keywords: ['kane cli ios simulator', 'ios simulator setup', 'xcode simctl', 'kane cli doctor', 'mobile app testing'] -"og:description": "Set up Apple's iOS Simulator so Kane CLI can run mobile tests on a virtual iOS device on macOS Apple Silicon: install Xcode 16+ and point the CLI tools at it." ---- - -Set up Apple's iOS Simulator once, and Kane CLI can run mobile tests against it. This guide targets **macOS on Apple Silicon (arm64)**, the only supported host for this release. See [Mobile Testing](/docs/kane-cli-mobile/) for the full picture. - - -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. - - -## 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. - -## 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: - -```bash -sudo xcode-select -s /Applications/Xcode.app/Contents/Developer -sudo xcodebuild -license accept # accept the license non-interactively -``` - -Confirm Xcode and `simctl` are reachable: - -```bash -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**. - -## 3. Install the Kane CLI Test Tooling - -Sign in and let Kane CLI install the tooling it manages for the simulator: - -```bash -kane-cli login -kane-cli doctor --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: - -```bash -kane-cli doctor # required checks, each with a fix if it fails -kane-cli doctor --targets # also list the simulators Kane CLI can run against -``` - -When the iOS checks pass, your simulator setup is complete. - -## Run a Test - -```bash -kane-cli run "Sign in and open the account tab" --target simulator --app ./builds/MyApp.zip -``` - -The simulator target accepts a `.zip` build or an uploaded app id, `APP` followed by six or more digits. - -## Common Failures - -| Symptom | Cause | Fix | -|---------|-------|-----| -| `doctor` reports Xcode is too old | Xcode older than 16 | Update Xcode to 16 or newer from the App Store | -| `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` | -| `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` | -| "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 | - -## Next Steps - -- [Android Emulator setup](/docs/kane-cli-mobile-emulator/) -- [Mobile Testing overview](/docs/kane-cli-mobile/) diff --git a/docs/kane-cli-mobile.mdx b/docs/kane-cli-mobile.mdx index 0edbb0771..719463464 100644 --- a/docs/kane-cli-mobile.mdx +++ b/docs/kane-cli-mobile.mdx @@ -1,18 +1,17 @@ --- title: "How to Test Mobile Apps with Kane CLI" sidebarTitle: "Mobile Testing" -description: "Run Kane CLI tests on mobile virtual devices, locally on macOS Apple Silicon or on the cloud grid from any machine. Set up the iOS Simulator or the Android Emulator and drive a native app." -keywords: ['kane cli mobile', 'kane cli emulator', 'kane cli simulator', 'kane cli ios simulator', 'kane cli android emulator', 'mobile app testing', 'android emulator testing', 'ios simulator testing', 'ios simulator setup', 'android emulator setup', 'xcode simctl', 'arm64-v8a system image', 'avdmanager', 'kane cli doctor', 'kane cli devices list', 'kane cli testrun remote', 'hyperexecute mobile', 'kaneai', 'testmu ai'] -"og:description": "Run Kane CLI tests on mobile virtual devices, locally on macOS Apple Silicon or on the cloud grid from any machine. Set up the iOS Simulator or the Android Emulator and drive a native app." +description: "Run Kane CLI tests against local mobile virtual devices. Set up the iOS Simulator or the Android Emulator, then drive a native app on macOS Apple Silicon." +keywords: ['kane cli mobile', 'kane cli emulator', 'kane cli simulator', 'kane cli ios simulator', 'kane cli android emulator', 'mobile app testing', 'android emulator testing', 'ios simulator testing', 'ios simulator setup', 'android emulator setup', 'xcode simctl', 'arm64-v8a system image', 'avdmanager', 'kane cli doctor', 'kaneai', 'testmu ai'] +"og:description": "Run Kane CLI tests against local mobile virtual devices. Set up the iOS Simulator or the Android Emulator, then drive a native app on macOS Apple Silicon." --- import { KaneCliCta } from "/snippets/KaneCliCta.mdx"; -import { BrandName } from "/snippets/BrandName.mdx"; 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. +This release supports **macOS on Apple Silicon (arm64) only**. Mobile testing is not yet available on Intel Macs, Linux, or Windows. Everything below assumes a mac-arm64 host. ## What Mobile Means Here @@ -25,45 +24,36 @@ Pointing a mobile run at a website is not supported yet. Mobile runs target a na **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 +## Why a Single Architecture 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. +Standardising on one host architecture for the first release keeps setup predictable and runs fast, with no cross-architecture translation in the path. Support for other hosts will follow in a later release. ## 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. +**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.** Sign in and run one command: +**2. Kane CLI installs its own test tooling and drives the device.** After a one-time `kane-cli doctor --install`, covered in [Setup](#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. -```bash -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. +Run `kane-cli doctor` at any time to check what is ready and what is missing. It prints one line per required check, each with a fix. ## Prerequisites -| Target | Virtual device | You install | App formats | +| Target | Virtual device | You provide | 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 | +| 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`. 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. +Both targets require macOS on Apple Silicon and a one-time `kane-cli doctor --install`. ## 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](#running-a-mobile-suite-on-the-cloud-grid). - +### Step 1: Prepare the Virtual Device Follow the tab for the platform you intend to test. Set up both if you test on both. @@ -74,15 +64,9 @@ Follow the tab for the platform you intend to test. Set up both if you test on b 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 +#### Point the Command Line Tools at Xcode -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: +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: ```bash sudo xcode-select -s /Applications/Xcode.app/Contents/Developer @@ -98,28 +82,6 @@ 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 - -Sign in and let Kane CLI install the tooling it manages for the simulator: - -```bash -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: - -```bash -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 "" --os-version ` as the list prints them. - @@ -132,13 +94,9 @@ The exact Android API levels and device profiles in the supported matrix are pin 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. +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. -#### Step 2: Install an arm64 System Image +#### 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: @@ -146,7 +104,7 @@ Install a system image with the **`arm64-v8a`** ABI. In the Android Studio SDK M sdkmanager "system-images;android-35;google_apis;arm64-v8a" ``` -#### Step 3: Create a Virtual Device (AVD) +#### 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: @@ -156,86 +114,64 @@ avdmanager create avd -n kane_pixel \ -d pixel ``` -#### Step 4: Point Kane CLI at a Non-Default SDK Location (Only If Needed) +#### 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: ```bash -export ANDROID_HOME="/path/to/your/Android/sdk" # only if not the default location +export ANDROID_HOME="/path/to/your/Android/sdk" ``` If your SDK is at the default path, skip this step. -#### Step 5: Install the Kane CLI Test Tooling + + + +### Step 2: Install the Kane CLI Test Tooling -Sign in and let Kane CLI install the tooling it manages for the emulator: +Sign in and let Kane CLI install the tooling it manages. This is the same for both platforms: ```bash kane-cli login -kane-cli doctor --target emulator --install +kane-cli doctor --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. +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. -#### Ready Check +### Step 3: Ready Check -Confirm Kane CLI sees a ready Android toolchain and, optionally, the AVDs on your machine: +Confirm Kane CLI sees a ready toolchain and, optionally, the devices on your machine: ```bash -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 +kane-cli doctor # required checks, each with a fix if it fails +kane-cli doctor --targets # also list the simulators and 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 "" --os-version ` as the list prints them. - - - +When the checks for your platform pass, setup is complete. On Android, confirm your AVD is listed by `--targets`. -## Running a Mobile Test Locally +## Running a Mobile Test Once a target is set up, point a run at it: ```bash # one-off, from the command line kane-cli run "Sign in and open the account tab" --target simulator --app ./builds/MyApp.zip +kane-cli run "Add the first item to the cart" --target emulator --app ./builds/app-debug.apk # 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](/docs/kane-cli-cli-reference/#kane-cli-run) and [Mobile Runs](/docs/kane-cli-modes/#mobile-runs). To save a default target, device, and app instead of passing flags every time, see [Configuration](/docs/kane-cli-configuration/#mobile-target). To set the target, app, and device inside a test file, see [Test.md](/docs/kane-cli-testmd/#mobile-target). To run a folder of mobile tests, see [Batch Runs](/docs/kane-cli-testrun/#mobile-members). - -## 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. - -```bash -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 -``` +`--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. -Three things differ from a local run: +You also need a device. In the interactive TUI, leaving `--device` 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 `--device` or `kane-cli config set-device`, or the run exits and prints the fix. On the `desktop` target, `--device` and `--app` are ignored. -- **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. +In the interactive TUI, switch targets with `/mobile` and `/desktop`, and run `/doctor` to check mobile tooling and devices. -The prerequisites, the app rules, and what one job can hold are covered in [Remote runs on the cloud grid](https://github.com/LambdaTest/kane-cli/blob/main/docs/user-guide/remote-execution.md) in the Kane CLI user guide. +For the full flag list and the app formats each target accepts, see the [CLI Reference](/docs/kane-cli-cli-reference/#kane-cli-run). To save a default target, device, and app instead of passing flags every time, see [Configuration](/docs/kane-cli-configuration/#mobile-target). To run a mobile test from a file, see [Test.md](/docs/kane-cli-testmd/#mobile-target). ## Evidence for a Mobile Run @@ -255,10 +191,8 @@ The result summary records the **device** in the run environment, for example th ## Next Steps -- [Remote runs on the cloud grid](https://github.com/LambdaTest/kane-cli/blob/main/docs/user-guide/remote-execution.md) to run mobile suites from any machine - [CLI Reference](/docs/kane-cli-cli-reference/) for the full flag and command list - [Configuration](/docs/kane-cli-configuration/) to save a default target, device, and app -- [Batch Runs](/docs/kane-cli-testrun/) to run a suite of mobile tests - [Troubleshooting](/docs/kane-cli-troubleshooting/) for wider setup and run problems diff --git a/docs/kane-cli-modes.mdx b/docs/kane-cli-modes.mdx index ee625738a..ed4a9cecb 100644 --- a/docs/kane-cli-modes.mdx +++ b/docs/kane-cli-modes.mdx @@ -179,7 +179,7 @@ For variables and context file behavior, see [Variables and context](/docs/kane- ### Mobile runs -By default a run targets the **desktop** browser (Chrome), so every example above is unchanged. On macOS Apple Silicon you can instead point a run at a virtual mobile device on this machine: an `emulator` (a virtual Android device) or a `simulator` (a virtual iOS device). Every mobile run needs an app under test. From any other machine, run a saved mobile suite on the cloud grid with [`testrun run --remote`](/docs/kane-cli-mobile/#running-a-mobile-suite-on-the-cloud-grid). +By default a run targets the **desktop** browser (Chrome), so every example above is unchanged. On macOS Apple Silicon you can instead point a run at a virtual mobile device: an `emulator` (a virtual Android device) or a `simulator` (a virtual iOS device). Every mobile run needs an app under test. ```bash # desktop (default): nothing changes for web runs @@ -195,12 +195,12 @@ kane-cli run "Sign in and open the account tab" --target simulator --app ./build The mobile run flags: - `--target desktop|emulator|simulator`: which target to run against. Defaults to the saved session target, otherwise `desktop`. -- `--device-name ` and `--os-version `: pick a device as `kane-cli devices list --target emulator|simulator` prints it. A name needs a version, and a version alone matches any device on it. In the TUI/TTY, omitting them opens a one-time picker and the choice is saved. In non-interactive runs a device must already be set, via the flags or `kane-cli config set-device-name` / `set-os-version`, or the run exits with the fix spelled out. -- `--app `: the app under test, required for every mobile run. Pass a build (emulator: `.apk`, simulator: `.zip`) or an uploaded app id (`APP` followed by six or more digits). `kane-cli apps list --target ` lists yours. On the `desktop` target, the device flags and `--app` are ignored. +- `--device `: pick a device by name, serial, `ip:port`, or udid. In the TUI/TTY, omitting it opens a one-time picker and the choice is saved; in non-interactive runs a device must already be set (via `--device` or `kane-cli config set-device`) or the run exits with the fix spelled out. +- `--app `: the app under test, required for every mobile run. Pass a build (emulator: `.apk`, simulator: `.zip`) or an uploaded app id (`APP` followed by six or more digits). On the `desktop` target, `--device` and `--app` are ignored. In the interactive TUI, a first run offers a Desktop / Emulator / Simulator chooser, and you can switch targets at any time with `/mobile` and `/desktop`. Run `/doctor` to check mobile tooling and devices. -For setup (Xcode or Android Studio, `kane-cli login`, and `kane-cli doctor --target emulator|simulator --install`) and the app formats each target accepts, see [Mobile testing](/docs/kane-cli-mobile/). +For setup (Xcode or Android Studio, `kane-cli login`, and `kane-cli doctor --install`) and the app formats each target accepts, see [Mobile testing](/docs/kane-cli-mobile/). ### Output Streams diff --git a/docs/kane-cli-testmd.mdx b/docs/kane-cli-testmd.mdx index 556f76a50..e20f1a7ca 100644 --- a/docs/kane-cli-testmd.mdx +++ b/docs/kane-cli-testmd.mdx @@ -84,11 +84,9 @@ headless: true | `code_export` | root + step | Generate Playwright code after the run | | `code_language` | root + step | `python` or `javascript` for code export | | `global_context` / `local_context` | root + step | Inline Markdown or file path for agent context | -| `target` | root | Where the test runs: a browser transport (`chrome`, the default, `cdp`, or `ws`) or a mobile target (`emulator` or `simulator`, a virtual Android or iOS device, locally on macOS Apple Silicon or on the cloud grid with `testrun run --remote`). See [Mobile Target](#mobile-target). | +| `target` | root | Where the test runs: a browser transport (`chrome`, the default, `cdp`, or `ws`) or a mobile target (`emulator` or `simulator`, macOS Apple Silicon). See [Mobile Target](#mobile-target). | | `app` | root | Mobile only. The app under test: a build path (emulator `.apk`, simulator `.zip`) or an uploaded `APP…` id. Required with a mobile target, rejected with a browser target. | | `no_reset` | root | Mobile only. Keep the app's existing state between runs instead of resetting it. | -| `device_name` | root | Mobile only. The default device for this test, as `kane-cli devices list --target ` prints it (add `--remote` for the grid catalog). Overridden by `--device-name`. | -| `os_version` | root | Mobile only. The device's OS version (`14`, `17.5`). Overridden by `--os-version`. Required alongside `device_name`. | | `chrome_profile` | root only | Named Chrome profile under `~/.testmuai/kaneai/chrome-profiles/`. | | `cdp_endpoint` | root only | Reuse an external Chrome over CDP. | | `ws_endpoint` | root only | LambdaTest / Playwright WebSocket endpoint. | @@ -96,14 +94,12 @@ headless: true ### Mobile Target -`target:` also accepts the two mobile values, `emulator` for a virtual Android device and `simulator` for a virtual iOS device, with the app under test as its own root key: +On macOS Apple Silicon, `target:` also accepts the two mobile values, `emulator` for a virtual Android device and `simulator` for a virtual iOS device, with the app under test as its own root key: ```yaml --- target: emulator # emulator (Android) | simulator (iOS) -app: ./builds/app-debug.apk # or an APP… id from `kane-cli apps list --target emulator` -device_name: Pixel 7 # optional default device (with os_version) -os_version: "14" # optional; `--device-name` / `--os-version` override both +app: ./builds/app-debug.apk no_reset: false # optional --- ``` @@ -111,13 +107,12 @@ no_reset: false # optional - **`target`**: `emulator` runs on an Android emulator, `simulator` on an iOS simulator. The platform never appears separately, the target implies it. - **`app`**: the app under test, required with a mobile target and rejected with a browser one. A build path (emulator `.apk`, simulator `.zip`) or an uploaded app id, `APP` followed by six or more digits. On-device package ids are not accepted. - **`no_reset`**: optional. Keep the app's existing state between runs instead of resetting it. -- **`device_name`** / **`os_version`**: optional per-test defaults for the device, in the vocabulary of `kane-cli devices list --target ` (local) or `kane-cli devices list --target --remote` (grid catalog). The run flags `--device-name` / `--os-version` override them. A name needs a version. The nested form, `target: {platform, app}`, is not accepted. The parser refuses it and spells out the flat shape above. -Mobile tests run with `kane-cli testmd run` and in batch with [`testrun`](/docs/kane-cli-testrun/#mobile-members). Locally that needs macOS Apple Silicon, and setup is covered in [Mobile Testing](/docs/kane-cli-mobile/). With [`testrun run --remote`](/docs/kane-cli-mobile/#running-a-mobile-suite-on-the-cloud-grid), the suite runs on a grid emulator or simulator from any machine. +Mobile tests run with `kane-cli testmd run`. A batch run does not support mobile members: a `_test.md` with a mobile target is rejected up front, before the suite runs. Setup is covered in [Mobile Testing](/docs/kane-cli-mobile/). ### Root-only vs root-or-per-step diff --git a/docs/kane-cli-testrun.mdx b/docs/kane-cli-testrun.mdx index 4d00946fb..31ffdee18 100644 --- a/docs/kane-cli-testrun.mdx +++ b/docs/kane-cli-testrun.mdx @@ -53,17 +53,7 @@ error: plan invalid — 2 offending test(s): tests/other_project_test.md: project_mismatch ``` -## Mobile members - -A `_test.md` with a mobile [`target:`](/docs/kane-cli-testmd/#mobile-target) (`emulator` / `simulator`) is a normal member *(0.8.7)*: - -- **Locally**, the suite drives the emulators and simulators on this machine, so the host must be macOS Apple Silicon with the [mobile setup](/docs/kane-cli-mobile/#setup) done. Pick the device with `--device-name` / `--os-version` as `kane-cli devices list --target emulator|simulator` prints it, or set `device_name:` / `os_version:` in the file. -- **On the cloud grid** (`--remote`), the suite runs on a virtual device on a HyperExecute macOS host, so it works **from any machine**: Linux, Windows, or a Mac with no Xcode or Android Studio. Pick the device from `kane-cli devices list --target emulator|simulator --remote`. One grid job runs one platform (emulator members on one Android version, simulator members on one HyperExecute pool), and a member's local build is uploaded from your machine before dispatch and handed to the grid as an `APP…` id. Everything else is in [Remote runs on the cloud grid](https://github.com/LambdaTest/kane-cli/blob/main/docs/user-guide/remote-execution.md). - -```bash -kane-cli testrun run tests/app/ --device-name "Pixel 7 API 35" --os-version 15 # local emulators -kane-cli testrun run tests/app/ --remote --device-name "Pixel 7" --os-version 14 # the grid -``` +> **Mobile is not supported in a batch run.** A `_test.md` with a mobile [`target:`](/docs/kane-cli-testmd/#mobile-target) (`emulator` / `simulator`) is rejected up front, before the suite runs. Run mobile tests one at a time with `kane-cli testmd run `. ## Running @@ -79,9 +69,6 @@ kane-cli testrun run tests/app/ --remote --device-name "Pixel 7" --os-version 14 | `--retry-count ` | Max replay restart attempts before a full re-author | `3` | | `--bug-detection ` | `off` \| `stop` \| `continue` — see [Configuration](/docs/kane-cli-configuration/#bug-detection) | config value | | `--headless` | Run Chrome without a visible window | off | -| `--remote [backend]` | Dispatch the suite to the cloud grid instead of local Chrome or local devices (default backend: `hyper`). Needs `kane-cli plugin install remote-execution`. See [Remote runs on the cloud grid](https://github.com/LambdaTest/kane-cli/blob/main/docs/user-guide/remote-execution.md) | off | -| `--device-name ` | Device for the suite's mobile members: as `kane-cli devices list --target ` prints it locally, or a grid catalog device with `--remote` | member's `device_name:` | -| `--os-version ` | OS version for the mobile members (`14`, `17.5`). Alone, it matches any device on that version | member's `os_version:` | | `--env ` | Environment (`prod` or `stage`) | active env | | `--username ` / `--access-key ` | Basic auth (skips OAuth) | — | diff --git a/docs/kane-cli-troubleshooting.mdx b/docs/kane-cli-troubleshooting.mdx index d3b683c6a..d0d7651b8 100644 --- a/docs/kane-cli-troubleshooting.mdx +++ b/docs/kane-cli-troubleshooting.mdx @@ -353,20 +353,12 @@ Two other triggers: npm configured to skip optional dependencies (`npm config ge ## Mobile Issues -Local mobile runs are supported on **macOS Apple Silicon (arm64) only**. On other hosts, run mobile suites on the cloud grid with `kane-cli testrun run --remote`. See [Running a Mobile Suite on the Cloud Grid](/docs/kane-cli-mobile/#running-a-mobile-suite-on-the-cloud-grid). - -Start every local mobile problem with `doctor`, which prints one line per required check, each with a fix. `doctor` checks one target at a time, so pass `--target`: +Mobile testing is supported on **macOS Apple Silicon (arm64) only**. Start every mobile problem with `doctor`, which prints one line per required check, each with a fix: ```bash -# iOS Simulator -kane-cli doctor --target simulator # required checks, each with a fix if it fails -kane-cli doctor --target simulator --install # install the test tooling Kane CLI manages -kane-cli devices list --target simulator # the simulators Kane CLI can run against - -# Android Emulator -kane-cli doctor --target emulator -kane-cli doctor --target emulator --install -kane-cli devices list --target emulator +kane-cli doctor # required checks, each with a fix if it fails +kane-cli doctor --install # install the test tooling Kane CLI manages +kane-cli doctor --targets # list the emulators and simulators available ``` The common setup failures for each platform, and their fixes, are listed on the mobile testing page: