Usage Guide

# Install
npm install -g appclaw

# 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

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

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

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

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

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

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

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

- 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

- tap: "Login Button"

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

- 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

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

# Enable LambdaTest cloud
CLOUD_PROVIDER=lambdatest

# LambdaTest credentials (from app.lambdatest.com → Profile → Access Key)
LAMBDATEST_USERNAME=your_username
LAMBDATEST_ACCESS_KEY=your_access_key

# Target device
LAMBDATEST_DEVICE_NAME=iPhone 14
LAMBDATEST_OS_VERSION=16
PLATFORM=ios

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

# LLM for AI-powered automation
LLM_PROVIDER=gemini
LLM_API_KEY=your_gemini_api_key

# 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

import { AppClaw } from 'appclaw';

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

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/

npm install appclaw

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

import { AppClaw } from 'appclaw';

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();

import { AppClaw } from 'appclaw';

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();

import { AppClaw } from 'appclaw';

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

await app.run('open YouTube app');       // regex match — no LLM call
await app.run('tap Search');             // regex match — no LLM call
await app.run('type Appium 3.0');        // regex match — no LLM call
await app.run('tap the search button');  // LLM fallback → tap
await app.run('wait 2 seconds');         // regex match — no LLM call
await app.run('scroll down');            // regex match — no LLM call

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

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

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

npx appclaw --report

.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

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

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

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);
  });
});

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}`);
}

import { AppClaw } from 'appclaw';

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.');

npx tsx scripts/smoke-test.ts

import {
  AppClaw,
  type AppClawOptions,   // constructor options
  type FlowResult,       // returned by runFlow()
  type RunResult,        // returned by run()
  type AgentResult,      // returned by runGoal()
  type RunYamlFlowOptions // second arg to runFlow()
} from 'appclaw';

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

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

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

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

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

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

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

- 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

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

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

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

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

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

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