Kalokoby

All guides › By use case

By use case

Mobile apps: walk Android and iOS screens like web pages

Kaloko drives Android emulators and phones over adb and the iOS Simulator, captures each screen with its UI tree on every device you name, in light and dark mode, checks labels, touch targets and crashes, and lays the app flow out on the same canvas as your web pages.

Your web flows get reviewed on a canvas. The app ships the same features and nobody sees its screens side by side until the store review. Kaloko walks the app too, so both are reviewed in one place.

The problem

Mobile end-to-end suites prove that a button can be tapped. They do not show whether the screen reads well in Czech, whether a label is cut off on a small phone, whether dark mode leaves grey text on a black background, or whether the icon button has a label for VoiceOver. Screenshots end up in a chat thread, detached from the criteria.

What changes with Kaloko

The scenario says platform: android or platform: ios. Steps are reached by deep links or by a short step script. Every step becomes a screenshot and a UI tree, criteria are checked against that tree, and the canvas shows the flow with device frames. List several devices (devices: [pixel-8-api-34, iphone-se-ios-18]) and add color_schemes: [light, dark], and every screen is captured on each device in both modes. Reviewers accept or return steps exactly as they do for web runs.

How it works

  1. Name the app

    in kaloko.config.yml for each environment: the Android package (and an APK to install), or the iOS bundle and simulator. Phones over Wi-Fi and real iPhones get an entry under devices.

  2. Describe the flow

    screens with deep links (shop://product/42) or scripts such as app.tap('button[text="Do košíku"]'). Each locale starts the app fresh in that language.

  3. Walk

    npx kaloko walk goes through the flow on each device. An emulator that is not running is started, a phone is woken up and gets a clean status bar. Kaloko captures each screen: adb screencap with the uiautomator tree on Android, and simctl with the idb tree on iOS (text recognition without idb). It also reads the Android app log for crashes.

  4. Dark mode and motion

    for each capture Kaloko switches the device to dark mode or reduced motion (cmd uimode on Android, simctl ui on the Simulator) and back afterwards.

  5. Check

    the app pack checks labels on every control, touch targets (48 dp / 44 pt), truncated texts and crashes. Your own criteria use CSS-like selectors on the tree. Semantic questions read the screen as an outline. A screen that is a WebView in an Android app can be captured as a web page with every web check.

  6. Anything else

    Maestro, Appium, Detox or XCUITest take the screenshot, and kaloko capture --image shot.png --tree hierarchy.xml brings it in with its UI dump.

Skills and prompts

Walk the checkout of our Android app in cs and en on the small and the large emulator, in light and dark mode: product detail by deep link, add to cart, cart. Use the app pack and check the price format.
Our Maestro flow already walks the iOS onboarding. After each screen, capture it into Kaloko with the hierarchy, then share the run for design review.

Expected outcome: a canvas of app screens in phone frames per locale, device and mode. Each has its UI tree, highlighted elements for failing criteria (a 30×30 icon button without a label, say) and a crash stamp if the app died.

What you get

FAQ

Do I need Appium?

No. Android needs adb and an emulator or a device. iOS needs Xcode's Simulator; idb adds the full UI tree and taps. If you already use Appium, Maestro or XCUITest, keep them and import their screens. npx kaloko doctor says what is missing on your machine and how to install it.

Does it work with Flutter or React Native?

Yes, as long as the platform's UI tree exposes the widgets (Flutter with semantics, React Native with testID and accessibility labels). Otherwise Kaloko falls back to text recognition on the screenshot.

Can it run on a real iPhone?

Yes, for launching the app, opening deep links and taking screenshots: Kaloko uses Xcode's devicectl and idevicescreenshot or pymobiledevice3, and reads the text on the screen. It does not tap on a real iPhone; let XCUITest, Maestro or Appium do that and import each screen with kaloko capture --image. Real Android phones work fully over USB or Wi-Fi.

What about a WebView inside the app?

On Android, a debuggable WebView is a Chromium page: a step script gets it with await webview(), and the capture holds its DOM with the web checks. On iOS, capture the screen as an app screen and test the web content itself in WebKit with an iPhone preset.

More guides

Accepting a task with an AI agent, in the pull requestRegression before a release: compare the run with the accepted baselineSEO and landing-page checks on production, read-only, every dayE-mail flows: capture the message next to the screen that sent it

Install once, then work through your agent

Kaloko runs where your code and your agent are. The service stores and versions the results, shows the canvas and collects approvals.

  1. Add the CLI to the project
    npm install --save-dev kaloko

    Needs Node 20 or newer. Update later with npm update kaloko.

  2. Create the config and install the skill
    npx kaloko init --agent claude --org <your-org>

    The skill is copied to .claude/skills/kaloko. npx kaloko doctor checks Chrome, the config and the token.

  3. Create your organization and a token

    Create an organization; you become its admin. The start page offers a tester token in one click, later under Settings → API tokens. Put it into the project .env:

    KALOKO_TOKEN=kal_…
    TYPESAFE_API_KEY=…   # optional: semantic evaluator

Then just ask your agent

The skill teaches your agent the whole loop: it writes the acceptance plan and the scenario from the task, walks the screens, evaluates, shares the canvas, reads what reviewers said and fixes it. You don’t type the commands; you look at the canvas.

What the agent runs (or run it yourself, e.g. in CI)

The same loop by hand:

npx kaloko start --scenario docs/tasks/TASK-123/qa/scenario.yml --env local
npx kaloko walk        # playwright steps; agent/manual steps: kaloko capture
npx kaloko evaluate
npx kaloko share --pr
npx kaloko feedback    # what reviewers said, with ids to answer