action.yml

name: 'AppClaw Mobile Tests'
description: 'Run mobile UI automation flows and AI-driven goals in CI — Android emulator, iOS simulator, or LambdaTest cloud devices.'
author: 'AppiumTestDistribution'

branding:
  icon: 'smartphone'
  color: 'purple'

# ── Inputs ────────────────────────────────────────────────────────────────────

inputs:
  # ── What to run ─────────────────────────────────────────────────────────────
  flow:
    description: 'Path to a YAML flow file (mutually exclusive with goal)'
    required: false
    default: ''
  goal:
    description: 'Natural language goal for the LLM agent (mutually exclusive with flow)'
    required: false
    default: ''

  # ── Platform ─────────────────────────────────────────────────────────────────
  platform:
    description: 'Target platform: android or ios'
    required: false
    default: 'android'

  # ── LLM ──────────────────────────────────────────────────────────────────────
  provider:
    description: 'LLM provider: gemini, anthropic, openai, groq'
    required: false
    default: 'gemini'
  api-key:
    description: 'LLM API key — passed to AppClaw as LLM_API_KEY'
    required: true
  model:
    description: 'LLM model ID to use (e.g. gemini-2.0-flash, claude-3-5-haiku-20241022). Defaults to the provider built-in.'
    required: false
    default: ''

  # ── Agent ────────────────────────────────────────────────────────────────────
  agent-mode:
    description: 'Interaction strategy: dom (element locators) or vision (screenshot AI)'
    required: false
    default: 'dom'
  max-steps:
    description: 'Maximum agent steps before the run is marked failed. Default: 30'
    required: false
    default: '30'
  step-delay:
    description: 'Delay in milliseconds between steps. Default: 500'
    required: false
    default: '500'

  # ── Debug ────────────────────────────────────────────────────────────────────
  mcp-debug:
    description: 'Enable MCP debug logging (MCP_DEBUG=1). Default: false'
    required: false
    default: 'false'
  mcp-timeout-ms:
    description: 'MCP request timeout in milliseconds. Default: 300000'
    required: false
    default: '300000'
  llm-thinking:
    description: 'Enable LLM extended thinking: on or off. Default: off'
    required: false
    default: 'off'

  # ── iOS device ───────────────────────────────────────────────────────────────
  ios-device-type:
    description: 'iOS device type: simulator or real. Default: simulator'
    required: false
    default: 'simulator'

  # ── iOS simulator ────────────────────────────────────────────────────────────
  device-udid:
    description: 'Explicit device/simulator UDID to target. Leave empty to let AppClaw auto-detect.'
    required: false
    default: ''
  ios-simulator-name:
    description: 'iOS simulator device model to boot (e.g. "iPhone 16", "iPhone 15 Pro"). Default: iPhone 16'
    required: false
    default: 'iPhone 16'
  ios-simulator-os:
    description: 'iOS version to use when multiple runtimes are available (e.g. "18.4", "17.5"). Default: latest available'
    required: false
    default: ''

  # ── Android emulator ─────────────────────────────────────────────────────────
  android-api-level:
    description: 'Android emulator API level. Default: 33 (Android 13)'
    required: false
    default: '33'
  android-profile:
    description: 'Android AVD hardware profile. Default: pixel_6'
    required: false
    default: 'pixel_6'
  android-target:
    description: 'Emulator system image target: default or google_apis'
    required: false
    default: 'default'
  android-arch:
    description: 'Emulator CPU architecture: x86_64 or x86. Default: x86_64 (required for API 31+)'
    required: false
    default: 'x86_64'

  # ── LambdaTest cloud ─────────────────────────────────────────────────────────
  cloud-provider:
    description: 'Cloud device provider: lambdatest. Leave empty for local emulator/simulator (default).'
    required: false
    default: ''
  lambdatest-username:
    description: 'LambdaTest account username (required when cloud-provider=lambdatest)'
    required: false
    default: ''
  lambdatest-access-key:
    description: 'LambdaTest access key (required when cloud-provider=lambdatest)'
    required: false
    default: ''
  lambdatest-device-name:
    description: 'Cloud device name, e.g. "Pixel 7" or "iPhone 14" (required when cloud-provider=lambdatest)'
    required: false
    default: ''
  lambdatest-os-version:
    description: 'Cloud OS version, e.g. "13" for Android or "16" for iOS (required when cloud-provider=lambdatest)'
    required: false
    default: ''
  lambdatest-app:
    description: 'LambdaTest app ID (lt://APP...) — the app to test on the cloud device'
    required: false
    default: ''

  # ── Report ───────────────────────────────────────────────────────────────────
  report:
    description: 'Upload HTML report as a workflow artifact after the run. Default: true'
    required: false
    default: 'true'
  report-name:
    description: 'Name of the uploaded artifact. Default: appclaw-report'
    required: false
    default: 'appclaw-report'

  # ── AppClaw version ───────────────────────────────────────────────────────────
  appclaw-version:
    description: 'AppClaw npm package version to install. Default: latest'
    required: false
    default: 'latest'
  use-local-build:
    description: 'Build and install AppClaw from the checked-out source instead of npm. Use in PRs to test local changes.'
    required: false
    default: 'false'

# ── Outputs ───────────────────────────────────────────────────────────────────

outputs:
  report-path:
    description: 'Path to the generated .appclaw/runs/<id>/ report directory'
    value: ${{ steps.report-path.outputs.path }}

# ── Steps ─────────────────────────────────────────────────────────────────────

runs:
  using: composite
  steps:
    # ── Validate ──────────────────────────────────────────────────────────────
    - name: Validate inputs
      shell: bash
      run: |
        if [ -z "${{ inputs.flow }}" ] && [ -z "${{ inputs.goal }}" ]; then
          echo "::error title=Missing input::Provide either 'flow' (path to YAML) or 'goal' (natural language string)"
          exit 1
        fi
        if [ -n "${{ inputs.flow }}" ] && [ -n "${{ inputs.goal }}" ]; then
          echo "::error title=Conflicting inputs::Provide either 'flow' or 'goal', not both"
          exit 1
        fi
        if [ "${{ inputs.platform }}" != "android" ] && [ "${{ inputs.platform }}" != "ios" ]; then
          echo "::error title=Invalid platform::platform must be 'android' or 'ios', got '${{ inputs.platform }}'"
          exit 1
        fi
        if [ -n "${{ inputs.cloud-provider }}" ] && [ "${{ inputs.cloud-provider }}" != "lambdatest" ]; then
          echo "::error title=Invalid cloud-provider::cloud-provider must be 'lambdatest' or empty, got '${{ inputs.cloud-provider }}'"
          exit 1
        fi
        if [ "${{ inputs.cloud-provider }}" = "lambdatest" ]; then
          if [ -z "${{ inputs.lambdatest-username }}" ] || [ -z "${{ inputs.lambdatest-access-key }}" ]; then
            echo "::error title=Missing LambdaTest credentials::lambdatest-username and lambdatest-access-key are required when cloud-provider=lambdatest"
            exit 1
          fi
          if [ -z "${{ inputs.lambdatest-device-name }}" ] || [ -z "${{ inputs.lambdatest-os-version }}" ]; then
            echo "::error title=Missing device info::lambdatest-device-name and lambdatest-os-version are required when cloud-provider=lambdatest"
            exit 1
          fi
        fi

    # ── Node + AppClaw ────────────────────────────────────────────────────────
    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22'

    - name: Install AppClaw (from npm)
      if: inputs.use-local-build == 'false'
      shell: bash
      run: |
        echo "::group::Installing @appclaw/cli@${{ inputs.appclaw-version }}"
        npm install -g @appclaw/cli@${{ inputs.appclaw-version }} mjpeg-consumer
        echo "::endgroup::"

    - name: Install AppClaw (from local source)
      if: inputs.use-local-build == 'true'
      shell: bash
      run: |
        echo "::group::Building AppClaw from local source"
        npm install --no-package-lock
        npm run build
        # The root is a private workspace with no bin; the `appclaw` command
        # lives in @appclaw/cli and resolves its @appclaw/* deps from the local
        # workspace (they aren't published). A global `npm install -g .` would
        # expose no bin, so put the workspace bin dir on PATH instead.
        npm install -g mjpeg-consumer
        echo "$GITHUB_WORKSPACE/node_modules/.bin" >> "$GITHUB_PATH"
        echo "::endgroup::"

    # ── LambdaTest — YAML flow ────────────────────────────────────────────────
    - name: Run YAML flow on LambdaTest
      if: inputs.cloud-provider == 'lambdatest' && inputs.flow != ''
      shell: bash
      env:
        LLM_PROVIDER: ${{ inputs.provider }}
        LLM_API_KEY: ${{ inputs.api-key }}
        LLM_MODEL: ${{ inputs.model }}
        LLM_THINKING: ${{ inputs.llm-thinking }}
        AGENT_MODE: ${{ inputs.agent-mode }}
        MAX_STEPS: ${{ inputs.max-steps }}
        STEP_DELAY: ${{ inputs.step-delay }}
        PLATFORM: ${{ inputs.platform }}
        CLOUD_PROVIDER: lambdatest
        LAMBDATEST_USERNAME: ${{ inputs.lambdatest-username }}
        LAMBDATEST_ACCESS_KEY: ${{ inputs.lambdatest-access-key }}
        LAMBDATEST_DEVICE_NAME: ${{ inputs.lambdatest-device-name }}
        LAMBDATEST_OS_VERSION: ${{ inputs.lambdatest-os-version }}
        LAMBDATEST_APP: ${{ inputs.lambdatest-app }}
      run: appclaw --flow "${{ inputs.flow }}" --platform ${{ inputs.platform }}

    # ── LambdaTest — natural language goal ────────────────────────────────────
    - name: Run goal on LambdaTest
      if: inputs.cloud-provider == 'lambdatest' && inputs.goal != ''
      shell: bash
      env:
        LLM_PROVIDER: ${{ inputs.provider }}
        LLM_API_KEY: ${{ inputs.api-key }}
        LLM_MODEL: ${{ inputs.model }}
        LLM_THINKING: ${{ inputs.llm-thinking }}
        AGENT_MODE: ${{ inputs.agent-mode }}
        MAX_STEPS: ${{ inputs.max-steps }}
        STEP_DELAY: ${{ inputs.step-delay }}
        PLATFORM: ${{ inputs.platform }}
        CLOUD_PROVIDER: lambdatest
        LAMBDATEST_USERNAME: ${{ inputs.lambdatest-username }}
        LAMBDATEST_ACCESS_KEY: ${{ inputs.lambdatest-access-key }}
        LAMBDATEST_DEVICE_NAME: ${{ inputs.lambdatest-device-name }}
        LAMBDATEST_OS_VERSION: ${{ inputs.lambdatest-os-version }}
        LAMBDATEST_APP: ${{ inputs.lambdatest-app }}
      run: appclaw "${{ inputs.goal }}" --platform ${{ inputs.platform }}

    # ── Android — enable KVM ──────────────────────────────────────────────────
    - name: Enable KVM
      if: inputs.platform == 'android' && inputs.cloud-provider == ''
      shell: bash
      run: |
        echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
          | sudo tee /etc/udev/rules.d/99-kvm4all.rules
        sudo udevadm control --reload-rules
        sudo udevadm trigger --name-match=kvm

    # ── Android — YAML flow ───────────────────────────────────────────────────
    - name: Run YAML flow on Android emulator
      if: inputs.platform == 'android' && inputs.cloud-provider == '' && inputs.flow != ''
      uses: reactivecircus/android-emulator-runner@v2
      env:
        LLM_PROVIDER: ${{ inputs.provider }}
        LLM_API_KEY: ${{ inputs.api-key }}
        LLM_MODEL: ${{ inputs.model }}
        LLM_THINKING: ${{ inputs.llm-thinking }}
        AGENT_MODE: ${{ inputs.agent-mode }}
        MAX_STEPS: ${{ inputs.max-steps }}
        STEP_DELAY: ${{ inputs.step-delay }}
        PLATFORM: android
      with:
        api-level: ${{ inputs.android-api-level }}
        arch: ${{ inputs.android-arch }}
        profile: ${{ inputs.android-profile }}
        target: ${{ inputs.android-target }}
        emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
        disable-animations: true
        script: appclaw --flow "${{ inputs.flow }}" --platform android

    # ── Android — natural language goal ───────────────────────────────────────
    - name: Run goal on Android emulator
      if: inputs.platform == 'android' && inputs.cloud-provider == '' && inputs.goal != ''
      uses: reactivecircus/android-emulator-runner@v2
      env:
        LLM_PROVIDER: ${{ inputs.provider }}
        LLM_API_KEY: ${{ inputs.api-key }}
        LLM_MODEL: ${{ inputs.model }}
        LLM_THINKING: ${{ inputs.llm-thinking }}
        AGENT_MODE: ${{ inputs.agent-mode }}
        MAX_STEPS: ${{ inputs.max-steps }}
        STEP_DELAY: ${{ inputs.step-delay }}
        PLATFORM: android
      with:
        api-level: ${{ inputs.android-api-level }}
        arch: ${{ inputs.android-arch }}
        profile: ${{ inputs.android-profile }}
        target: ${{ inputs.android-target }}
        emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
        disable-animations: true
        script: appclaw "${{ inputs.goal }}" --platform android

    # ── iOS — pre-download WebDriverAgent ────────────────────────────────────
    - name: Download prebuilt WebDriverAgent for iOS simulator
      if: inputs.platform == 'ios' && inputs.cloud-provider == ''
      shell: bash
      env:
        GH_TOKEN: ${{ github.token }}
      run: |
        # Resolve latest WDA version via GitHub API (authenticated = 5000/hr, no rate-limit risk)
        WDA_VERSION=$(curl -fsSL \
          -H "Authorization: Bearer ${GH_TOKEN}" \
          -H "Accept: application/vnd.github+json" \
          "https://api.github.com/repos/appium/WebDriverAgent/releases/latest" \
          | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")

        if [ -z "$WDA_VERSION" ]; then
          echo "::error::Could not resolve latest WDA version from GitHub"
          exit 1
        fi

        ARCH=$(uname -m)  # arm64 on macos-14 (Apple Silicon), x86_64 otherwise
        URL="https://github.com/appium/WebDriverAgent/releases/download/v${WDA_VERSION}/WebDriverAgentRunner-Build-Sim-${ARCH}.zip"

        echo "Downloading prebuilt WDA v${WDA_VERSION} for ${ARCH}..."
        curl -fsSL "${URL}" -o /tmp/wda.zip
        unzip -q /tmp/wda.zip -d /tmp/wda

        WDA_APP="/tmp/wda/WebDriverAgentRunner-Runner.app"
        if [ ! -d "$WDA_APP" ]; then
          echo "::error::WebDriverAgentRunner-Runner.app not found after extraction"
          ls -la /tmp/wda/
          exit 1
        fi

        echo "APPIUM_MCP_WDA_APP_PATH=${WDA_APP}" >> $GITHUB_ENV
        echo "WDA pre-downloaded: ${WDA_APP}"

    # ── iOS — boot simulator ─────────────────────────────────────────────────
    - name: Boot iOS simulator
      if: inputs.platform == 'ios' && inputs.cloud-provider == '' && inputs.ios-device-type == 'simulator'
      shell: bash
      env:
        SIM_NAME: ${{ inputs.ios-simulator-name }}
        SIM_OS: ${{ inputs.ios-simulator-os }}
      run: |
        xcrun simctl list devices available -j > /tmp/simctl_devices.json

        UDID=$(python3 <<'EOF'
        import json, os, re, sys
        sim_name = os.environ.get('SIM_NAME', 'iPhone 16').lower()
        sim_os   = os.environ.get('SIM_OS', '').strip()
        data = json.load(open('/tmp/simctl_devices.json'))
        candidates = []
        for runtime, devs in data['devices'].items():
            if 'iOS' not in runtime:
                continue
            # Extract version from runtime key, e.g. "com.apple.CoreSimulator.SimRuntime.iOS-18-4" → "18.4"
            m = re.search(r'iOS[- ]([\d][\d.-]+)', runtime, re.IGNORECASE)
            ver = m.group(1).replace('-', '.') if m else ''
            if sim_os and not ver.startswith(sim_os):
                continue
            for d in devs:
                if d.get('isAvailable') and sim_name in d.get('name', '').lower():
                    candidates.append((ver, d['udid']))
        if not candidates:
            sys.exit(1)
        # Pick highest iOS version
        candidates.sort(key=lambda x: [int(p) for p in x[0].split('.') if p.isdigit()], reverse=True)
        print(candidates[0][1])
        EOF
        )

        if [ -z "$UDID" ]; then
          echo "::error::No available iOS simulator matching name='${SIM_NAME}' os='${SIM_OS}'"
          xcrun simctl list devices available
          exit 1
        fi

        echo "Booting simulator $UDID (${SIM_NAME})"
        xcrun simctl boot "$UDID" 2>/dev/null || true   # already Booted is OK
        xcrun simctl bootstatus "$UDID" -b               # block until fully booted
        echo "IOS_SIMULATOR_UDID=$UDID" >> "$GITHUB_ENV"

    # ── iOS — YAML flow ───────────────────────────────────────────────────────
    - name: Run YAML flow on iOS simulator
      if: inputs.platform == 'ios' && inputs.cloud-provider == '' && inputs.flow != ''
      shell: bash
      env:
        LLM_PROVIDER: ${{ inputs.provider }}
        LLM_API_KEY: ${{ inputs.api-key }}
        LLM_MODEL: ${{ inputs.model }}
        LLM_THINKING: ${{ inputs.llm-thinking }}
        AGENT_MODE: ${{ inputs.agent-mode }}
        MAX_STEPS: ${{ inputs.max-steps }}
        STEP_DELAY: ${{ inputs.step-delay }}
        PLATFORM: ios
        DEVICE_TYPE: ${{ inputs.ios-device-type }}
        DEVICE_UDID: ${{ inputs.device-udid || env.IOS_SIMULATOR_UDID }}
        MCP_DEBUG: ${{ inputs.mcp-debug == 'true' && '1' || '0' }}
        MCP_TIMEOUT_MS: ${{ inputs.mcp-timeout-ms }}
      run: appclaw --flow "${{ inputs.flow }}" --platform ios

    # ── iOS — natural language goal ───────────────────────────────────────────
    - name: Run goal on iOS simulator
      if: inputs.platform == 'ios' && inputs.cloud-provider == '' && inputs.goal != ''
      shell: bash
      env:
        LLM_PROVIDER: ${{ inputs.provider }}
        LLM_API_KEY: ${{ inputs.api-key }}
        LLM_MODEL: ${{ inputs.model }}
        LLM_THINKING: ${{ inputs.llm-thinking }}
        AGENT_MODE: ${{ inputs.agent-mode }}
        MAX_STEPS: ${{ inputs.max-steps }}
        STEP_DELAY: ${{ inputs.step-delay }}
        PLATFORM: ios
        DEVICE_TYPE: ${{ inputs.ios-device-type }}
        DEVICE_UDID: ${{ inputs.device-udid || env.IOS_SIMULATOR_UDID }}
        MCP_DEBUG: ${{ inputs.mcp-debug == 'true' && '1' || '0' }}
        MCP_TIMEOUT_MS: ${{ inputs.mcp-timeout-ms }}
      run: appclaw "${{ inputs.goal }}" --platform ios

    # ── Report ────────────────────────────────────────────────────────────────
    - name: Find report path
      id: report-path
      if: always()
      shell: bash
      run: |
        DIR=$(ls -td .appclaw/runs/*/ 2>/dev/null | head -1 || echo "")
        echo "path=${DIR}" >> $GITHUB_OUTPUT
        if [ -n "$DIR" ]; then
          echo "::notice title=AppClaw Report::Report written to ${DIR}"
        fi

    - name: Upload report artifact
      if: ${{ always() && inputs.report == 'true' }}
      uses: actions/upload-artifact@v4
      with:
        name: ${{ inputs.report-name }}
        path: .appclaw/runs/
        if-no-files-found: warn