Usage Guide

Quick Start

Install AppClaw globally and start automating in seconds.

# Install
npm install -g @appclaw/cli

# Run with a natural language goal
appclaw "Open Settings and turn on Wi-Fi"

# Run a YAML flow
appclaw --flow my-test.yaml

# Interactive playground
appclaw --playground

For a full test project — config file, spec files, npm scripts — scaffold it with appclaw init or set it up manually below.

Scaffold a project with appclaw init

The fastest way to start. It asks a few questions (platform, LLM provider, agent mode — use the ↑/↓ arrow keys to choose), then writes a ready-to-run project. It only creates files and prints next steps: it never installs packages, never touches the network, and never prompts for your API key.

# Scaffold into the current folder (or pass a directory name)
npx appclaw init
npx appclaw init my-app

# Skip the prompts with flags / defaults
npx appclaw init my-app --platform ios --provider anthropic --yes

It generates a complete Test Runner project:

my-app/
  appclaw.config.ts      # all 5 lifecycle hooks, wired to your answers
  tests/
    example.spec.ts      # a starter spec to run immediately
  .env.example           # full, commented reference of every setting
  .env                   # empty — paste your LLM_API_KEY here (gitignored)
  package.json           # "test" + "test:parallel" scripts, devDeps
  tsconfig.json
  .gitignore             # node_modules/, .appclaw/, .env

Then finish setup and run:

cd my-app
npm install
# paste your key into .env → LLM_API_KEY=...
npm test

Or set it up manually

# 1. Install (project-local) — tsx loads the TypeScript specs/config
npm install -D appclaw tsx

# 2. Connect an emulator / device, then run all tests
npx appclaw test

# Run a single file, or filter by path substring
npx appclaw test tests/login.spec.ts
npx appclaw test login

Trigger it from package.json

The normal entry point is an npm script. appclaw test auto-discovers appclaw.config.ts in the working directory and runs the specs in its testDir — so the script is just the command plus any flags.

{
  "scripts": {
    "test": "appclaw test",                  // runs everything in testDir
    "test:parallel": "appclaw test --workers 2",
    "test:login": "appclaw test tests/login.spec.ts",
    "test:grep": "appclaw test --grep login"
  },
  "devDependencies": { "@appclaw/cli": "^1.9.3", "@appclaw/core": "^1.9.3", "@appclaw/runner": "^1.9.3", "tsx": "^4.21.0" }
}

npm test                  # → appclaw test (reads appclaw.config.ts)
npm run test:parallel     # 2 devices at once
npm run test:login        # a single file

A minimal project layout:

my-app/
  package.json          # "test": "appclaw test"
  appclaw.config.ts     # infra: nodes, concurrency, retries, llm, hooks (write once)
  tests/
    login.spec.ts       # your tests — no UDIDs, no ports
    checkout.spec.ts

CLI Options

All the flags you can pass to appclaw.

Execution Modes

AppClaw has three distinct ways to automate mobile apps.

Agent Mode

Give AppClaw a goal in plain English. The AI agent takes a screenshot, reasons about what it sees, and decides what to tap, type, or swipe — step by step until the goal is complete.

appclaw "Search for 'Appium 3.0' on YouTube and find the TestMu AI video"

YAML Flows

Define repeatable, version-controlled test flows in YAML. Each step is a natural language instruction — no element selectors, no brittle locators.

appclaw --flow tests/youtube-search.yaml --env dev

Playground

An interactive REPL where you type one instruction at a time and see it execute immediately. Great for exploring an app and building flows interactively.

appclaw --playground --platform ios --device-type simulator

When you're happy with the recorded steps, type /export to save them. By default this writes an SDK vitest spec (.test.ts); pass a .yaml filename to export a YAML flow instead.

# In the REPL prompt:
/export                  # → SDK vitest spec (flow-<ts>.test.ts)
/export login.test.ts    # → SDK vitest spec
/export login.yaml       # → YAML flow

Bare-filename exports land in EXPORT_DIR (default .appclaw/exports). Override it per run with --export-dir, and load a custom .env with --env-path:

appclaw --playground --env-path path/to/.env --export-dir tests/generated

Designing YAML Flows

YAML flows are the heart of AppClaw's repeatable automation. Write your test steps in plain English — AppClaw figures out how to execute them on the device. No XPath, no accessibility IDs, no brittle selectors.

Flat Format

The simplest YAML structure — a metadata header separated by --- from a flat list of steps.

name: Turn on Wi-Fi
platform: android
---
- open Settings app
- tap Connections
- wait 1s
- tap Wi-Fi
- verify Wi-Fi is visible
- done

Metadata Fields

Phased Format

For structured tests, organize your steps into three phases: setup, steps, and assertions. This gives clearer reporting and separates initialization from the actual test logic.

name: YouTube Search
description: Searches YouTube and verifies video results
platform: android
env: dev
---
setup:
  - open ${variables.app_name} app
  - wait until search icon is visible

steps:
  - click on search icon
  - type '${secrets.search_query}'
  - wait 3s
  - click on the first result from the list
  - wait for the search results to be visible
  - scroll down

assertions:
  - verify ${variables.expected_channel} is visible

Phases Explained

Variables & Secrets

Keep your flows flexible and secure with variable interpolation.

Variables ${variables.X}

Loaded from environment files. Values appear in logs.

Secrets ${secrets.X}

Resolved from shell environment variables at runtime. Always shown as *** in logs. Use --env-path path/to/.env to load these from a dotenv file outside the working directory (values override the process environment).

Environment File

Create .appclaw/env/<name>.yaml in your project root:

variables:
  app_name: youtube
  expected_channel: TestMu AI
  timeout: 30
  locale: en-US

Then reference it in your YAML header with env: dev, or pass --env dev on the CLI.

Inline Variables

For self-contained flows, embed variables directly in the YAML header:

name: Self-contained flow
env:
  variables:
    app_name: youtube
    search_term: appium 3.0
---
- open ${variables.app_name} app
- type ${variables.search_term}

Open / Close App

Launch an app by name, or close (terminate) it when you’re done. Closing uses appium-mcp’s terminate under the hood.

# Open
- open YouTube
- launch Settings app

# Close — by name
- close YouTube
- close the YouTube app
- terminate Settings
- quit Chrome

# Close — the current foreground app
- close app
- close the app

App names resolve against the device’s installed apps (well-known names like YouTube work out of the box). Omitting the name closes whatever app is in the foreground.

Tap / Click

Tap on an element by describing its label. AppClaw matches it against visible text and elements on screen.

- tap Login
- click on the search icon
- press Submit
- select the first item
- choose English
- pick the blue option
- navigate to Settings
- toggle Dark Mode
- enable Notifications
- close the popup
- dismiss the dialog

All of these are equivalent — they find the element and tap it. Use whichever reads most naturally.

- tap: "Login Button"

Proximity Selectors

When several elements share the same label — e.g. a “Login” tab, a “Login” nav item, and the actual LOGIN button — add a spatial qualifier to pick the right one by its position relative to another element. Works on both tap and type.

- tap the login button below the password field
- tap the icon to the right of the title
- tap the arrow to the left of the heading
- tap the star above the rating
- click the checkbox next to Terms
- tap the submit button within the form
- type "secret" in the field below the email

The phrase after the target names the relation and the anchor element. Modeled on Taiko’s proximity selectors:

Type Text

Type text into the currently focused field, or specify a target field.

# Type into focused field
- type "hello world"
- enter text "user@example.com"

# Type into a specific field
- type "john@example.com" in email field
- enter "password123" into password field

# Search (types the text)
- search for "Appium 3.0"
- look for "restaurants nearby"

- type: "hello world"

Wait / Pause

Pause execution for a fixed duration.

- wait 3s
- wait 1.5 seconds
- sleep 500ms
- pause 2 sec
- wait               # defaults to 2 seconds
- wait a moment      # defaults to 2 seconds

- wait: 3          # seconds

Wait Until

Wait dynamically until a condition is met. Polls the screen every 500ms up to a timeout (default 10s). Uses AI vision to understand the screen — you can describe what you expect to see in plain English.

- wait until search icon is visible
- wait for the search results to be visible
- wait for the home screen to be loaded
- wait until "Welcome back" appears
- wait 15s until login button is visible  # custom timeout

- wait until loading spinner is gone
- wait for the popup to be hidden
- wait until progress bar disappeared

- wait until screen is loaded
- wait until screen is stable
- wait 5s until screen is ready

# With custom timeout
- waitUntil: "Login button"
  timeout: 15

# Wait for element to disappear
- waitUntilGone: "Loading spinner"
  timeout: 20

# Screen loaded (DOM stability check)
- waitUntil: "screen loaded"

Scroll / Swipe

Scroll or swipe in any direction, optionally repeating multiple times or scrolling until an element is found.

- scroll down
- scroll up 3 times
- swipe left
- swipe right 2 times

# Scroll until an element appears
- scroll down until "Terms & Conditions" is visible
- scroll down 5 times to find "Accept"
- scroll down to see "Load More"

- scrollAssert: "Terms & Conditions"
  direction: down
  maxScrolls: 5

Drag / Slider

Drag one element to another — sliders, carousels, reorderable lists, and any drag-and-drop interaction. Requires vision mode (AGENT_MODE=vision).

- drag the green circle slider to the +100 mark
- slide the price handle to +80
- move the volume knob to maximum

# "drag: from to to"
- drag: "green circle slider to +100 mark"

- drag:
    from: green circle slider
    to:   +100 mark

Assert / Verify

Verify that something is visible on screen. Works with both literal text and visual/semantic descriptions via AI vision.

- verify "Welcome back" is visible
- assert Dashboard is visible
- check that the login button is on the screen
- verify TestMu AI is visible

- assert: "Welcome back"
- verify: "Dashboard"    # alias for assert
- check:  "Login button"  # alias for assert

Navigation & Control

App launch, back, home, enter, and flow completion.

# Launch / open
- open YouTube app
- launch Settings
- start Chrome

# Navigation
- go back
- press back button
- go home

# Submit / Enter
- press enter
- submit
- perform search
- confirm

# Flow completion
- done
- done: "Login was successful"

Full Command Reference

Every supported step kind at a glance.

Vision Modes

Control how AppClaw locates elements on screen.

Agent Mode AGENT_MODE

Vision Mode VISION_MODE

Environment Variables

All environment variables recognized by AppClaw. These are especially useful for CI/CD pipelines.

LLM Configuration

Device & Platform

Vision

Execution Tuning

MCP Connection

Cloud Providers

Set CLOUD_PROVIDER=browserstack | saucelabs | lambdatest | custom to route sessions through a remote hub instead of a local device. Full variable reference: Cloud Providers → Environment variables.

Custom Capabilities

Sometimes the built-in capabilities aren't enough — you want to set appium:autoGrantPermissions, force a specific appium:automationName, or pre-install an APK. AppClaw accepts a JSON file of extra capabilities merged into create_session on every run.

Where to set it

• CLI: --caps path/to/caps.json (interactive, YAML flow, --playground, --record — every mode).
• Env var: CAPABILITIES_FILE=path/to/caps.json in .env or your shell.
• SDK: new AppClaw({ capabilitiesFile: 'path/to/caps.json' }).

--caps wins over the env var when both are set.

Flat format

The simplest shape — a flat object of Appium capabilities. Applied to every session regardless of platform.

{
  "appium:autoGrantPermissions": true,
  "appium:noReset": true,
  "appium:newCommandTimeout": 300
}

Platform-scoped format

When Android and iOS need different capabilities, split them under top-level android and ios keys. Optionally use common (alias: default, shared) for capabilities that apply to both.

{
  "common": {
    "appium:newCommandTimeout": 300,
    "appium:noReset": true
  },
  "android": {
    "appium:app": "/path/to/MyApp.apk",
    "appium:automationName": "UiAutomator2",
    "appium:autoGrantPermissions": true
  },
  "ios": {
    "appium:app": "/path/to/MyApp.ipa",
    "appium:automationName": "XCUITest",
    "appium:autoAcceptAlerts": true
  }
}

The wrapper keys themselves (android, ios, common) are stripped before sending to Appium — they're config metadata, not W3C capabilities.

Precedence

When multiple sources set the same capability, later wins:

1. Built-in defaults (MJPEG port, app from APP_PATH, etc.)
2. Your capabilities file (top-level / common / platform-specific, in that order)
3. Framework-managed caps (per-parallel-worker ports, pinned UDID from --udid)

So your file can override defaults, but framework values (parallel ports, device pinning) still take final precedence — concurrent workers won't collide even if your file sets the same key.

Notes

• The file is loaded once per session. Editing it during a long run has no effect until the next session.
• appium:app in the file takes precedence over the APP_PATH env var, which itself is overridden by a per-flow app: YAML header.
• All values are sent through verbatim — AppClaw doesn't validate that appium:* keys are recognised by your driver. Typos will surface as Appium errors at session creation.
• Cloud runs: capabilities from this file are merged into the remote session too, including provider-specific namespaces like bstack:options, sauce:options, or lt:options.

Cloud Providers

Run AppClaw on real iOS and Android devices in the cloud — no local device or emulator required. AppClaw ships built-in support for TestMuAI (formerly LambdaTest), Sauce Labs, and BrowserStack, plus a custom mode that points at any Appium-compatible hub (self-hosted grids, device farms, Selenium Grid).

Configuration is generic across providers: pick one via CLOUD_PROVIDER, then supply credentials, target device, and app through the same CLOUD_* variables. Provider-specific dashboard options (bstack:options, sauce:options, lt:options) go through CAPABILITIES_FILE — AppClaw doesn't wrap them individually.

Quick reference

TestMuAI (formerly LambdaTest)

Example .env for the TestMuAI hub. Sauce Labs and BrowserStack use the same CLOUD_* variables — swap CLOUD_PROVIDER to saucelabs or browserstack, plug in that provider's credentials and app identifier, and add CLOUD_REGION for Sauce if you're not on us-west-1.

# Enable TestMuAI (formerly LambdaTest)
CLOUD_PROVIDER=lambdatest

# Credentials (app.lambdatest.com → Profile → Access Key)
CLOUD_USERNAME=your_username
CLOUD_ACCESS_KEY=your_access_key

# Target device
PLATFORM=ios
CLOUD_DEVICE_NAME=iPhone 14
CLOUD_OS_VERSION=16

# Your app (upload via portal, copy the lt:// ID)
CLOUD_APP=lt://APP10xxxxxxxxxxxxxxxx

# Optional dashboard labels (mapped into lt:options.build/project)
CLOUD_BUILD_NAME=nightly-1234
CLOUD_PROJECT_NAME=Checkout Suite

Custom / self-hosted grid

Use CLOUD_PROVIDER=custom to point at any Appium-compatible hub — a self-hosted Selenium Grid node, an internal device farm, an Appium server running on another machine, or a third-party provider not listed above. AppClaw sends W3C caps verbatim; it doesn't inject a provider-specific options namespace.

# Custom grid — you supply the whole hub URL
CLOUD_PROVIDER=custom
CLOUD_SERVER_URL=https://appium.example.com/wd/hub

# Auth: either embed in the URL (https://user:key@host/wd/hub) OR set separately
CLOUD_USERNAME=your_username
CLOUD_ACCESS_KEY=your_access_key

PLATFORM=android
CLOUD_DEVICE_NAME=Pixel 8
CLOUD_OS_VERSION=14
CLOUD_APP=https://storage.example.com/builds/app.apk

Provider-specific options (bstack / sauce / lt)

AppClaw maps CLOUD_BUILD_NAME and CLOUD_PROJECT_NAME into the active provider's options namespace as a convenience (for BrowserStack it aliases both buildName/projectName and build/project). Everything else — video recording, network logs, tunneling, geo-location, project capacity — goes through a capabilities file:

{
  "lt:options": {
    "video": true,
    "network": true,
    "deviceOrientation": "PORTRAIT",
    "idleTimeout": 300
  }
}

Load it via CLI or SDK the same way you do for local runs:

appclaw --caps ./caps.json --flow flows/checkout.yaml

CLI usage

Once .env is configured, run AppClaw exactly as you would locally:

# Run a natural-language goal on a cloud device
appclaw "Open the app and navigate to the checkout screen"

# Run a YAML flow on a cloud device
appclaw --flow flows/checkout.yaml

SDK usage

No SDK changes needed — the same AppClaw instance routes through the configured cloud provider automatically:

import { AppClaw } from '@appclaw/core';

// CLOUD_PROVIDER is read from .env automatically
const app = new AppClaw({
  provider:    'gemini',
  apiKey:      process.env.LLM_API_KEY,
  reportName:  'Checkout — Cloud',
});

await app.run('open the app');
await app.run('tap Add to Cart');
await app.run('tap Checkout');

await app.teardown();  // report saved to .appclaw/runs/

Environment variables

¹ Not strictly required for custom when the credentials are embedded in CLOUD_SERVER_URL (https://user:key@host/wd/hub).
² Required for CLOUD_PROVIDER=custom; optional otherwise.

Node.js / TypeScript SDK

AppClaw ships a first-class programmatic API so you can drive mobile automation directly from Node.js or TypeScript — no CLI required. The SDK is the natural fit for QA automation inside test runners (Vitest, Jest, Mocha), CI pipelines, and any script that needs to control a device programmatically.

Architecture

The SDK exposes a single AppClaw class that manages the full lifecycle:

• Lazy MCP connect — the Appium connection is opened on the first runFlow() or runGoal() call, not on construction.
• Connection reuse — subsequent calls share the same underlying connection, so you pay the startup cost once per test suite.
• Explicit teardown — call teardown() in your afterAll hook to close the connection cleanly.
• Silent by default — spinners and terminal colours are suppressed automatically, keeping CI logs clean.

Installation

AppClaw is a single package — the SDK is built in, nothing extra to install.

npm install appclaw

Create a .env file in your project root (or pass options directly to the constructor — see Options Reference).

LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
PLATFORM=android

runFlow()

Parse and execute a YAML flow file against a connected device. Returns a FlowResult you can assert on.

import { AppClaw } from '@appclaw/core';

const app = new AppClaw({
  provider: 'anthropic',
  apiKey:   process.env.ANTHROPIC_API_KEY,
  platform: 'android',
});

const result = await app.runFlow('./flows/checkout.yaml');

console.log(result.success);    // true
console.log(result.stepsUsed);  // 6
console.log(result.stepsTotal); // 6

await app.teardown();

FlowResult shape

runGoal()

Execute a plain-English goal using the agent loop — same as passing a goal string to the CLI. Returns an AgentResult.

import { AppClaw } from '@appclaw/core';

const app = new AppClaw({ provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY });

const result = await app.runGoal(
  'Log in with email qa@company.com and password Test1234'
);

console.log(result.success);   // true
console.log(result.stepsUsed); // 4
console.log(result.reason);    // "Logged in successfully"

await app.teardown();

run()

Execute a single natural-language instruction directly on the device — the programmatic equivalent of typing a command in the playground REPL. Each call is one atomic action: parse the instruction, execute it, return the result.

import { AppClaw } from '@appclaw/core';

const app = new AppClaw({ provider: 'gemini', apiKey: process.env.GEMINI_API_KEY, platform: 'android' });

await app.run('open YouTube app');
await app.run('tap Search');
await app.run('type Appium 3.0');
await app.run('tap the search button');
await app.run('wait 2 seconds');
await app.run('scroll down');

// Assertion — throws AppClawAssertionError if the claim is false
await app.verify('the TestMu AI video is visible');

await app.teardown();  // report written to .appclaw/runs/

Per-command options

run() takes an optional second argument (RunOptions) that overrides the instance defaults for that one call — handy for a slow screen that needs a longer wait, or a tight list that needs a shorter scroll. Every field is optional and falls back to the constructor value, then to the engine default.

// Wait up to 20s for this specific (slow-loading) screen
await app.run('click on Dashboard', { waitTimeout: 20000 });

// Scroll a short distance, up to 5 times, to find an item
await app.run('scroll down until Karma is visible', { scrollMode: 'short', scrollTimes: 5 });

// A single full-screen swipe
await app.run('swipe up', { scrollMode: 'full' });

RunResult shape

verify()

Assert that something is true on the current screen. verify() takes a natural-language claim, captures the screen, and checks whether it holds — the programmatic counterpart to a YAML assertion step. Unlike run(), it throws when the claim is false, so it drops straight into any test runner.

import { AppClaw } from '@appclaw/core';

const app = new AppClaw();

await app.run('open YouTube app');
await app.run('search for Appium 3.0');

// Throws AppClawAssertionError if the claim is false — no try/catch needed,
// the throw fails the test and the error carries the on-screen context.
await app.verify('the TestMu AI video is visible');

await app.teardown();

On failure it raises AppClawAssertionError, which carries the original claim, the underlying result, and — in DOM mode — the screenContents captured from the page source, so the failure message shows what was actually on screen. In vision mode the model's reasoning is already included in result.message.

When a claim fails, the thrown error reads like this:

AppClawAssertionError: Verify failed: "the TestMu AI video is visible"
  Reason: "TestMu AI" not found on screen
    Screen contains: Search, Appium 3.0 | What's new in Appium 3 | Appium 3.0 Tutorial | Mobile Testing 101 | Selenium vs Appium
  On screen now:
    • Search, Appium 3.0
    • What's new in Appium 3
    • Appium 3.0 Tutorial
    • Mobile Testing 101
    • Selenium vs Appium

Locator Cache

The SDK locator cache is an opt-in DOM-mode speed path for repeated app.run() calls. When the same app, screen, action, and label are seen again, AppClaw can skip the page-source parse, DOM scoring, and multi-strategy probing and go straight to the Appium locator that worked last time.

Enable it

Enable per SDK instance:

const app = new AppClaw({
  platform: 'android',
  agentMode: 'dom',
  locatorCache: true
});

Or isolate the cache file and namespace for CI:

const app = new AppClaw({
  locatorCache: {
    path: '.appclaw/cache/locator-cache.json',
    namespace: process.env.GITHUB_REF_NAME ?? 'local'
  }
});

You can also enable it through environment variables:

AGENT_MODE=dom
LOCATOR_CACHE_ENABLED=on
LOCATOR_CACHE_PATH=.appclaw/cache/locator-cache.json
APPCLAW_MEMORY_NAMESPACE=main

What gets stored

AppClaw stores the winning Appium locator, not the Appium element UUID. UUIDs are session-scoped and change every run; locators such as accessibility IDs and resource IDs can be re-resolved to a fresh UUID on the next run.

{
  "version": 1,
  "entries": [
    {
      "namespace": "default",
      "platform": "android",
      "appId": "com.example.app",
      "screenFingerprint": "68eda714f104",
      "actionKind": "tap",
      "label": "login button",
      "locator": {
        "strategy": "accessibility id",
        "selector": "login"
      },
      "successCount": 4,
      "failCount": 0,
      "confidence": 1
    }
  ]
}

How a cache hit works

1. AppClaw reads page source and builds a cache key from namespace, platform, app ID, semantic screen fingerprint, action kind, and label.
2. If an entry exists, AppClaw calls one Appium lookup: findElement(strategy, selector).
3. If Appium returns a fresh element UUID, AppClaw performs the action with that UUID.
4. On success, the report manifest records "cacheHit": true for that step.

{
  "verbatim": "click on login button",
  "message": "Tapped \"login button\"",
  "cacheHit": true
}

Loading screens and implicit waits

Cache misses do not bypass AppClaw's implicit wait. For DOM actions such as tap, longPress, and type, AppClaw still polls according to waitTimeout and waitInterval.

Each poll attempt does this:

1. Try the cached locator, if a cache entry exists.
2. If the cached findElement returns no element, do not fail and do not mark the cache stale. The page may still be loading.
3. Fall back to normal DOM parsing, scoring, and locator probing.
4. If a matching element is found, perform the action and update the cache.
5. If no match is found, wait waitInterval and try again.

Locator changes and recovery

If the app changes and the cached selector no longer works, AppClaw recovers through the normal DOM path. For example, if the cache contains { strategy: "accessibility id", selector: "login1" } but the real element is now login:

1. The cached lookup for login1 returns no element.
2. AppClaw falls back to DOM scoring in the same poll attempt.
3. The matching element is found and tapped.
4. recordHit() overwrites the stale selector with the new winning locator.

If the cached locator resolves to an element but the action fails against that UUID, AppClaw marks the entry stale, lowers confidence, and falls back to normal DOM resolution. Entries with very low effective confidence are evicted on save.

Screen transitions

During a transition, Appium can briefly return a mixed DOM containing labels from the previous and next screens. To avoid recording cache entries against that transient state, cache-enabled DOM actions wait briefly for two consecutive semantic screen fingerprints to match before reading or writing cache entries.

Inspecting the cache

The default file is:

cat ~/.appclaw/locator-cache.json

To see whether a step used the cache, inspect the latest SDK report manifest:

find .appclaw/runs -name manifest.json -maxdepth 2 | xargs ls -t | head -1
rg "cacheHit|verbatim|message" .appclaw/runs/*/manifest.json

Reports

Reports are enabled by default when using the SDK. After teardown() is called, AppClaw writes an HTML report to .appclaw/runs/ — one screenshot per step, plus a full execution summary. No extra configuration needed.

const app = new AppClaw({
  provider:   'gemini',
  apiKey:     process.env.GEMINI_API_KEY,
  platform:   'android',
  reportName: 'YouTube Search',  // shown in the report viewer
});

await app.run('open YouTube app');
await app.run('tap Search');
await app.run('type Appium 3.0');
await app.run('tap the search button');

await app.teardown();
// ↑ writes report to .appclaw/runs/<runId>/

Screen recording

Pass video: true to record the screen for the entire run and embed the video in the report. Recording starts automatically on the first run() call and stops in teardown().

const app = new AppClaw({
  provider:   'gemini',
  apiKey:     process.env.GEMINI_API_KEY,
  platform:   'android',
  reportName: 'YouTube Search',
  video:      true,               // record screen for the whole run
});

await app.run('open YouTube app');
await app.run('tap Search');
await app.run('type Appium 3.0');
await app.run('tap the search button');

await app.teardown();
// ↑ report includes recording.mp4 under the Recording tab

Viewing the report

Run the built-in report server after your tests complete:

npx appclaw --report                              # serves ./.appclaw/runs/
npx appclaw --report --report-dir examples/runner # serve a specific location
npx appclaw --report --report-port 5000           # custom port

The server reads .appclaw/runs/ relative to the current directory. Use --report-dir <path> to point it at a project elsewhere (absolute or relative to cwd) without cding there. Every run is listed with its steps, screenshots, pass/fail status, and timing.

Report file layout

.appclaw/
  runs/
    runs.json              # global run index
    <runId>/
      manifest.json        # full run data (steps, timing, success)
      steps/
        step-000.png       # screenshot after step 1
        step-001.png       # screenshot after step 2
        step-002.png

Disabling reports

Set report: false to skip report generation (e.g. in performance-sensitive CI pipelines):

const app = new AppClaw({
  provider: 'gemini',
  apiKey:   process.env.GEMINI_API_KEY,
  report:   false,   // disable report generation
});

Using with Vitest / Jest

Create one AppClaw instance per test file, connect once in beforeAll, and tear down in afterAll. Individual tests call runFlow() or runGoal() and assert on the result.

import { describe, it, expect, afterAll } from 'vitest';
import { AppClaw } from '@appclaw/core';

const app = new AppClaw({
  provider: 'anthropic',
  apiKey:   process.env.ANTHROPIC_API_KEY,
  platform: 'android',
  maxSteps: 20,
});

afterAll(() => app.teardown());

describe('Checkout flow', () => {
  it('completes purchase as a logged-in user', async () => {
    const result = await app.runFlow('./flows/checkout.yaml');
    expect(result.success).toBe(true);
  });

  it('handles empty cart gracefully', async () => {
    const result = await app.runFlow('./flows/checkout-empty-cart.yaml');
    expect(result.success).toBe(true);
  });

  it('completes in under 15 steps', async () => {
    const result = await app.runFlow('./flows/checkout.yaml');
    expect(result.stepsUsed).toBeLessThan(15);
  });
});

Phased flows & assertion results

For flows that use setup / steps / assertions sections, the failedPhase field tells you exactly where execution broke down:

const result = await app.runFlow('./flows/login-phased.yaml');

if (!result.success) {
  // failedPhase: 'setup' | 'test' | 'assertion'
  console.error(`Failed in ${result.failedPhase} phase`);
  console.error(`Step ${result.failedStep}: ${result.error}`);
}

CI Scripts

For CI pipelines that don't use a test framework, run flows sequentially and exit non-zero on failure. The SDK's silent: true default keeps logs clean.

import { AppClaw } from '@appclaw/core';

const app = new AppClaw({
  provider: 'google',
  apiKey:   process.env.GEMINI_API_KEY,
  platform: 'android',
  silent:   true,  // no spinners in CI
});

const flows = [
  './flows/login.yaml',
  './flows/checkout.yaml',
  './flows/search.yaml',
];

for (const flow of flows) {
  const result = await app.runFlow(flow);

  if (!result.success) {
    console.error(`FAILED: ${flow} — ${result.error}`);
    await app.teardown();
    process.exit(1);
  }

  console.log(`PASSED: ${flow} (${result.stepsUsed} steps)`);
}

await app.teardown();
console.log('All flows passed.');

Run it with tsx (no compilation step needed):

npx tsx scripts/smoke-test.ts

Options Reference

All fields passed to new AppClaw(options). Every field is optional — unset fields fall back to .env values or built-in defaults, matching CLI behaviour exactly.

TypeScript types

All public types are exported from the top-level '@appclaw/core' import:

import {
  AppClaw,
  type AppClawOptions,   // constructor options
  type RunOptions,        // per-command second arg to run()
  type ScrollDistance,    // 'short' | 'medium' | 'full'
  type FlowResult,       // returned by runFlow()
  type RunResult,        // returned by run()
  type AgentResult,      // returned by runGoal()
  type RunYamlFlowOptions // second arg to runFlow()
} from '@appclaw/core';

RunOptions is an interface, so TypeScript flags a misspelled key and the ScrollDistance union rejects an invalid value — the options object is fully type-checked, not any:

await app.run('swipe up', { scrollMode: 'shrt' });  // ✗ not assignable to ScrollDistance
await app.run('swipe up', { waitTimout: 1000 });   // ✗ unknown property (did you mean waitTimeout?)

GitHub Actions

Run AppClaw mobile UI automation flows and AI-driven goals directly in GitHub Actions — Android emulator or iOS simulator included, zero boilerplate.

Available on the GitHub Marketplace as AppClaw Mobile Tests.

uses: AppiumTestDistribution/AppClaw@v1
with:
  flow: flows/login.yaml
  platform: android
  api-key: ${{ secrets.LLM_API_KEY }}

Quick Start

Android — run a YAML flow

name: Mobile Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: AppiumTestDistribution/AppClaw@v1
        with:
          flow: flows/login.yaml
          platform: android
          api-key: ${{ secrets.LLM_API_KEY }}

Android — natural language goal

- uses: AppiumTestDistribution/AppClaw@v1
  with:
    goal: 'Open YouTube, search for Appium 3.0, verify the first result is visible'
    platform: android
    api-key: ${{ secrets.LLM_API_KEY }}

iOS — run a YAML flow

jobs:
  test:
    runs-on: macos-14  # iOS requires macOS (Apple Silicon)
    steps:
      - uses: actions/checkout@v4

      - uses: AppiumTestDistribution/AppClaw@v1
        with:
          flow: flows/ios-login.yaml
          platform: ios
          api-key: ${{ secrets.LLM_API_KEY }}

Inputs

All inputs are passed via the with: block in your workflow.

* Provide either flow or goal, not both.

** Required when cloud-provider: lambdatest.

Secrets Setup

Go to your repo → Settings → Secrets and variables → Actions → New repository secret:

Examples

Parallel matrix — run multiple flows concurrently

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        flow:
          - flows/login.yaml
          - flows/search.yaml
          - flows/checkout.yaml
    steps:
      - uses: actions/checkout@v4

      - uses: AppiumTestDistribution/AppClaw@v1
        with:
          flow: ${{ matrix.flow }}
          platform: android
          api-key: ${{ secrets.LLM_API_KEY }}
          report-name: report-${{ strategy.job-index }}

LambdaTest cloud devices

Run iOS tests on Ubuntu — no macOS runner needed.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: AppiumTestDistribution/AppClaw@v1
        with:
          flow: flows/ios-login.yaml
          platform: ios
          api-key: ${{ secrets.LLM_API_KEY }}
          cloud-provider: lambdatest
          lambdatest-username: ${{ secrets.LT_USERNAME }}
          lambdatest-access-key: ${{ secrets.LT_ACCESS_KEY }}
          lambdatest-device-name: 'iPhone 14'
          lambdatest-os-version: '16'
          lambdatest-app: ${{ secrets.LT_APP_ID }}

Vision mode (screenshot-based AI)

- uses: AppiumTestDistribution/AppClaw@v1
  with:
    flow: flows/onboarding.yaml
    platform: android
    agent-mode: vision
    api-key: ${{ secrets.LLM_API_KEY }}

Pin model for cost control

- uses: AppiumTestDistribution/AppClaw@v1
  with:
    flow: flows/smoke.yaml
    platform: android
    api-key: ${{ secrets.LLM_API_KEY }}
    model: 'gemini-2.0-flash'  # cheaper/faster than pro

Nightly regression on a schedule

on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM UTC every night

jobs:
  nightly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: AppiumTestDistribution/AppClaw@v1
        with:
          flow: flows/full-regression.yaml
          platform: android
          api-key: ${{ secrets.LLM_API_KEY }}
          report-name: nightly-report-${{ github.run_id }}

Reports

When report: true (default), an HTML report is uploaded as a workflow artifact after each run. Download it from the Actions run summary → Artifacts. The report includes:

• Step-by-step screenshots with tap overlays
• Pass/fail status per step
• Execution timeline
• Screen recording (if video: true is set in your flow)

Use report path in a downstream step

- uses: AppiumTestDistribution/AppClaw@v1
  id: appclaw
  with:
    flow: flows/login.yaml
    platform: android
    api-key: ${{ secrets.LLM_API_KEY }}

- name: Print report location
  run: echo "Report at ${{ steps.appclaw.outputs.report-path }}"

Runner Requirements

iOS tip: For faster iOS CI, use LambdaTest cloud devices on ubuntu-latest instead of a macOS runner.

What are App Guides?

App Guides (AppGuides) are per-app knowledge snippets injected directly into the agent's context window at the start of every automation run. They encode navigation patterns, gesture shortcuts, and common action paths for a specific app — so the agent never needs to rediscover them by trial and error.

How it works

When AppClaw starts a run against a known app, it automatically loads the matching guide and prepends it to the agent's system prompt with an APP_GUIDE (AppName): prefix. The LLM sees this contextual knowledge before it takes any action — making the first step decisive rather than exploratory.

APP_GUIDE (WhatsApp):

## WhatsApp Navigation
- Bottom tabs: Chats | Updates | Communities | Calls
- New chat: floating pencil/message icon (bottom-right)
- Search: magnifying-glass icon at the top of Chats

## Messaging
- Open a chat → type in the message bar at the bottom → send via arrow icon
- Attach media: paperclip icon next to message bar
- Voice note: long-press the microphone icon

Resolution order

1. Custom guide — .appclaw/guides/<appId>.md (highest priority, overrides built-ins)
2. Built-in guide — bundled guides for 10 common apps
3. No guide — agent explores the app from scratch using only what it sees on screen

Built-in Guides

AppClaw ships with guides for the most commonly automated apps on both Android and iOS. These activate automatically when AppClaw detects the matching package name or bundle ID.

Example: WhatsApp Guide

## WhatsApp Navigation
- Bottom tabs: Chats | Updates | Communities | Calls
- New chat: floating pencil/message icon (bottom-right)
- Search: magnifying-glass icon at the top of Chats

## Messaging
- Open a chat → type in the message bar at the bottom → send via arrow icon
- Attach media: paperclip icon next to message bar
- Voice note: long-press the microphone icon
- Emoji/stickers: smiley face icon on the left of message bar

## Common Actions
- Star a message: long-press message → star icon
- Forward: long-press message → forward arrow
- Delete: long-press message → trash icon
- Group info: tap the group name at the top of the chat

Example: YouTube Guide

## YouTube Navigation
- Bottom nav: Home | Shorts | + (upload) | Subscriptions | Library
- Search: magnifying-glass icon (top-right)
- Tap a video thumbnail to play; double-tap left/right to seek ±10 s

## Searching
- Tap the search icon → type query → press Enter or tap search icon again
- Filter results: tap "Filters" after searching

## Playback
- Full screen: rotate device or tap the expand icon (bottom-right of player)
- Quality: tap ⋮ inside player → Quality
- Captions: tap CC icon inside player

Custom Guides

Add a guide for any app — or override a built-in — by dropping a Markdown file at .appclaw/guides/<appId>.md in your project directory. Custom guides always take priority over built-ins.

Creating a custom guide

1. Find your app's package name (Android) or bundle ID (iOS). You can get this from the appId field in your YAML flow, or by inspecting the device.
2. Create the directory .appclaw/guides/ in your project root.
3. Write a Markdown file named <appId>.md.

## Main Navigation
- Bottom tabs: Home | Search | Orders | Profile
- Hamburger menu (top-left) → categories and account settings

## Checkout Flow
- Cart icon is always in the top-right corner
- Tap "Proceed to Checkout" → select address → choose payment → Place Order
- Apply coupon: tap "Have a coupon?" on the order summary screen

## Product Search
- Tap the search bar at the top; supports filters: Brand | Price | Rating
- Long-press any product thumbnail to preview without navigating away

Once in place, AppClaw picks it up automatically — no code changes or restarts needed.

Tips for writing good guides

Agent CLI appclaw-agent

appclaw-agent is a deterministic terminal CLI designed for AI coding agents — Claude Code, Gemini CLI, Codex CLI, and any agent with terminal access. It exposes named device sessions through simple JSON-output commands so the host agent can inspect and operate a real Android or iOS device without writing any automation code.

How it compares

Installation

Install globally so appclaw-agent is available in any terminal session.

npm install -g @appclaw/agent

Verify the install and read the built-in workflow guide — agents should run this before starting any session:

appclaw-agent help workflow

Workflow

Every session follows the same five-step pattern. Re-snapshot after every state-changing action — refs are invalidated when the screen changes.

# 1. Open a named session
appclaw-agent --session login open com.example.app --platform android

# 2. Inspect actionable UI elements
appclaw-agent --session login snapshot -i --json

# 3. Interact using a ref or stable selector
appclaw-agent --session login fill @e1 "test@example.com" --json
appclaw-agent --session login press @e2 --json

# 4. Re-snapshot to get fresh refs
appclaw-agent --session login snapshot -i --json

# 5. Verify visually, then close
appclaw-agent --session login screenshot /tmp/screen.png
appclaw-agent --session login close

Session persistence

A user-local daemon owns active sessions. Separate terminal invocations sharing the same --session name continue operating on the same screen — you don't lose the device connection between commands.

JSON output

All commands accept --json and return a structured response the host agent can parse directly:

{
  "ok": true,
  "session": "login",
  "message": "Snapshot contains 12 element(s)",
  "output": "@e1 [EditText] \"Email\" id=\"com.example:id/email\"\n...",
  "data": { "elements": [ ... ] }
}

Command Reference

Session management

Inspection

Interaction

Hardware keys

Selectors & Refs

There are two ways to target an element: snapshot refs (short-lived) and stable selectors (durable across snapshots).

Snapshot refs (@eN)

Every snapshot -i --json response includes short refs like @e1, @e2, etc. Use these for immediate actions on the current screen — they're fast to write but expire as soon as the screen changes.

appclaw-agent --session s1 press @e3 --json

Stable selectors

Stable selectors survive re-snapshots and are safe to store in test scripts. Three selector kinds are supported:

# Using resource ID
appclaw-agent --session s1 press 'id="com.example:id/login_btn"' --json

# Using accessibility ID
appclaw-agent --session s1 press 'accessibility="Sign in"' --json

# Using visible text
appclaw-agent --session s1 press 'text="Sign in"' --json

Vision

When AppClaw's vision API is configured, you can describe elements in plain English instead of providing a selector. Use --vision only for genuinely visual operations where a DOM selector isn't available or reliable.

# Tap by visual description
appclaw-agent --session s1 press --vision "cart icon in the top right"

# Assert something is visible on screen
appclaw-agent --session s1 is visible --vision "order confirmed message" --json

# Read a value from the screen
appclaw-agent --session s1 get info --vision "displayed total" --json

Visual assertions vs DOM checks

DOM checks confirm an element exists in the hierarchy — not that it is rendered on screen. An element can be in the DOM but scrolled off-screen or hidden. Always use a screenshot for pass/fail assertions:

Test Runner

The AppClaw Runner owns your entire mobile test run. It discovers connected devices, starts the appium-mcp server, assigns one device per worker, runs your tests in parallel, and writes a consolidated report. You only write the test bodies — device pools, ports, sessions, and cleanup are handled for you.

It builds on the Node.js SDK: every test receives a ready app (an AppClaw instance) bound to a leased device, so the full app.run() / app.verify() surface is available inside a test.

What the Runner handles for you:

• Device pool — discovers and de-dupes connected devices/emulators.
• appium-mcp node — spins up a local SSE server and connects to it.
• Parallel sessions — one device per worker, isolated ports + pinned UDID.
• Lifecycle hooks — run / device / scope / test setup and teardown.
• Fixtures — Playwright-style reusable, composable, injected setup.
• Reporting — per-test reports + a suite summary, with a pass/fail exit code.
• Cleanup — deletes sessions (frees adb ports) and never orphans the server.

Writing Tests

Import test, describe, and hooks from @appclaw/runner. Each test gets an injected app and a context object.

import { test, describe } from '@appclaw/runner';

describe('Login', () => {
  test('user can sign in', async (app, ctx) => {
    // app = an AppClaw on a leased device
    await app.run('tap the Username field');
    await app.run('type admin');
    await app.run('tap Login');
    await app.verify('the home screen is visible');
    // ctx.state · ctx.device · ctx.title · ctx.retry
  });

  // Per-test options: retries, skip, only, platform
  test('flaky path', { retries: 2 }, async (app) => { /* … */ });
  test.skip('not ready', async () => {});
  test.only('focus this', async (app) => { /* … */ });

  // Platform-only tests — skipped (not failed) on a run of the other OS
  test.android('NFC tap-to-pay', async (app) => { /* … */ });
  test.ios('Face ID enrollment', async (app) => { /* … */ });
  test('shared but explicit', { platform: ['android', 'ios'] }, async (app) => { /* … */ });
});

Configuration

All run configuration lives in appclaw.config.ts via defineConfig. It is written once by whoever operates the lab/CI — test authors never touch it.

import { defineConfig } from '@appclaw/runner';

export default defineConfig({
  // ── discovery / specs ──
  testDir: 'tests',
  testMatch: ['**/*.spec.ts', '**/*.test.ts'],

  // ── execution ──
  concurrency: 'auto',        // 'auto' = one worker per device, or a number
  retries: 1,
  timeout: 120000,           // per-test timeout (ms)

  // ── infra ──
  node: { local: true },     // spawn a local appium-mcp SSE server

  // ── AppClaw options (forwarded to every test's session) ──
  platform: 'android',
  provider: process.env.LLM_PROVIDER,
  apiKey: process.env.LLM_API_KEY,
  model: process.env.LLM_MODEL,
  capabilitiesFile: './tests/caps.json',   // resolved next to this config
  // agentMode: 'vision', maxSteps: 40, waitTimeout: 15000, video: true, …
});

Environment variables (.env)

The config reads secrets from process.env (e.g. apiKey: process.env.LLM_API_KEY). AppClaw auto-loads a .env file from the directory you run in — put it next to package.json and the values are available before the config is read. No wiring needed.

LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-…
LLM_MODEL=claude-sonnet-4-6

If your .env lives elsewhere (a shared file, a CI secret path), point at it with --env-file — it's loaded before the config, overriding the auto-loaded one:

appclaw test --env-file ../../.env
appclaw test --env-file .env.ci --workers 2

Resolution precedence

For any setting: CLI flag > config file > built-in default.

Runner-level options

AppClaw options (pass-through)

The config extends the full AppClawOptions surface, so any per-session option can be set directly on the config and is forwarded to every test: platform, provider, apiKey, model, agentMode, maxSteps, waitTimeout, scrollMode, video, locatorCache, capabilitiesFile, and more. See the SDK Options Reference. The Runner manages mcpTransport/mcpHost/mcpPort/deviceUdid itself (overridden per session) so you can't accidentally break device pinning.

Running on Android & iOS

A run targets one platform — set by platform in the config, or overridden with --platform android|ios. The whole run (device pool, sessions, report) pins to that platform.

Your specs don't change: AppClaw drives by natural language + DOM/vision, not platform-specific selectors, so the same tests/login.spec.ts runs on both OSes. Only the config differs (platform + capabilities). The clean setup is two config files sharing one tests/ folder, since capabilitiesFile is per-platform:

appclaw.android.ts   // platform: 'android', capabilitiesFile: './caps/android.json'
appclaw.ios.ts       // platform: 'ios',     capabilitiesFile: './caps/ios.json'
tests/               // shared specs — unchanged across platforms

{
  "scripts": {
    "test:android": "appclaw test -c appclaw.android.ts",
    "test:ios":     "appclaw test -c appclaw.ios.ts",
    "test:all":     "npm run test:android && npm run test:ios"
  }
}

If both platforms can share a single caps file, skip the second config and just flip the flag: appclaw test --platform android / --platform ios.

Lifecycle Hooks

Hooks run at four scopes. All are optional — unset hooks are simply skipped.

defineConfig({
  globalSetup: async ({ pool }) => {
    const token = await loginViaApi();
    return { token };           // → ctx.state in every test
  },
  globalTeardown: async ({ state }) => { await cleanup(state.token); },

  deviceSetup: async (app, ctx) => { await app.run('grant all permissions'); },
  beforeEach:  async (app, ctx) => { await app.run('reset app'); },
  afterEach:   async (app, info) => { /* info.status, info.durationMs */ },
});

beforeAll / afterAll are registered inside spec files (file-scoped at the top, or inside a describe):

import { test, describe, beforeAll, afterAll } from '@appclaw/runner';

beforeAll(async (app) => { /* once per device, before this file's tests */ });

describe('Cart', () => {
  beforeAll(async (app) => { /* once per device, for this group */ });
  test('add item', async (app) => { /* … */ });
});

Execution order (on a device)

deviceSetup → beforeAll (file → describe) → beforeEach → test → afterEach
           → … → afterAll (describe → file, reverse) at device drain

Fixtures

Fixtures are reusable setup a test opts into by destructuring it from the first argument — the Playwright model. They are lazy (built only when a test asks), support dependency injection, and use the use() pattern for setup/teardown.

import { test as base } from '@appclaw/runner';
import type { AppClaw } from '@appclaw/core';

// loggedInApp: taps login, hands the app to the test, then tears down.
export const test = base.extend<{ loggedInApp: AppClaw }>({
  loggedInApp: async ({ app }, use) => {
    await app.run('Click on login button');   // setup
    await use(app);                            // hand to the test
    // teardown here, after the test
  },
});

import { test } from './fixtures.js';

test('list is visible', async ({ loggedInApp }) => {
  await loggedInApp.verify('the list is visible');
});

Built-in fixtures

Destructure these without defining anything: app (the AppClaw on the leased device), device, state (from globalSetup), title, and retry. Your own fixtures can depend on them.

Returning data from a fixture (device info + an API user)

A fixture isn't limited to the app — it can do any setup and return data the test needs, by passing it to use(value). The test reads it back by destructuring the fixture's name, fully typed. A common case: provision a user through your backend before the test and tear it down after. The built-in device is available to both the fixture and the test.

import { test as base } from '@appclaw/runner';
import { createUser, deleteUser, type ApiUser } from './api.js';

export const test = base.extend<{ apiUser: ApiUser }>({
  apiUser: async ({ device }, use) => {
    const user = await createUser(device.name);   // setup — POST /users
    await use(user);                            // hand the data to the test
    await deleteUser(user);                      // teardown — DELETE /users/:id
  },
});

import { test } from './fixtures.js';

test('sign up a fresh user', async ({ app, device, apiUser }) => {
  // device info — name, udid, platform, state
  console.log(`on ${device.name} (${device.udid})`);

  // fixture data — typed as ApiUser, so apiUser.email autocompletes
  await app.run(`Type ${apiUser.email} into the email field`);
  await app.run(`Type ${apiUser.password} into the password field`);
  await app.run('Click on login button');
  await app.verify('the home screen is visible');
});

Scope: test vs worker

By default a fixture is test-scoped — built fresh for every test, torn down right after. Pass { scope: 'worker' } (the [fn, options] tuple form) to build it once per worker (= once per device), reuse it across that worker's tests, and tear it down once when the worker finishes. Use it to avoid repeating expensive setup (accounts, tokens, seeded data, a mock server) on every test.

export const test = base.extend<{ account: Account }>({
  // built once per device, shared by all its tests
  account: [async ({ device }, use) => {
    const acct = await createAccount();   // setup once
    await use(acct);
    await deleteAccount(acct);            // teardown once, at worker drain
  }, { scope: 'worker' }],
});

test('uses the shared account', async ({ app, account }) => {
  await app.run(`sign in as ${account.email}`);
});

Parallelism

The Runner runs tests across all your devices at once. The unit of parallelism is the test: every test goes into one shared queue, and each device-worker pulls the next test when free (work-stealing). A device is held by its worker for the whole run (sticky lease), and each test gets its own isolated Appium session — unique systemPort / mjpegServerPort / wdaLocalPort and a pinned UDID — so concurrent sessions never collide.

What runs in parallel — tests, not files

A common assumption is that each *.spec.ts file runs on its own device. It doesn't. The runner flattens every file into a single queue of tests, and each device-worker pulls the next test when free — so two tests from the same file routinely run on different devices at the same time.

Notice the login.spec.ts tests (teal) landed on both devices — the file was never the unit of work; each test was.

How many run at once

workers = min( request , devices , tests )
                  │         │         └ can't have more workers than tests
                  │         └ hard ceiling: number of discovered devices
                  └ concurrency / --workers

Ways to control it

Examples

appclaw test --workers 2

# Summary shows which device each test ran on:
#   ✓ Login › user can sign in   [emulator-5554]
#   ✓ Cart  › add item          [emulator-5556]

CLI Reference

appclaw test [filter…] [options]. The positional filter narrows by file path or substring within testDir. Run it via an npm script ("test": "appclaw test") or directly with npx appclaw test ….

Reports & Cleanup

Every test writes its own run data to .appclaw/runs/ (screenshots per step, status, timing), the console prints a file-grouped summary table, and the Runner generates a self-contained HTML report for that run. The process exit code is 0 when all tests pass, 1 otherwise — so it drops straight into CI.

Results

tests/login.spec.ts (2)
  ✓ Login › user can sign in        emulator-5554  6.1s
  ✓ Login › toggle remember-me      emulator-5556  7.0s
tests/cart.spec.ts (1)
  ✗ Cart  › add item                emulator-5554  3.2s  ↻1
      expected badge "1", found "0"

──────────────────────────────────────────────────────────
✓ 2 passed  ✗ 1 failed  in 16.3s  · emulator-5554: 2  emulator-5556: 1
→ report  .appclaw/runs/suite-…/index.html

The HTML report

Open the printed path in a browser. The report is scoped to the current run only — it never folds in past runs — and is built for mobile: a pass-rate summary, a per-device breakdown, results grouped by spec file, and, on expanding a test, a device-framed screenshot of every step, the failure reason, and a screen recording when one was captured.

Cleanup is automatic and layered:

• Per test — the session is deleted on teardown, which frees its adb port forwards and the on-device server.
• End of run — the local appium-mcp node is stopped.
• On interrupt — a signal guard (Ctrl-C / SIGTERM / crash) kills the node so it is never orphaned.

View the HTML reports any time with appclaw --report (add --report-dir <path> to serve reports from a location outside cwd).